Skip to main content
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. Set version to draft to read the editable draft.

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

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

Parameters

Examples

Basic Retrieval

Validation Rules

The API enforces the following validation rules:
  • Agent access - Your API key must have access to the agent
  • Draft read - version=draft needs the same edit access as an agent update
  • Workspace match - Agent must belong to the same workspace as your API key

Response Format

agent.access is included only when the API key has an explicit editor or owner grant on the agent. It lists direct user, group, and workspace grants, excluding owner and API-key grants. sharingManagedByAdmin is read-only; when true, sharing cannot be changed through this API. Sharing settings are current and independent of the returned agent version.

Success Response (200 OK)

icon is included only when includeIcon is true. null means the agent has no uploaded image. Otherwise fileName is icon.png or icon.jpg. The image is PNG or JPEG, at most 512 pixels on the long side and about 250 KB. Create and update responses never include icon. The actions array omits ids whose action is missing or soft-deleted. It still includes live actions that are unavailable in the workspace. skillIds lists attached Skills. File templates stay on the agent and do not appear in this array. subAgents lists attached subagents, each with agentId and requiresConfirmation. workflowIds lists attached workflows. Deleted agents and workflows are omitted.

Error Handling

422 and 503 apply only when you set includeIcon to true. 422 means the stored image cannot be returned as PNG or JPEG, including a file over 20 MB. 503 means storage could not be read. icon: null is not an error.
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.