> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Discover the agents in your workspace and their channel configuration

Agents are the AI assistants in your workspace — every contact, conversation, form, and pipeline lives under one. The Agents API is a **read-only** discovery endpoint: use it to list the agents in a workspace and look up the IDs you'll pass as `bot_id` to the rest of the API.

<Tip>
  Most resources in the API (contacts, companies, forms, pipelines, conversations) are scoped by `bot_id`. If you don't already have one, list agents first and pick the right `id`.
</Tip>

## The Agent object

<ResponseField name="id" type="string">
  Unique agent identifier — pass this as `bot_id` to other endpoints.
</ResponseField>

<ResponseField name="workspace_id" type="string">
  The workspace this agent belongs to.
</ResponseField>

<ResponseField name="name" type="string | null">
  Human-readable agent name.
</ResponseField>

<ResponseField name="slug" type="string | null">
  URL-safe handle used in dashboard links (`/admin/{workspace}/{slug}`).
</ResponseField>

<ResponseField name="summary" type="string | null">
  One-line description of what this agent does.
</ResponseField>

<ResponseField name="is_agent" type="boolean">
  `true` for next-gen agents (`/admin/{workspace}/agents`). Some legacy bots may have `is_agent=false` — they're still valid `bot_id` targets for the rest of the API.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  `false` if the agent has been disabled by an admin.
</ResponseField>

<ResponseField name="public" type="boolean">
  `true` if the agent's chat embed is allowed on public sites.
</ResponseField>

<ResponseField name="agent_role" type="string | null">
  Role string (e.g. `"sales"`, `"support"`).
</ResponseField>

<ResponseField name="agent_type" type="string | null">
  One of `internal`, `external`, or `both`.
</ResponseField>

<ResponseField name="agent_status" type="string | null" />

<ResponseField name="agent_color" type="string | null">
  Brand color used in the dashboard / inbox.
</ResponseField>

<ResponseField name="agent_email" type="string | null">
  Auto-provisioned inbound email address (e.g. `b_01HDEF@inbound.clarky.ai`).
</ResponseField>

<ResponseField name="agent_phone" type="string | null">
  Provisioned voice / SMS phone number, when one is attached.
</ResponseField>

<ResponseField name="chat_greeting" type="string | null">
  Opening message shown in the chat widget.
</ResponseField>

<ResponseField name="chat_avatar_intro" type="string | null">
  Speech bubble shown next to the avatar before the user opens the widget.
</ResponseField>

<ResponseField name="chat_avatar_image_url" type="string | null" />

<ResponseField name="phone_greeting" type="string | null">
  Spoken greeting on inbound calls.
</ResponseField>

<ResponseField name="phone_voice_id" type="string | null">
  ID of the TTS voice used for outbound speech.
</ResponseField>

<ResponseField name="text_greeting" type="string | null">
  Auto-reply for first SMS contact.
</ResponseField>

<ResponseField name="email_inbound" type="boolean | null">
  `true` if inbound emails to `agent_email` are processed.
</ResponseField>

<ResponseField name="email_outbound_autoreply" type="boolean | null" />

<ResponseField name="email_outbound_email" type="string | null">
  "From" address used for outbound emails.
</ResponseField>

<ResponseField name="email_outbound_name" type="string | null">
  "From" name used for outbound emails.
</ResponseField>

<ResponseField name="booking_provider" type="string | null">
  Booking integration in use — `clarky`, `calcom`, `google`, etc. `null` if booking isn't enabled.
</ResponseField>

<ResponseField name="enabled_event_type_ids" type="string[] | null">
  IDs of [Event Types](/features/booking/event-types) this agent can offer when scheduling.
</ResponseField>

<ResponseField name="allow_human_takeover" type="boolean">
  `true` if teammates can take over conversations from this agent.
</ResponseField>

<ResponseField name="escalation_detection_enabled" type="boolean">
  `true` if Clarky should auto-flag conversations that need a human.
</ResponseField>

<ResponseField name="sentiment_analysis_enabled" type="boolean">
  `true` if conversations are analyzed for sentiment.
</ResponseField>

<ResponseField name="knowledge_count" type="number">
  Approximate number of [knowledge entries](/features/knowledge/overview) attached to this agent.
</ResponseField>

<ResponseField name="number_of_conversations" type="number">
  Lifetime conversation count.
</ResponseField>

<ResponseField name="popular_topics" type="string[] | null">
  Recent top topics extracted from this agent's conversations.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<Note>
  We deliberately omit secrets (Slack tokens, Resend API keys), system prompts (`internal_personality`, `external_personality`, `custom_escalation_prompt`), and internal RAG tuning knobs (`match_threshold`, `match_count`) from this response. Manage those in the dashboard.
</Note>

***

## List agents

<ParamField path="method" type="GET">
  `GET /api/v1/agents`
</ParamField>

Returns a paginated list of every agent in the workspace.

### Query parameters

| Param        | Type    | Description                                 |
| ------------ | ------- | ------------------------------------------- |
| `search`     | string  | Match against name, slug, or summary        |
| `slug`       | string  | Exact-match agent slug                      |
| `is_agent`   | boolean | Filter to next-gen agents only              |
| `enabled`    | boolean | Filter by enabled state                     |
| `agent_type` | string  | One of `internal`, `external`, `both`       |
| `page`       | integer | See [Pagination](/api-reference/pagination) |
| `page_size`  | integer | See [Pagination](/api-reference/pagination) |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/agents?enabled=true" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "b_01HDEF...",
      "workspace_id": "w_01HXXX...",
      "name": "Clarky Sales",
      "slug": "sales",
      "summary": "Outbound + inbound sales agent for the marketing site.",
      "is_agent": true,
      "enabled": true,
      "public": true,
      "agent_role": "sales",
      "agent_type": "external",
      "agent_status": "live",
      "agent_color": "#0586ff",
      "agent_email": "b_01HDEF@inbound.clarky.ai",
      "agent_phone": "+15125550100",
      "chat_greeting": "Hey! What can I help you with today?",
      "chat_avatar_intro": "Got questions? Ask me anything.",
      "chat_avatar_image_url": null,
      "phone_greeting": "Hi, this is Clarky's sales agent — how can I help?",
      "phone_voice_id": "elv_voice_andy",
      "text_greeting": "Thanks for texting! What's up?",
      "email_inbound": true,
      "email_outbound_autoreply": true,
      "email_outbound_email": "sales@example.com",
      "email_outbound_name": "Clarky Sales",
      "booking_provider": "clarky",
      "enabled_event_type_ids": ["et_01HABC..."],
      "allow_human_takeover": true,
      "escalation_detection_enabled": true,
      "sentiment_analysis_enabled": true,
      "knowledge_count": 184,
      "number_of_conversations": 5421,
      "popular_topics": ["pricing", "demo", "integrations"],
      "created_at": "2026-01-12T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get an agent

<ParamField path="method" type="GET">
  `GET /api/v1/agents/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/agents/b_01HDEF \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "b_01HDEF...",
    "name": "Clarky Sales",
    "slug": "sales",
    "is_agent": true,
    "enabled": true,
    "agent_email": "b_01HDEF@inbound.clarky.ai",
    "agent_phone": "+15125550100",
    "booking_provider": "clarky",
    "knowledge_count": 184,
    "number_of_conversations": 5421,
    "created_at": "2026-01-12T10:00:00.000Z"
  }
}
```

***

## Common patterns

### Resolve an agent by slug

The dashboard URL `https://clarky.ai/admin/{workspace}/{slug}` exposes each agent's slug. Use it to look up the canonical `id`:

```bash theme={null}
curl "https://clarky.ai/api/v1/agents?slug=sales" \
  -H "Authorization: Bearer ck_live_example"
```

### Bootstrap an integration

A first-run flow for a new integration:

```bash theme={null}
# 1. List agents to let the user pick one.
curl https://clarky.ai/api/v1/agents \
  -H "Authorization: Bearer ck_live_example"

# 2. Use the chosen id as bot_id everywhere else.
curl -X POST https://clarky.ai/api/v1/contacts \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "b_01HDEF", "first_name": "Ada", "emails": [{ "email": "ada@example.com" }] }'
```