Agent Update API

​

Before You Start

• API key scope: Requires an API key with the Agent API scope and edit access to the agent you want to update.
• 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.
• Draft settings: Configuration changes apply to the agent’s draft. Access changes take effect immediately and do not require publishing.

​

Base URL

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

​

Update Behavior

• Partial updates - Only fields provided in the request are updated; omitted fields remain unchanged
• Array fields replace - actions, inputFields, conversationStarters, attachments, knowledgeFolderIds, skillIds, subAgents, and workflowIds completely replace existing values when provided
• Empty arrays - Send [] to remove all actions, fields, or attachments. For skillIds, [] detaches every Skill and leaves file template attachments in place. For subAgents and workflowIds, [] detaches every subagent or workflow
• Null handling - Send null for emoji to clear it, and null for icon to remove the uploaded image. Omit icon to keep the current image. Setting icon does not clear emoji. For description and instruction, send an empty string "" to clear them
• Unchanged fields - Fields not included in the request retain their current values

​

Parameters

​

Access Configuration

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "access": {
    "users": [{ "id": "550e8400-e29b-41d4-a716-446655440001", "role": null }],
    "workspace": null
  }
}

​

Actions Configuration

• actionId (required) - UUID of the action
• requiresConfirmation (optional) - Whether to require user confirmation before executing (default: true)

​

Input Fields Configuration

​

Examples

​

Updating Basic Properties

const axios = require("axios");

async function updateAgentName() {
  const response = await axios.patch(
    "https://api.langdock.com/agent/v1/update",
    {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      name: "Advanced Document Analyzer",
      description: "Analyzes documents with enhanced capabilities",
      creativity: 0.7
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent updated:", response.data.message);
}

​

Validation Rules

• Agent access - A personal key can update configuration when its owner can edit the agent, including through a group or the workspace, or when the key has an editor or owner grant. A workspace key needs that grant on the key. The User role and workspace admin status do not grant configuration updates.
• Workspace match - Agent must belong to the same workspace as your API key
• Model - If provided, must be in your workspace’s active models list
• Actions - If provided, the array replaces the draft list. Omit an id to remove it.
• Draft action ids - Missing or soft-deleted ids already on the draft are dropped. Unavailable ids already on the draft stay.
• New action ids - Must exist and belong to integrations enabled in your workspace. Otherwise the request returns 400 with missingActionIds or unavailableActionIds.
• Attachments - If provided, must exist in your workspace and not be deleted
• Folders - If provided, must exist in your workspace and not be deleted
• Skills - If provided, each ID must be a Skill the key owner can attach. File templates are rejected. A missing Skill returns 400 with missingSkillIds. A Skill the owner cannot attach returns 400 with inaccessibleSkillIds
• Draft subagent and workflow ids - Ids already on the draft are kept without a new check. Workflows does not need to be enabled for those ids.
• New subagents - Each new agentId must be an agent in your workspace that the key owner can use. Direct only, attaching the agent to itself, and cycles are rejected. A missing agent returns 400 with missingSubAgentIds. An agent the owner cannot use, or one set to Direct only, returns 400 with inaccessibleSubAgentIds. A cycle or attaching the agent to itself returns 400 with cyclicSubAgentIds
• New workflows - Each new ID must be an active workflow the key owner can use. The key owner needs Workflows enabled. When it is not, new ids return 400 with inaccessibleWorkflowIds. Otherwise a missing workflow, including a template, returns 400 with missingWorkflowIds, and an inactive workflow returns 400 with inactiveWorkflowIds. A workflow the owner cannot use returns 400 with inaccessibleWorkflowIds
• Sharing - Sharing permissions and targets are validated before any changes are saved
• Name - If provided, must be between 1-80 characters
• Description - If provided, maximum 800 characters
• Instruction - If provided, maximum 50000 characters
• Creativity - If provided, must be between 0 and 1

​

Response Format

​

Success Response (200 OK)

{
  status: "success";
  message: "Agent updated 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;
      slug: string;
      options: string[];
      fileTypes: string | null;
      emailDomain: string | null;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    skillIds: string[];
    subAgents: Array<{
      agentId: string;
      requiresConfirmation: boolean;
    }>;
    workflowIds: string[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
    access?: {
      users: Array<{ id: string; role: "user" | "editor" }>;
      groups: Array<{ id: string; role: "user" | "editor" }>;
      workspace: "user" | "editor" | null;
      sharingManagedByAdmin: boolean;
    };
  };
  preservedUnavailableActionIds?: string[];
}

​

Error Handling

try {
  const response = await axios.patch('https://api.langdock.com/agent/v1/update', ...);
} 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('Agent not found or API key does not have edit access');
        break;
      case 404:
        console.error('Share target not found');
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

​

Best Practices

1. Fetch before update - If you need to preserve existing array values, fetch the editable draft first with version=draft. Default GET returns the published version when one exists, otherwise the draft.
2. Incremental updates - Update only the fields that need to change
3. Validate attachments - Ensure attachment UUIDs are valid before including them
4. Keep draft actions - Resubmit every action id you want to keep. Missing ids already on the draft are dropped. Unavailable ids already on the draft stay.
5. Handle errors gracefully - Implement proper error handling for validation failures