> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assistant Create API

> Create a new Assistant programmatically

<Warning>
  **The Assistants API will be deprecated on 30 April.**

  For new projects, we recommend using the [Agents API](/en/developer/agents-api/agent-create). The Agents API provides native Vercel AI SDK compatibility and removes custom transformations.

  See the [migration guide](/en/developer/assistants-api/assistant-to-agent-migration) to learn about the differences.
</Warning>

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.

<Info>
  Requires an API key with the `AGENT_API` scope. Created Assistants are automatically shared with the API key for use in chat completions.
</Info>

## Request Parameters

| Parameter              | Type      | Required | Description                                                    |
| ---------------------- | --------- | -------- | -------------------------------------------------------------- |
| `name`                 | string    | Yes      | Name of the Assistant (1-80 characters)                        |
| `description`          | string    | No       | Description of what the Assistant does (max 500 chars)         |
| `emoji`                | string    | No       | Emoji icon for the Assistant (e.g., "🤖")                      |
| `instruction`          | string    | No       | System prompt/instructions for the Assistant (max 40000 chars) |
| `inputType`            | string    | No       | Input type: "PROMPT" or "STRUCTURED" (default: "PROMPT")       |
| `model`                | string    | No       | Model identifier (deployment name from the Models API)         |
| `creativity`           | number    | No       | Temperature between 0-1 (default: 0.3)                         |
| `conversationStarters` | string\[] | No       | Array of suggested prompts to help users get started           |
| `actions`              | array     | No       | Array of action objects for custom integrations                |
| `inputFields`          | array     | No       | Array of form field definitions (for STRUCTURED input type)    |
| `attachments`          | string\[] | No       | Array of attachment UUIDs to include with the Assistant        |
| `webSearch`            | boolean   | No       | Enable web search capability (default: false)                  |
| `imageGeneration`      | boolean   | No       | Enable image generation capability (default: false)            |
| `dataAnalyst`          | boolean   | No       | Enable code interpreter capability (default: false)            |
| `canvas`               | boolean   | No       | Enable canvas capability (default: false)                      |
| `extendedThinking`     | boolean   | No       | Enable extended thinking mode (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: true)

<Info>
  Only actions from integrations enabled in your workspace can be used.
</Info>

### Input Fields Configuration

When using `inputType: "STRUCTURED"`, you can define form fields in the `inputFields` array:

| Field         | Type      | Required | Description                                    |
| ------------- | --------- | -------- | ---------------------------------------------- |
| `slug`        | string    | Yes      | Unique identifier for the field                |
| `type`        | string    | Yes      | Field type (see supported types below)         |
| `label`       | string    | Yes      | Display label for the field                    |
| `description` | string    | No       | Help text for the field                        |
| `required`    | boolean   | No       | Whether the field is required (default: false) |
| `order`       | number    | Yes      | Display order (0-indexed)                      |
| `options`     | string\[] | No       | Options for SELECT type fields                 |
| `fileTypes`   | string\[] | No       | Allowed file types for FILE type fields        |
| `emailDomain` | string    | No       | Allowed email domain for EMAIL 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
* `EMAIL` - Email address

## Obtaining Attachment IDs

To include attachments with your Assistant, first upload files using the [Upload Attachment API](/en/developer/assistants-api/upload-attachments). This will return attachment UUIDs that you can include in the `attachments` array.

## Examples

### Creating a Basic Assistant

```javascript theme={null}
const axios = require("axios");

async function createBasicAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/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-80 characters
* **Description** - Maximum 500 characters
* **Instruction** - Maximum 40000 characters
* **Creativity** - Must be between 0 and 1

## Important Notes

<Warning>
  Pre-selected OAuth connections are not supported via the API. Users must configure OAuth connections through the Langdock UI.
</Warning>

* 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 `AGENT` (not `WORKFLOW` or `PROJECT`)
* `createdBy` and `workspaceId` are automatically set from your API key

## Response Format

### Success Response (201 Created)

```typescript theme={null}
{
  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;
    extendedThinking: 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;
      emailDomain: string | null;
    }>;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}
```

## Error Handling

```typescript theme={null}
try {
  const response = await axios.post('https://api.langdock.com/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 AGENT_API scope');
        break;
      case 404:
        console.error('Resource not found (model, action, or attachment)');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}
```

## Migrating to Agents API

The new Agents API offers improved compatibility with modern AI SDKs. The create endpoint has similar functionality with updated parameter names.

See the equivalent endpoint in the Agents API:

* [Agent Create API](/en/developer/agents-api/agent-create) - Uses `agentId` instead of `assistantId`

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml POST /assistant/v1/create
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
security:
  - bearerAuth: []
paths:
  /assistant/v1/create:
    post:
      tags:
        - Assistant Build
      summary: '[Deprecated] Creates a new assistant'
      description: >-
        This endpoint is deprecated. Please use /agent/v1/create for new
        integrations. Creates a new assistant in your workspace
        programmatically.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            examples:
              basicAgent:
                summary: Basic agent with minimal configuration
                value:
                  name: Document Analyzer
                  description: Analyzes and summarizes documents
                  emoji: 📄
                  instruction: You are a helpful agent that analyzes documents.
                  creativity: 0.5
                  dataAnalyst: true
              agentWithActions:
                summary: Agent with actions and capabilities
                value:
                  name: Email Agent
                  description: Helps manage and send emails
                  emoji: 📧
                  instruction: You are an email agent.
                  model: gpt-5-mini
                  creativity: 0.7
                  conversationStarters:
                    - Send an email to my team
                    - Draft a follow-up email
                  actions:
                    - actionId: action-uuid
                      requiresConfirmation: true
                  webSearch: true
              structuredInputAgent:
                summary: Agent with structured input fields
                value:
                  name: Invoice Analyzer
                  description: Analyzes invoices
                  emoji: 🧾
                  instruction: You are an invoice analysis agent.
                  inputType: STRUCTURED
                  inputFields:
                    - slug: customer_name
                      type: TEXT
                      label: Customer Name
                      description: Enter customer name
                      required: true
                      order: 0
                      options: []
                    - slug: invoice_date
                      type: DATE
                      label: Invoice Date
                      required: true
                      order: 1
                      options: []
                  dataAnalyst: true
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Name of the agent
                description:
                  type: string
                  maxLength: 256
                  description: Description of what the agent does
                emoji:
                  type: string
                  description: Emoji icon for the agent (e.g., "🤖")
                instruction:
                  type: string
                  maxLength: 16384
                  description: System prompt/instructions for the agent
                inputType:
                  type: string
                  enum:
                    - PROMPT
                    - STRUCTURED
                  default: PROMPT
                  description: Input type for the agent
                model:
                  type: string
                  description: Model ID to use (see Models for Agent API)
                creativity:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.3
                  description: Temperature for response generation
                conversationStarters:
                  type: array
                  items:
                    type: string
                  description: Array of suggested prompts to help users get started
                actions:
                  type: array
                  items:
                    type: object
                    required:
                      - actionId
                    properties:
                      actionId:
                        type: string
                        format: uuid
                        description: UUID of the action from an enabled integration
                      requiresConfirmation:
                        type: boolean
                        default: false
                        description: Whether to require user confirmation before executing
                  description: Array of action objects for custom integrations
                inputFields:
                  type: array
                  items:
                    type: object
                    required:
                      - slug
                      - type
                      - label
                      - order
                    properties:
                      slug:
                        type: string
                        description: Unique identifier for the field
                      type:
                        type: string
                        enum:
                          - TEXT
                          - MULTI_LINE_TEXT
                          - NUMBER
                          - CHECKBOX
                          - FILE
                          - SELECT
                          - DATE
                        description: Field type
                      label:
                        type: string
                        description: Display label for the field
                      description:
                        type: string
                        description: Help text for the field
                      required:
                        type: boolean
                        default: false
                        description: Whether the field is required
                      order:
                        type: integer
                        minimum: 0
                        description: Display order (0-indexed)
                      options:
                        type: array
                        items:
                          type: string
                        description: Options for SELECT type fields
                      fileTypes:
                        type: array
                        items:
                          type: string
                        description: Allowed file types for FILE type fields
                  description: Array of form field definitions (for STRUCTURED input type)
                attachments:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Array of attachment UUIDs to include with the agent
                webSearch:
                  type: boolean
                  default: false
                  description: Enable web search capability
                imageGeneration:
                  type: boolean
                  default: false
                  description: Enable image generation capability
                dataAnalyst:
                  type: boolean
                  default: false
                  description: Enable code interpreter capability
                canvas:
                  type: boolean
                  default: false
                  description: Enable canvas capability
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - agent
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                    example: Assistant created successfully
                  assistant:
                    $ref: '#/components/schemas/AssistantDetails'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: object
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '403':
          description: Insufficient permissions - requires AGENT_API scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Resource not found (model, action, or attachment)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
      deprecated: true
components:
  schemas:
    AssistantDetails:
      type: object
      required:
        - id
        - name
        - emojiIcon
        - model
        - temperature
        - inputType
        - webSearchEnabled
        - imageGenerationEnabled
        - codeInterpreterEnabled
        - canvasEnabled
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        name:
          type: string
          description: Name of the agent
        description:
          type: string
          nullable: true
          description: Description of what the agent does
        instruction:
          type: string
          nullable: true
          description: System prompt/instructions for the agent
        emojiIcon:
          type: string
          nullable: true
          description: Emoji icon for the agent
        model:
          type: string
          description: Model ID to use (see Models for Agent API)
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature/creativity setting for response generation
        conversationStarters:
          type: array
          items:
            type: string
          description: Array of suggested prompts to help users get started
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
          description: Input type for the agent
        webSearchEnabled:
          type: boolean
          description: Whether web search capability is enabled
        imageGenerationEnabled:
          type: boolean
          description: Whether image generation capability is enabled
        codeInterpreterEnabled:
          type: boolean
          description: Whether code interpreter/data analyst capability is enabled
        canvasEnabled:
          type: boolean
          description: Whether canvas capability is enabled
        extendedThinking:
          type: boolean
          description: >-
            Whether extended thinking is enabled. Only supported on models that
            expose this capability; enabling it on an unsupported model returns
            a 400 error.
        actions:
          type: array
          items:
            type: object
            required:
              - actionId
              - requiresConfirmation
            properties:
              actionId:
                type: string
                format: uuid
                description: UUID of the action from an enabled integration
              requiresConfirmation:
                type: boolean
                description: Whether user confirmation is required before executing
          description: Array of action objects for custom integrations
        inputFields:
          type: array
          items:
            type: object
            required:
              - slug
              - type
              - label
              - required
              - order
            properties:
              slug:
                type: string
                description: Unique identifier for the field
              type:
                type: string
                enum:
                  - TEXT
                  - MULTI_LINE_TEXT
                  - NUMBER
                  - CHECKBOX
                  - FILE
                  - SELECT
                  - DATE
                description: Field type
              label:
                type: string
                description: Display label for the field
              description:
                type: string
                description: Help text for the field
              required:
                type: boolean
                description: Whether the field is required
              order:
                type: integer
                minimum: 0
                description: Display order (0-indexed)
              options:
                type: array
                items:
                  type: string
                description: Options for SELECT type fields
              fileTypes:
                type: array
                items:
                  type: string
                nullable: true
                description: Allowed file types for FILE type fields
          description: Array of form field definitions (for STRUCTURED input type)
        attachments:
          type: array
          items:
            type: string
            format: uuid
          description: Array of attachment UUIDs associated with the agent
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the agent was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the agent was last updated
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````