Agent Get API

Retrieve details of an existing agent

GET /agent/v1/get

Retrieves details of an existing agent

cURL

curl --request GET \
  --url https://api.langdock.com/agent/v1/get \
  --header 'Authorization: Bearer <token>'

200

{
  "status": "<string>",
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "emojiIcon": "<string>",
    "model": "<string>",
    "temperature": 0.5,
    "conversationStarters": [
      "<string>"
    ],
    "inputType": "PROMPT",
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "canvasEnabled": true,
    "extendedThinking": true,
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "type": "TEXT",
        "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"
  }
}

Retrieves the current settings and details available for an existing agent in your workspace. The endpoint returns the agent’s active (published) version. If the agent has never been published, it returns the current draft instead.

Before You Start

• API key scope: Requires an API key with the Agent API scope and access to the agent you want to retrieve.
• Legacy Assistants API: This is the new Agents API with native Vercel AI SDK compatibility. If you’re using the legacy Assistants API, see the migration guide.

Base URL

https://api.langdock.com/agent/v1/get

Dedicated deployments

Replace api.langdock.com with <your-deployment-url>/api/public in all requests.

Parameters

Parameter	Type	Required	Description
agentId	string	Yes	UUID of the agent to retrieve

Examples

Basic Retrieval

const axios = require("axios");

async function getAgent() {
  const response = await axios.get(
    "https://api.langdock.com/agent/v1/get",
    {
      params: {
        agentId: "550e8400-e29b-41d4-a716-446655440000"
      },
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log("Agent details:", response.data.agent);
}

Validation Rules

The API enforces the following validation rules:

• Agent access - Your API key must have access to the agent
• Workspace match - Agent must belong to the same workspace as your API key

Response Format

Success Response (200 OK)

{
  status: "success";
  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[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

try {
  const response = await axios.get('https://api.langdock.com/agent/v1/get', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid agent ID format');
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - no access to this agent');
        break;
      case 404:
        console.error('Agent not found');
        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"

Query Parameters

agentId · string<uuid> · required

Response

200 - application/json

Agent retrieved successfully

status · string · required

agent · object · required

Show child attributes