Skip to main content
POST
/
assistant
/
v1
/
create
curl --request POST \
  --url https://api.langdock.com/assistant/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Document Analyzer",
  "description": "Analyzes and summarizes documents",
  "emoji": "📄",
  "instruction": "You are a helpful assistant that analyzes documents.",
  "creativity": 0.5,
  "dataAnalyst": true
}
'
{
  "status": "success",
  "message": "Assistant created successfully",
  "assistant": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "emojiIcon": "<string>",
    "model": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "temperature": 0.5,
    "inputType": "PROMPT",
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "codeInterpreterEnabled": true,
    "canvasEnabled": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "instruction": "<string>",
    "conversationStarters": [
      "<string>"
    ],
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "slug": "<string>",
        "type": "TEXT",
        "label": "<string>",
        "required": true,
        "order": 1,
        "description": "<string>",
        "options": [
          "<string>"
        ],
        "fileTypes": [
          "<string>"
        ]
      }
    ],
    "attachments": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}
Creates a new assistant in your workspace programmatically. The created assistant can be used via the chat completions endpoint or accessed through the Langdock UI.
Requires an API key with the ASSISTANT_API scope. Created assistants are automatically shared with the API key for use in chat completions.

Request Parameters

ParameterTypeRequiredDescription
namestringYesName of the assistant (1-255 characters)
descriptionstringNoDescription of what the assistant does (max 256 chars)
emojistringNoEmoji icon for the assistant (e.g., ”🤖“)
instructionstringNoSystem prompt/instructions for the assistant (max 16384 chars)
inputTypestringNoInput type: “PROMPT” or “STRUCTURED” (default: “PROMPT”)
modelstringNoModel UUID to use (uses workspace default if not provided)
creativitynumberNoTemperature between 0-1 (default: 0.3)
conversationStartersstring[]NoArray of suggested prompts to help users get started
actionsarrayNoArray of action objects for custom integrations
inputFieldsarrayNoArray of form field definitions (for STRUCTURED input type)
attachmentsstring[]NoArray of attachment UUIDs to include with the assistant
webSearchbooleanNoEnable web search capability (default: false)
imageGenerationbooleanNoEnable image generation capability (default: false)
dataAnalystbooleanNoEnable code interpreter capability (default: false)
canvasbooleanNoEnable canvas capability (default: false)

Actions Configuration

Each action in the actions array should contain:
  • actionId (required) - UUID of the action from an enabled integration
  • requiresConfirmation (optional) - Whether to require user confirmation before executing (default: false)
You can retrieve available actions using the Integrations API. Only actions from integrations enabled in your workspace can be used.

Input Fields Configuration

When using inputType: "STRUCTURED", you can define form fields in the inputFields array:
FieldTypeRequiredDescription
slugstringYesUnique identifier for the field
typestringYesField type (see supported types below)
labelstringYesDisplay label for the field
descriptionstringNoHelp text for the field
requiredbooleanNoWhether the field is required (default: false)
ordernumberYesDisplay order (0-indexed)
optionsstring[]NoOptions for SELECT type fields
fileTypesstring[]NoAllowed file types for FILE type fields
Supported Field Types:
  • TEXT - Single line text input
  • MULTI_LINE_TEXT - Multi-line text area
  • NUMBER - Numeric input
  • CHECKBOX - Boolean checkbox
  • FILE - File upload
  • SELECT - Dropdown selection
  • DATE - Date picker

Obtaining Attachment IDs

To include attachments with your assistant, first upload files using the Upload Attachment API. This will return attachment UUIDs that you can include in the attachments array.

Examples

Creating a Basic Assistant

const axios = require("axios");

async function createBasicAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/api/public/assistant/v1/create",
    {
      name: "Document Analyzer",
      description: "Analyzes and summarizes documents",
      emoji: "📄",
      instruction: "You are a helpful assistant that analyzes documents and provides clear summaries of key information.",
      creativity: 0.5,
      conversationStarters: [
        "Summarize this document",
        "What are the key points?",
        "Extract action items"
      ],
      dataAnalyst: true,
      webSearch: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Assistant created:", response.data.assistant.id);
}

Validation Rules

The API enforces several validation rules:
  • Model - Must be in your workspace’s active models list
  • Actions - Must belong to integrations enabled in your workspace
  • Attachments - Must exist in your workspace and not be deleted
  • Permissions - Your API key must have the createAssistants permission
  • Name - Must be between 1-255 characters
  • Description - Maximum 256 characters
  • Instruction - Maximum 16384 characters
  • Creativity - Must be between 0 and 1

Important Notes

Pre-selected OAuth connections are not supported via the API. Users must configure OAuth connections through the Langdock UI.
  • Created assistants are automatically shared with your API key for use in chat completions
  • The API key creator becomes the owner and can manage the assistant in the UI
  • Attachments are bidirectionally linked to the assistant
  • The assistant type is set to ASSISTANT (not WORKFLOW or PROJECT)
  • createdBy and workspaceId are automatically set from your API key

Response Format

Success Response (201 Created)

{
  status: "success";
  message: "Assistant created successfully";
  assistant: {
    id: string;
    name: string;
    description: string;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
    }>;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

try {
  const response = await axios.post('https://api.langdock.com/api/public/assistant/v1/create', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters:', error.response.data.message);
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - requires ASSISTANT_API scope');
        break;
      case 404:
        console.error('Resource not found (model, action, or attachment)');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

Authorizations

Authorization
string
header
required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json
name
string
required

Name of the assistant

Required string length: 1 - 255
description
string

Description of what the assistant does

Maximum string length: 256
emoji
string

Emoji icon for the assistant (e.g., "🤖")

instruction
string

System prompt/instructions for the assistant

Maximum string length: 16384
inputType
enum<string>
default:PROMPT

Input type for the assistant

Available options:
PROMPT,
STRUCTURED
model
string<uuid>

Model UUID to use (uses workspace default if not provided)

creativity
number
default:0.3

Temperature for response generation

Required range: 0 <= x <= 1
conversationStarters
string[]

Array of suggested prompts to help users get started

actions
object[]

Array of action objects for custom integrations

inputFields
object[]

Array of form field definitions (for STRUCTURED input type)

attachments
string<uuid>[]

Array of attachment UUIDs to include with the assistant

Enable web search capability

imageGeneration
boolean
default:false

Enable image generation capability

dataAnalyst
boolean
default:false

Enable code interpreter capability

canvas
boolean
default:false

Enable canvas capability

Response

Assistant created successfully

status
enum<string>
required
Available options:
success
message
string
required
Example:

"Assistant created successfully"

assistant
object
required