Agents

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.

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.

The Agent object

string

Unique agent identifier — pass this as bot_id to other endpoints.

string

The workspace this agent belongs to.

string | null

Human-readable agent name.

string | null

URL-safe handle used in dashboard links (/admin/{workspace}/{slug}).

string | null

One-line description of what this agent does.

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.

boolean

false if the agent has been disabled by an admin.

boolean

true if the agent’s chat embed is allowed on public sites.

string | null

Role string (e.g. "sales", "support").

string | null

One of internal, external, or both.

string | null

Brand color used in the dashboard / inbox.

string | null

Auto-provisioned inbound email address (e.g. b_01HDEF@inbound.clarky.ai).

string | null

Provisioned voice / SMS phone number, when one is attached.

string | null

Opening message shown in the chat widget.

string | null

Speech bubble shown next to the avatar before the user opens the widget.

string | null

Spoken greeting on inbound calls.

string | null

ID of the TTS voice used for outbound speech.

string | null

Auto-reply for first SMS contact.

boolean | null

true if inbound emails to agent_email are processed.

boolean | null

string | null

“From” address used for outbound emails.

string | null

“From” name used for outbound emails.

string | null

Booking integration in use — clarky, calcom, google, etc. null if booking isn’t enabled.

string[] | null

IDs of Event Types this agent can offer when scheduling.

boolean

true if teammates can take over conversations from this agent.

boolean

true if Clarky should auto-flag conversations that need a human.

boolean

true if conversations are analyzed for sentiment.

number

Approximate number of knowledge entries attached to this agent.

number

Lifetime conversation count.

string[] | null

Recent top topics extracted from this agent’s conversations.

string

ISO 8601 timestamp.

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.

List agents

GET

GET /api/v1/agents

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
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/agents?enabled=true" \
  -H "Authorization: Bearer ck_live_example"

{
  "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

GET

GET /api/v1/agents/{id}

Example

curl https://clarky.ai/api/v1/agents/b_01HDEF \
  -H "Authorization: Bearer ck_live_example"

{
  "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:

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:

# 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" }] }'

Getting Started

Resources

The Agent object

List agents

Query parameters

Example

Get an agent

Example

Common patterns

Resolve an agent by slug

Bootstrap an integration

​The Agent object

​List agents

​Query parameters

​Example

​Get an agent

​Example

​Common patterns

​Resolve an agent by slug

​Bootstrap an integration

The Agent object

List agents

Query parameters

Example

Get an agent

Example

Common patterns

Resolve an agent by slug

Bootstrap an integration