> ## 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.

# Agent List API

> List the agents shared with this API key

List the agents shared with this API key for invocation. The response does not include every agent in the workspace.

> [!NOTE]
>
> Disabled agents are included with `disabled: true`, but [chat completions](https://docs.langdock.com/en/developer/agents-api/agent.md) reject them with `403` and the code `ASSISTANT_DISABLED` until they are [re-enabled](https://docs.langdock.com/en/developer/agents-api/agent-disable.md).

## Before You Start

* **API key scope**: Requires the **Read Agents** scope, or the legacy **Agent API (full access)** scope.
* **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](https://docs.langdock.com/en/developer/agents-api/assistant-to-agent-migration.md).

## Base URL

```
https://api.langdock.com/agent/v1/list
```

> [!WARNING]
>
> **Dedicated deployments**
>
> Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | No | Page size from 1 to 250. Defaults to 50. |
| `cursor` | string | No | Agent id from the previous page's `nextCursor`. |

## Examples

### First page

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

async function listAgents() {
  const response = await axios.get(
    "https://api.langdock.com/agent/v1/list",
    {
      params: {
        limit: 50
      },
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log("Agents:", response.data.agents);
}
```

## Validation Rules

The API enforces the following validation rules:

* **API key access**: The list contains only agents shared with this API key for invocation
* **Workspace match**: Agents must belong to the same workspace as your API key
* **Omitted agents**: Deleted and archived agents are left out. Projects are not included. Disabled agents stay in the list with `disabled` set to `true`. You cannot chat with them until they are re-enabled

Agents are ordered by creation time, newest first.

Name, description, emoji, model, and input type come from the latest published version. If the agent has never been published, those fields come from the draft. When the agent uses Auto mode, `model` is `auto`.

Each item includes fewer fields than [Get agent details](https://docs.langdock.com/en/developer/agents-api/agent-get.md). `owner` is the current owner when that user still has an active membership in the workspace. If more than one owner remains, this is the most recently granted owner who is still an active member. It is `null` when no remaining owner is an active member.

`nextCursor` is included only when another page exists. Send it as `cursor` to fetch the next page. A well-formed UUID cursor that does not match an agent returns `200` with an empty `agents` array.

## Response Format

### Success Response (200 OK)

```typescript theme={null}
{
  agents: Array<{
    id: string;
    name: string | null;
    description: string | null;
    emojiIcon: string | null;
    model: string | null;
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    disabled: boolean;
    createdAt: string | null;
    updatedAt: string | null;
  }>;
  nextCursor?: string;
}
```

## Error Handling

```typescript theme={null}
try {
  const response = await axios.get('https://api.langdock.com/agent/v1/list', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Limit outside 1 to 250, not an integer, or cursor is not a UUID');
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('API key lacks the Read Agents scope or the Agent API (full access) scope');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}
```

> [!NOTE]
>
> 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](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.