The Conversations API from KaiCalls — 2 operation(s) for conversations.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kaicalls-com:kaicalls-com-conversations-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: KaiCalls Public Conversations API
version: '2026-06-05'
description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Conversations
paths:
/v1/conversations:
get:
summary: Return a tenant-scoped normalized call and SMS timeline for one customer…
description: Identify the customer with any one of customer_id, lead_id, phone, email or external_id — the same resolver `/v1/customers` uses. Items are normalized (`source_type`/`source_id`, `conversation_id`, `customer_id`/`lead_id`, `provider`/`provider_id`, `occurred_at`) while `source` preserves the original record, so a consumer can act without knowing which internal table held the artifact. Paging is an opaque keyset over the immutable `created_at` across both channels; walk it with `next_cursor`. `updated_since` matches a call on its updated_at and an SMS on its created_at — SMS rows carry no updated_at, so a delivery-status change on an already-synced message is NOT visible here; use the event/delivery endpoints for that.
parameters:
- name: customer_id
in: query
required: false
schema:
type: string
- name: lead_id
in: query
required: false
schema:
type: string
- name: phone
in: query
required: false
schema:
type: string
- name: email
in: query
required: false
schema:
type: string
- name: external_id
in: query
required: false
schema:
type: string
- name: updated_since
in: query
required: false
schema:
type: string
format: date-time
- name: cursor
in: query
required: false
description: Opaque cursor from a previous response’s next_cursor.
schema:
type: string
- name: order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 100
responses:
'200':
description: Normalized call and SMS timeline
'400':
description: No lookup key, more than one lookup key, an invalid cursor, or a bad updated_since.
'403':
description: Missing calls:read or sms:read scope
x-required-scopes:
allOf:
- calls:read
- sms:read
tags:
- Conversations
operationId: getV1Conversations
x-operation-id-source: derived
/v1/conversations/handoff:
post:
summary: 'Set who answers a customer''s text conversation: Kai (ai), the owner (human) or…'
description: 'owner ''ai'' is the default: Kai replies. ''human'' keeps Kai quiet so the owner answers. ''external'' keeps Kai quiet so your system answers: it receives the sms.received webhook (which carries conversation_owner) and replies with POST /v1/messages. With external_reply_timeout_seconds (external only, 60 to 86400), Kai answers a message nothing replied to in that time, within about a minute of the deadline, unless a newer message arrived or the owner changed. Inbound messages are always stored and sms.received always fires. Pass conversation_id for one conversation, or phone for every conversation the business has with that customer''s number (one per business line). Each owner change fires conversation.handoff. Re-sending the same owner is a no-op that reports changed: false. Responds 503 feature_unavailable until the feature is rolled out.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- owner
properties:
owner:
type: string
enum:
- ai
- human
- external
conversation_id:
type: string
format: uuid
description: One conversation. Pass this or phone.
phone:
type: string
description: 'The customer''s number (E.164): every conversation the business has with it.'
business_id:
type: string
format: uuid
description: Required when the API key reaches more than one business and only phone is given.
external_reply_timeout_seconds:
type:
- integer
- 'null'
minimum: 60
maximum: 86400
description: 'owner ''external'' only: Kai answers when nothing replied in this many seconds.'
responses:
'200':
description: Owner set (or already set).
content:
application/json:
schema:
type: object
required:
- conversation_id
- owner
- owner_set_at
- conversations
properties:
conversation_id:
type: string
owner:
type: string
enum:
- ai
- human
- external
owner_set_at:
type: string
format: date-time
external_reply_timeout_seconds:
type:
- integer
- 'null'
conversations:
type: array
items:
type: object
properties:
conversation_id:
type: string
lead_id:
type:
- string
- 'null'
lead_phone:
type:
- string
- 'null'
business_phone:
type:
- string
- 'null'
previous_owner:
type: string
enum:
- ai
- human
- external
owner:
type: string
enum:
- ai
- human
- external
changed:
type: boolean
'400':
description: Missing or invalid owner, neither or both of conversation_id and phone, a bad timeout, or business_id_required.
'403':
description: Missing sms:write scope, or business_id outside the key.
'404':
description: conversation_not_found.
'503':
description: 'feature_unavailable: handoff is not rolled out yet.'
x-required-scopes: sms:write
tags:
- Conversations
operationId: postV1ConversationsHandoff
x-operation-id-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
x-scopes:
- workspaces:read
- workspaces:write
- numbers:read
- numbers:write
- agents:read
- agents:write
- communication-runs:read
- communication-runs:write
- calls:read
- calls:write
- sms:read
- sms:write
- webhooks:read
- webhooks:write
- events:read
- events:replay
- lifecycle:write
- leads:read
- leads:write
- emails:read
- emails:write
- sdr:read
- sdr:write
- evals:read
- evals:write
- appointments:read
- appointments:write
- knowledge:read
- knowledge:write
- products:read
- products:write
- integrations:write
- approvals:write
- concierge:write
- billing:read
- billing:write
- call_evidence:read
- call_evidence:write
- support:write
sessionAuth:
type: apiKey
in: cookie
name: sb-access-token
description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.