POST
/
assistant
/
v1
/
chat
/
completions

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

ParameterTypeRequiredDescription
assistantIdstringOne of assistantId/assistant requiredID of an existing assistant to use
assistantobjectOne of assistantId/assistant requiredConfiguration for a new assistant
messagesarrayYesArray of message objects with role and content

​
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-1
  • model - Model ID to use (see Available Models for options)
  • capabilities - Enable features like web search, data analysis, image generation
  • actions - Custom API integrations
  • vectorDb - Vector database connections
  • knowledgeFolderIds - IDs of knowledge folders 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.

​
Examples

​
Using an Existing Assistant

const axios = require("axios");

async function chatWithAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistantId: "asst_123",
      messages: [
        {
          role: "user",
          content: "Hello! Can you help me with a task?",
        },
      ],
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

​
Using a temporary Assistant configuration

const axios = require("axios");

async function chatWithNewAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Math Tutor",
        instructions: "You are a helpful math tutor who explains concepts clearly",
        temperature: 0.7,
        model: "gpt-4o",
        capabilities: {
          webSearch: true,
          dataAnalyst: true,
        },
      },
      messages: [
        {
          role: "user",
          content: "Can you explain quadratic equations?",
        },
      ],
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

​
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 array of results, where each result contains:

{
  result: Array<{
    id: string;
    role: "tool" | "assistant";
    content: Array<{
      type: string;
      toolCallId?: string;
      toolName?: string;
      result?: object;
      args?: object;
      text?: string;
    }>;
  }>;
}

​
Error Handling

try {
  const response = await axios.post('https://api.langdock.com/assistant/v1/chat/completions', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters:', error.response.data.message);
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

Body

application/json
assistantId
string | null
required

ID of an existing assistant to use

messages
object[]
required
assistant
object

Response

200 - application/json
result
object[]
required

Was this page helpful?

Anthropic MessagesIntroduction to Search