Agent Create API

Creates a new agent

curl --request POST \
  --url https://api.langdock.com/agent/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "instruction": "<string>",
  "inputType": "PROMPT",
  "emoji": "<string>",
  "model": "<string>",
  "creativity": 0.3,
  "conversationStarters": [],
  "actions": [],
  "inputFields": [],
  "webSearch": false,
  "imageGeneration": false,
  "dataAnalyst": false,
  "extendedThinking": false,
  "attachments": [],
  "knowledgeFolderIds": []
}
'

import requests

url = "https://api.langdock.com/agent/v1/create"

payload = {
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "inputType": "PROMPT",
    "emoji": "<string>",
    "model": "<string>",
    "creativity": 0.3,
    "conversationStarters": [],
    "actions": [],
    "inputFields": [],
    "webSearch": False,
    "imageGeneration": False,
    "dataAnalyst": False,
    "extendedThinking": False,
    "attachments": [],
    "knowledgeFolderIds": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    instruction: '<string>',
    inputType: 'PROMPT',
    emoji: '<string>',
    model: '<string>',
    creativity: 0.3,
    conversationStarters: [],
    actions: [],
    inputFields: [],
    webSearch: false,
    imageGeneration: false,
    dataAnalyst: false,
    extendedThinking: false,
    attachments: [],
    knowledgeFolderIds: []
  })
};

fetch('https://api.langdock.com/agent/v1/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.langdock.com/agent/v1/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'instruction' => '<string>',
    'inputType' => 'PROMPT',
    'emoji' => '<string>',
    'model' => '<string>',
    'creativity' => 0.3,
    'conversationStarters' => [
        
    ],
    'actions' => [
        
    ],
    'inputFields' => [
        
    ],
    'webSearch' => false,
    'imageGeneration' => false,
    'dataAnalyst' => false,
    'extendedThinking' => false,
    'attachments' => [
        
    ],
    'knowledgeFolderIds' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.langdock.com/agent/v1/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.langdock.com/agent/v1/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.langdock.com/agent/v1/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "<string>",
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "emojiIcon": "<string>",
    "model": "<string>",
    "temperature": 0.5,
    "conversationStarters": [
      "<string>"
    ],
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "canvasEnabled": true,
    "extendedThinking": true,
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "label": "<string>",
        "description": "<string>",
        "required": true,
        "order": 1
      }
    ],
    "attachments": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "knowledgeFolderIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

POST

agent

create

Creates a new agent

curl --request POST \
  --url https://api.langdock.com/agent/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "instruction": "<string>",
  "inputType": "PROMPT",
  "emoji": "<string>",
  "model": "<string>",
  "creativity": 0.3,
  "conversationStarters": [],
  "actions": [],
  "inputFields": [],
  "webSearch": false,
  "imageGeneration": false,
  "dataAnalyst": false,
  "extendedThinking": false,
  "attachments": [],
  "knowledgeFolderIds": []
}
'

import requests

url = "https://api.langdock.com/agent/v1/create"

payload = {
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "inputType": "PROMPT",
    "emoji": "<string>",
    "model": "<string>",
    "creativity": 0.3,
    "conversationStarters": [],
    "actions": [],
    "inputFields": [],
    "webSearch": False,
    "imageGeneration": False,
    "dataAnalyst": False,
    "extendedThinking": False,
    "attachments": [],
    "knowledgeFolderIds": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    instruction: '<string>',
    inputType: 'PROMPT',
    emoji: '<string>',
    model: '<string>',
    creativity: 0.3,
    conversationStarters: [],
    actions: [],
    inputFields: [],
    webSearch: false,
    imageGeneration: false,
    dataAnalyst: false,
    extendedThinking: false,
    attachments: [],
    knowledgeFolderIds: []
  })
};

fetch('https://api.langdock.com/agent/v1/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.langdock.com/agent/v1/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'instruction' => '<string>',
    'inputType' => 'PROMPT',
    'emoji' => '<string>',
    'model' => '<string>',
    'creativity' => 0.3,
    'conversationStarters' => [
        
    ],
    'actions' => [
        
    ],
    'inputFields' => [
        
    ],
    'webSearch' => false,
    'imageGeneration' => false,
    'dataAnalyst' => false,
    'extendedThinking' => false,
    'attachments' => [
        
    ],
    'knowledgeFolderIds' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.langdock.com/agent/v1/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.langdock.com/agent/v1/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.langdock.com/agent/v1/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"instruction\": \"<string>\",\n  \"inputType\": \"PROMPT\",\n  \"emoji\": \"<string>\",\n  \"model\": \"<string>\",\n  \"creativity\": 0.3,\n  \"conversationStarters\": [],\n  \"actions\": [],\n  \"inputFields\": [],\n  \"webSearch\": false,\n  \"imageGeneration\": false,\n  \"dataAnalyst\": false,\n  \"extendedThinking\": false,\n  \"attachments\": [],\n  \"knowledgeFolderIds\": []\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "<string>",
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "emojiIcon": "<string>",
    "model": "<string>",
    "temperature": 0.5,
    "conversationStarters": [
      "<string>"
    ],
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "canvasEnabled": true,
    "extendedThinking": true,
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "label": "<string>",
        "description": "<string>",
        "required": true,
        "order": 1
      }
    ],
    "attachments": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "knowledgeFolderIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

⚠️ Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public

This is the new Agents API with native Vercel AI SDK compatibility. If you’re using the legacy Assistants API, see the migration guide.

Creates a new agent in your workspace programmatically. The created agent can be used via the chat completions endpoint or accessed through the Langdock UI.

Requires an API key with the AGENT_API scope. Created agents are automatically shared with the API key for use in chat completions.

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the agent (1-80 characters)
`description`	string	No	Description of what the agent does (max 800 chars)
`emoji`	string	No	Emoji icon for the agent (max 16 chars, e.g., ”🤖“)
`instruction`	string	No	System prompt/instructions for the agent (max 50000 chars)
`inputType`	string	No	Input type: “PROMPT”, “STRUCTURED”, “INTEGRATION”, “SCHEDULED”, or “WEBHOOK” (default: “PROMPT”)
`model`	string	No	Model identifier to use (deployment name from the Models API). Uses workspace default if not provided
`creativity`	number	No	Temperature between 0-1 (default: 0.3)
`conversationStarters`	string[]	No	Array of suggested prompts to help users get started (max 20, each 1-255 chars)
`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 up to 50 attachment UUIDs to include with the agent
`knowledgeFolderIds`	string[]	No	Array of Folder UUIDs to include with the agent
`webSearch`	boolean	No	Enable web search capability (default: false)
`imageGeneration`	boolean	No	Enable image generation capability (default: false)
`dataAnalyst`	boolean	No	Accepted for compatibility. See warning below
`extendedThinking`	boolean	No	Enable extended thinking mode (default: false)

The dataAnalyst parameter is deprecated and has no effect. Requests that include it still succeed for backward compatibility, but Langdock ignores the value and does not enable file or code execution. Omit this parameter from new integrations.

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)

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:

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 and MULTI_SELECT type fields
`fileTypes`	string	No	Allowed file types for FILE type fields (nullable)
`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
MULTI_SELECT - Multi-select
DATE - Date picker
EMAIL - Email address

Obtaining Attachment IDs

To include attachments with your agent, 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 Agent

const axios = require("axios");

async function createBasicAgent() {
  const response = await axios.post(
    "https://api.langdock.com/agent/v1/create",
    {
      name: "Document Analyzer",
      description: "Analyzes and summarizes documents",
      emoji: "📄",
      instruction: "You are a helpful agent 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"
      ],
      webSearch: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent created:", response.data.agent.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
Folders - Must exist in your workspace and not be deleted
Permissions - Your API key must have the createAgents permission
Name - Must be between 1-80 characters
Description - Maximum 800 characters
Instruction - Maximum 50000 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 agents are automatically shared with your API key for use in chat completions
The API key creator becomes the owner and can manage the agent in the UI
Attachments are bidirectionally linked to the agent
createdBy and workspaceId are automatically set from your API key

Response Format

Success Response (201 Created)

{
  status: "success";
  message: "Agent created successfully";
  agent: {
    id: string;
    name: string;
    description: string | null;
    instruction: string | null;
    emojiIcon: string | null;
    model: string | null;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
      label: string;
      description: string | null;
      required: boolean;
      order: number;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

try {
  const response = await axios.post('https://api.langdock.com/agent/v1/create', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters or resource not found:', 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 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

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.

Authorizations

Authorization

string

header

required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json

name

string

required

Name of the agent or assistant

Required string length: 1 - 80

description

string

Description of what the agent or assistant does. Send an empty string to clear it during an update.

Maximum string length: 800

instruction

string

System prompt or instructions. Send an empty string to clear it during an update.

Maximum string length: 50000

inputType

enum<string>

default:PROMPT

Input type

Available options:

PROMPT,

STRUCTURED,

INTEGRATION,

SCHEDULED,

WEBHOOK

emoji

string | null

Emoji icon

Maximum string length: 16

model

string

Model deployment name

creativity

number

default:0.3

Temperature for response generation

Required range: 0 <= x <= 1

conversationStarters

string[]

Suggested prompts

Maximum array length: 20

Required string length: 1 - 255

actions

object[]

Actions that the agent or assistant can use

Show child attributes

inputFields

object[]

Form fields for STRUCTURED input

Show child attributes

webSearch

boolean

default:false

Enable web search

imageGeneration

boolean

default:false

Enable image generation

dataAnalyst

boolean

default:false

deprecated

Deprecated. Accepted for compatibility and ignored.

extendedThinking

boolean

default:false

Enable extended thinking

attachments

string<uuid>[]

Attachment UUIDs

Maximum array length: 50

knowledgeFolderIds

string<uuid>[]

Folder UUIDs

Response

201 - application/json

Agent created successfully

status

enum<string>

required

Available options:

success

message

string

required

agent

object

required

Show child attributes

Agent Get API Agent Update API

⌘I

Overview

Completion API

Embedding API

Agents API

Assistants API (Deprecating)

Integrations API

Skills API

Knowledge Folder API

Usage Export API

User Management API

Audit Logs API

Agent Create API

Request Parameters

Actions Configuration

Input Fields Configuration

Obtaining Attachment IDs

Examples

Creating a Basic Agent

Validation Rules

Important Notes

Response Format

Success Response (201 Created)

Error Handling

Authorizations

Body

Response

​Request Parameters

​Actions Configuration

​Input Fields Configuration

​Obtaining Attachment IDs

​Examples

​Creating a Basic Agent

​Validation Rules

​Important Notes

​Response Format

​Success Response (201 Created)

​Error Handling

Authorizations

Body

Response

Request Parameters

Actions Configuration

Input Fields Configuration

Obtaining Attachment IDs

Examples

Creating a Basic Agent

Validation Rules

Important Notes

Response Format

Success Response (201 Created)

Error Handling