Assistant API
Creates a model response for a given Assistant.
Creates a model response for a given assistant id, or pass in an Assistant configuration that should be used for your request.
To use the API you need an API key. You can create API Keys in your Workspace settings. If you want to interact with an existing Assistant, make sure to “Share” access to the assistant with the created API Key (Assistants > Your Assistant > Share).
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assistantId | string | One of assistantId/assistant required | ID of an existing assistant to use |
assistant | object | One of assistantId/assistant required | Configuration for a new assistant |
messages | array | Yes | Array of message objects with role and content |
output | object | No | Structured output format specification |
Message Format
Each message in the messages
array should contain:
role
(required) - One of: “user”, “assistant”, or “tool”content
(required) - The message content as a stringattachmentIds
(optional) - Array of UUID strings identifying attachments for this message
Assistant Configuration
When creating a temporary assistant, you can specify:
name
(required) - Name of the assistant (max 64 chars)instructions
(required) - System instructions (max 16384 chars)description
- Optional description (max 256 chars)temperature
- Temperature between 0-1model
- Model ID to use (see Available Models for options)capabilities
- Enable features like web search, data analysis, image generationactions
- Custom API integrationsvectorDb
- Vector database connectionsknowledgeFolderIds
- IDs of knowledge folders to useattachmentIds
- Array of UUID strings identifying attachments to use
You can retrieve a list of available models using the Models API. This is useful when you want to see which models you can use in your assistant configuration.
Structured Output
You can specify a structured output format using the optional output
parameter:
Field | Type | Description |
---|---|---|
type | ”object” | “array” | “enum” | The type of structured output |
schema | object | JSON Schema definition for the output (for object/array types) |
enum | string[] | Array of allowed values (for enum type) |
The output
parameter behavior depends on the specified type:
type: "object"
with no schema: Forces the response to be a single JSON object (no specific structure)type: "object"
with schema: Forces the response to match the provided JSON Schematype: "array"
with schema: Forces the response to be an array of objects matching the provided schematype: "enum"
: Forces the response to be one of the values specified in theenum
array
You can use tools like easy-json-schema to generate JSON Schemas from example JSON objects.
Obtaining Attachment IDs
To use attachments in your assistant conversations, you first need to upload the files using the Upload Attachment API. This will return an attachmentId
for each file, which you can then include in the attachmentIds
array in your assistant or message configuration.
Examples
Using an Existing Assistant
Using a temporary Assistant configuration
Using Structured Output with Schema
Using Structured Output with Enum
Rate limits
The rate limit for the Assistant Completion endpoint is 500 RPM (requests per minute) and 60.000 TPM (tokens per minute). Rate limits are defined at the workspace level - and not at an API key level. Each model has its own rate limit. If you exceed your rate limit, you will receive a 429 Too Many Requests
response.
Please note that the rate limits are subject to change, refer to this documentation for the most up-to-date information. In case you need a higher rate limit, please contact us at support@langdock.com.
Response Format
The API returns an object containing:
Standard Result
The result
array contains the message exchange between user and assistant, including any tool calls that were made. This is always present in the response.
Structured Output
When the request includes an output
parameter, the response will also include an output
field. The type of this field depends on the requested output format:
- If
output.type
was “object”: Returns a JSON object (with schema validation if schema was provided) - If
output.type
was “array”: Returns an array (with schema validation if schema was provided) - If
output.type
was “enum”: Returns a string matching one of the provided enum values
For example, when requesting weather data with structured output:
Error Handling
Body
ID of an existing assistant to use
Specification for structured output format. When type is object/array and no schema is provided, the response will be JSON but can have any structure. When the type is enum, you must provide an enum parameter with an array of strings as options.
Response
Present when output parameter was specified in the request
Was this page helpful?