Skip to main content

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

​
id
string
Unique agent identifier — pass this as bot_id to other endpoints.
​
workspace_id
string
The workspace this agent belongs to.
​
name
string | null
Human-readable agent name.
​
slug
string | null
URL-safe handle used in dashboard links (/admin/{workspace}/{slug}).
​
summary
string | null
One-line description of what this agent does.
​
is_agent
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.
​
enabled
boolean
false if the agent has been disabled by an admin.
​
public
boolean
true if the agent’s chat embed is allowed on public sites.
​
agent_role
string | null
Role string (e.g. "sales", "support").
​
agent_type
string | null
One of internal, external, or both.
​
agent_status
string | null
​
agent_color
string | null
Brand color used in the dashboard / inbox.
​
agent_email
string | null
Auto-provisioned inbound email address (e.g. b_01HDEF@inbound.clarky.ai).
​
agent_phone
string | null
Provisioned voice / SMS phone number, when one is attached.
​
chat_greeting
string | null
Opening message shown in the chat widget.
​
chat_avatar_intro
string | null
Speech bubble shown next to the avatar before the user opens the widget.
​
chat_avatar_image_url
string | null
​
phone_greeting
string | null
Spoken greeting on inbound calls.
​
phone_voice_id
string | null
ID of the TTS voice used for outbound speech.
​
text_greeting
string | null
Auto-reply for first SMS contact.
​
email_inbound
boolean | null
true if inbound emails to agent_email are processed.
​
email_outbound_autoreply
boolean | null
​
email_outbound_email
string | null
“From” address used for outbound emails.
​
email_outbound_name
string | null
“From” name used for outbound emails.
​
booking_provider
string | null
Booking integration in use — clarky, calcom, google, etc. null if booking isn’t enabled.
​
enabled_event_type_ids
string[] | null
IDs of Event Types this agent can offer when scheduling.
​
allow_human_takeover
boolean
true if teammates can take over conversations from this agent.
​
escalation_detection_enabled
boolean
true if Clarky should auto-flag conversations that need a human.
​
sentiment_analysis_enabled
boolean
true if conversations are analyzed for sentiment.
​
knowledge_count
number
Approximate number of knowledge entries attached to this agent.
​
number_of_conversations
number
Lifetime conversation count.
​
popular_topics
string[] | null
Recent top topics extracted from this agent’s conversations.
​
created_at
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

​
method
GET
GET /api/v1/agents
Returns a paginated list of every agent in the workspace.

​
Query parameters

ParamTypeDescription
searchstringMatch against name, slug, or summary
slugstringExact-match agent slug
is_agentbooleanFilter to next-gen agents only
enabledbooleanFilter by enabled state
agent_typestringOne of internal, external, both
pageintegerSee Pagination
page_sizeintegerSee 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

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