Skip to main content
API docs by Redocly

Devs.ai API (1.0)

Download OpenAPI specification:Download

Create New AI

Creates a new AI specified by the given identifier.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
src
required
string

Url of the avatar image.

name
required
string

Display name of the AI

introduction
string

Text the AI uses as the greeting

description
required
string

Short description of the AI

instructions
required
string

Instructions that define the AI.

seed
string

A sample conversation between a human and the AI.

modelId
string

Identifier of the LLM to use for this AI.

visibility
string (AIVisibility)
Enum: "PRIVATE" "GROUP" "ORGANIZATION" "ANYONE_WITH_LINK"

Visibility level controlling who can access the AI. PRIVATE: Only the owner can access. GROUP: Only specified groups can access. ORGANIZATION: Anyone in the organization can access. ANYONE_WITH_LINK: Anyone with the link can access.

listInOrgCatalog
boolean

Whether to list this AI in the organization's catalog

generateCitations
boolean

Whether the AI should generate citations for its responses

chatLogsVisible
boolean

Whether chat logs should be visible to company admins.

intermediateStepsVisible
boolean

Whether intermediate reasoning steps should be visible during chat.

object (AIModelOptions)

Configuration options for the AI model's behavior

object (AIProfile)

Responses

Request samples

Content type
application/json
{
  • "src": "string",
  • "name": "string",
  • "introduction": "string",
  • "description": "string",
  • "instructions": "string",
  • "seed": "string",
  • "modelId": "string",
  • "visibility": "PRIVATE",
  • "listInOrgCatalog": true,
  • "generateCitations": true,
  • "chatLogsVisible": true,
  • "intermediateStepsVisible": true,
  • "options": {
    },
  • "profile": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "src": "string",
  • "profile": {
    },
  • "userName": "string",
  • "categoryId": "string",
  • "messageCount": 0,
  • "rating": 0,
  • "ratingCount": 0
}

Get AI Details

Retrieves details of the AI specified by the given identifier.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI whose details are to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "src": "string",
  • "profile": {
    },
  • "userName": "string",
  • "categoryId": "string",
  • "messageCount": 0,
  • "rating": 0,
  • "ratingCount": 0
}

Approve an AI

Marks an AI as approved by the organization.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI to be approved.

Responses

Get all chats for the AI

Retrieves a list of all chat sessions associated with the given AI identifier.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI whose chats are to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new chat session for the AI

Creates a new chat session associated with the given AI identifier and returns the created chat session data.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI with which the chat session is to be associated.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "userId": "string",
  • "pinPosition": 0,
  • "ai": {
    }
}

List data sources for the AI

Retrieves a list of data sources associated with the given AI identifier.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI whose data sources are to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Add an existing data source to the specified AI

Associates an existing data source with the specified AI.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The unique identifier for the AI to which the data source is to be added.

Request Body schema: application/json
required
dataSourceId
required
string

The unique identifier of the existing data source to be added.

Responses

Request samples

Content type
application/json
{
  • "dataSourceId": "string"
}

Response samples

Content type
application/json
{
  • "aiId": "string",
  • "dataSource": {
    }
}

Create a new API data source for the specified AI

Adds a new API data source with a specified name and JSON payload for the given AI.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The unique identifier for the AI.

Request Body schema: application/json
required
name
required
string

Name of the data source.

data
required
object

The JSON payload to be used as the data source's knowledge.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "aiId": "string",
  • "dataSourceId": "string"
}

Adds a file upload data source for the specified AI. Max file size: 4.5Mb.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The unique identifier for the AI.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "aiId": "string",
  • "dataSourceId": "string"
}

Revoke AI approval

Revokes the organization approval for an AI.

Authorizations:
ApiKeyAuth
path Parameters
aiId
required
string

The identifier of the AI whose approval is to be revoked.

Responses

Get a chat session

Retrieves the chat session with the specified ID.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "userId": "string",
  • "pinPosition": 0,
  • "ai": {
    },
  • "messages": [
    ]
}

Message a chat session

Send a message to a chat session with an AI.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session.

Request Body schema: application/json
required
date
required
string <date-time>

The date and time of the chat from the perspective of the user. This may be different from the server time for the AI.

required
string or (Array of ComplexMessageContent (TextMessageContent (object) or IdMessageContent (object) or UrlMessageContent (object)))

Message to send to the AI. Can be a string for simple text messages, or a ComplexMessageContent array that includes text and file references (images, documents, audio, video).

Responses

Request samples

Content type
application/json
Example
{
  • "date": "2024-01-15T10:30:00Z",
  • "prompt": "Hello, how are you?"
}

Delete a chat session

Deletes the chat session with the specified ID.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session to delete.

Responses

Duplicate a chat session

Creates a duplicate of the chat session with the specified ID.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session to duplicate.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "userId": "string",
  • "pinPosition": 0,
  • "ai": {
    },
  • "messages": [
    ]
}

Reset a chat session

Resets the chat session with the specified ID, clearing its current state or content.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session to reset.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "userId": "string",
  • "pinPosition": 0,
  • "ai": {
    },
  • "messages": [
    ]
}

Submit tool outputs (e.g., input field responses)

When the AI requests user input through tool calls (e.g., asking the user to fill in form fields), use this endpoint to submit the user's responses. The AI will receive these outputs and continue the conversation. Listen for 'tool.call' events in the chat stream to know when input is needed.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session.

Request Body schema: application/json
required
systemMessageId
required
string

The ID of the system message that requested the tool outputs (the message containing the tool calls).

required
Array of objects (ToolOutput)

Array of tool outputs, one for each tool call that needs a response.

object (ChatOptions)

Responses

Request samples

Content type
application/json
Example

Example of submitting a user's name when the AI requests it.

{
  • "systemMessageId": "msg_abc123",
  • "outputs": [
    ]
}

Upload a file to a chat session

Uploads a file that can be referenced in messages sent to this chat. Max file size: 5MB. After uploading, use the returned file ID to reference it in the prompt field using ComplexMessageContent.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session.

Request Body schema: multipart/form-data
required
file
required
string <binary>

The file to upload.

source
string
Enum: "USER" "SYSTEM"

The source of the file. Defaults to USER if not specified.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "source": "USER",
  • "filename": "string",
  • "size": 0,
  • "mimeType": "string",
  • "url": "string",
  • "metadata": { },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "status": "UPLOADED"
}

List files in a chat session

Retrieves a list of all files associated with the specified chat session.

Authorizations:
ApiKeyAuth
path Parameters
chatId
required
string

The unique identifier of the chat session.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List all data sources

Retrieves a list of data sources associated which the user has access to.

Authorizations:
ApiKeyAuth
query Parameters
name
string

The name of the data source.

type
string
Enum: "WEB_URL" "GOOGLE_DRIVE" "ONEDRIVE" "FILE_UPLOAD" "API"

The type of the data source. One of: WEB_URL, GOOGLE_DRIVE, ONEDRIVE, FILE_UPLOAD, API.

orderBy
string^[+-](createdAt|lastIndexedAt|usageCount)$

Order by field and direction. Prefix field name with '+' for ascending or '-' for descending order. Allowed fields: createdAt, lastIndexedAt, usageCount.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete a Data Source

Deletes a specific data source associated with the given AI identifier.

Authorizations:
ApiKeyAuth
path Parameters
dataSourceId
required
string

The unique identifier of the data source to be deleted.

Responses

Refresh a Data Source

This endpoint refreshes the specified data source.

Authorizations:
ApiKeyAuth
path Parameters
dataSourceId
required
string

The unique identifier of the data source to be refreshed.

query Parameters
forceRefresh
boolean

Indicates if the data source should be refreshed even if the content has not been updated

Responses

Create a new group

Creates a new group with the specified details.

Request Body schema: application/json
required
name
required
string

Name of the group.

availability
required
string (GroupAvailability)
Enum: "EVERYONE" "RESTRICTED"

Availability status of the group.

memberEmails
required
string

A comma-separated list of emails of users who should be added to the group.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "availability": "EVERYONE",
  • "memberEmails": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "orgId": "string",
  • "ownerUserId": "string",
  • "name": "string",
  • "availability": "EVERYONE",
  • "users": [
    ]
}

Update a group

Updates the details of a specific group and manages its member list.

path Parameters
groupId
required
string

The unique identifier of the group to update.

Request Body schema: application/json
required
name
string

Name of the group.

availability
string (GroupAvailability)
Enum: "EVERYONE" "RESTRICTED"

Availability status of the group.

memberEmailsToAdd
string

A comma-separated list of emails of users to be added to the group.

memberEmailsToRemove
Array of strings

A comma-separated list of emails of users to be removed from the group.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "availability": "EVERYONE",
  • "memberEmailsToAdd": "string",
  • "memberEmailsToRemove": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "orgId": "string",
  • "ownerUserId": "string",
  • "name": "string",
  • "availability": "EVERYONE",
  • "users": [
    ]
}

Delete a group

Deletes the group with the specified identifier.

path Parameters
groupId
required
string

The unique identifier of the group to delete.

Responses

Leave a group

Allows the current user to leave the group specified by the groupId.

path Parameters
groupId
required
string

The unique identifier of the group to leave.

Responses

List AIs

query Parameters
scope
string (ListAIsRequestScope)
Enum: "PRIVATE" "OWNED" "GROUP" "SHARED" "ORGANIZATION" "PUBLIC" "ALL"

The scope to filter results by

groupId
string

The id of a group to filter results by

categoryId
string

The id of a category to filter results by

approvedByOrg
boolean

Filter results by whether the AI has been approved by the organization.

search
string

Search term

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get all chats for the User

Retrieves a list of all chat sessions associated with the current user

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get groups of the current user

Retrieves a list of groups associated with the current user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get organization usage metrics by AI

Returns the usage metrics of the organization broken down by AI.

Responses

Response samples

Content type
application/json
{
  • "orgUsage": {
    },
  • "aiUsages": [
    ]
}

Get organization usage metrics

Returns usage metrics for the organization.

Responses

Response samples

Content type
application/json
{
  • "orgId": "string",
  • "dataTokensUsed": 0,
  • "dataUsageTokenLimit": 0,
  • "apiTokensUsed": 0,
  • "apiUsageTokenLimit": 0
}

Create a file record or upload a file

This endpoint supports two modes: 1) Create a file record with metadata (application/json), or 2) Upload a file directly (multipart/form-data). When creating a record, you'll need to upload the actual file separately. When uploading directly, the file is uploaded immediately.

Authorizations:
ApiKeyAuth
Request Body schema:
required

This endpoint supports two modes: Create a file record with metadata (application/json), or upload a file directly (multipart/form-data).

filename
required
string

The name of the file.

size
required
integer

The size of the file in bytes.

mimeType
required
string

The MIME type of the file.

metadata
object or null

Additional metadata associated with the file.

Responses

Request samples

Content type
{
  • "filename": "string",
  • "size": 0,
  • "mimeType": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "source": "USER",
  • "filename": "string",
  • "size": 0,
  • "mimeType": "string",
  • "url": "string",
  • "metadata": { },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "status": "UPLOADED"
}

Create a chat completion

Creates a completion for the chat message

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects

A list of messages comprising the conversation so far

model
required
string

ID of the Devs.ai AI or the LLM model to use for completion

stream
boolean
Default: false

Whether to stream the response or not

flowOverride
object

Optional flow override settings

tools
Array of objects

Optional list of tools to use

Responses

Request samples

Content type
application/json
{
  • "messages": [
    ],
  • "model": "string",
  • "stream": false,
  • "flowOverride": { },
  • "tools": [
    ]
}

Response samples

Content type
{
  • "choices": [
    ],
  • "chatId": "string"
}