manage agents

an agent is a prompt, a greeting, a voice and a language, plus a little call behaviour. /v1/agents is the same thing the dashboard’s agent editor edits.

create

POST /v1/agents creates an agent as a draft.

string

required

up to 120 characters. applies immediately when changed later.

string

required

the persona — who the agent is and how it behaves, up to 8000 characters. write only the persona: the rules for the chosen language and voice are appended server-side. {name} reads a variable, {{tool_name}} attaches a tool.

string

required

the first thing the agent says, up to 1000 characters. may use {name}.

object

the voice. model is muga, mulberry or spider; mulberry also takes a named voice and a style description. see voices. defaults to { "model": "muga" }.

string

english, hinglish or hindi, as the voice engine allows. unset = the engine’s default.

object

background_noise and idle_ladder, both off by default. see call behaviour.

string

a name for the first version, shown in the history. optional.

string

scratch (default) or template, with templateSlug naming the template from GET /v1/agents/templates.

curl

curl -X POST https://silk-api.rumik.ai/v1/agents \
  -H "Authorization: Bearer rk_live_•••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "systemInstruction": "You are the support agent for {company}. Be brief and warm. When the caller asks for a human, {{transfer_call}}.",
    "greeting": "Hi, this is {company} support. How can I help?",
    "ttsConfig": { "model": "mulberry", "voice": "Emma" },
    "language": "english",
    "callSettings": { "idle_ladder": { "enabled": true } },
    "versionName": "first cut"
  }'

returns 201 with the agent:

{
  "id": "019f6a2e-7c1d-7b3a-9e4f-1a2b3c4d5e6f",
  "handle": "ua_fe3277d8",
  "name": "support",
  "systemInstruction": "You are the support agent for {company}. …",
  "greeting": "Hi, this is {company} support. How can I help?",
  "ttsConfig": { "model": "mulberry", "voice": "Emma" },
  "callSettings": { "idle_ladder": { "enabled": true, "nudge_after_seconds": 5, "presence_after_seconds": 7, "hangup_after_seconds": 5 } },
  "language": "english",
  "source": "scratch",
  "templateSlug": null,
  "inboundPhoneNumber": null,
  "deployed": false,
  "ownerUserId": "019f0000-0000-7000-8000-000000000001",
  "createdAt": "2026-09-11T10:00:00Z",
  "updatedAt": "2026-09-11T10:00:00Z"
}

string

the short id (ua_…). use it or the UUID wherever an agent is named.

boolean

false until the first deploy. an undeployed agent answers no calls.

string | null

the number this agent answers, once a rented number or SIP trunk is connected to it.

the live configuration. after a PATCH, the pending edit is on the draft, not here, until you deploy.

typing {company} into the prompt declares an account-wide variable named company (with a blank default) if none exists yet. set its value with /v1/variables.

up to 25 agents per account (409 limit_exceeded past that).

deploy

POST /v1/agents/{agent_ref}/deploy promotes the pending draft to the next version and puts it live. it returns that version.

curl

curl -X POST https://silk-api.rumik.ai/v1/agents/ua_fe3277d8/deploy \
  -H "Authorization: Bearer rk_live_•••••••••"

{
  "id": "019f6b3f-8d2e-7c4b-af50-2b3c4d5e6f70",
  "versionNumber": 1,
  "name": "first cut",
  "status": "active",
  "systemInstruction": "…",
  "greeting": "…",
  "ttsConfig": { "model": "mulberry", "voice": "Emma" },
  "callSettings": { … },
  "language": "english",
  "activatedAt": "2026-09-11T10:05:00Z",
  "createdAt": "2026-09-11T10:00:00Z",
  "updatedAt": "2026-09-11T10:05:00Z"
}

with nothing pending you get 409 agent_version_no_draft — the agent already serves its latest edits.

update

PATCH /v1/agents/{agent_ref} takes any subset of the create fields.

name renames the agent at once.
systemInstruction, greeting, ttsConfig, language and callSettings go to the draft. the live version keeps answering until you deploy.
versionName names the draft this edit writes. omit it to leave the name alone, send null to clear it. sent on its own it renames the existing draft (409 agent_version_no_draft_to_name when there is none).

curl

curl -X PATCH https://silk-api.rumik.ai/v1/agents/ua_fe3277d8 \
  -H "Authorization: Bearer rk_live_•••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "systemInstruction": "You are the support agent for {company}. Be brief.", "versionName": "shorter prompt" }'

the response is the agent with its live fields; read the draft with GET /v1/agents/{agent_ref}/versions/draft, then deploy.

versions

method	path	what
GET	`/v1/agents/{agent_ref}/versions`	history, newest first: the `draft`, the `active` version, the `archived` ones
GET	`/v1/agents/{agent_ref}/versions/draft`	the pending draft (`404 agent_version_not_found` when none)
DELETE	`/v1/agents/{agent_ref}/versions/draft`	discard the pending edits
GET	`/v1/agents/{agent_ref}/versions/{n}`	one version’s full snapshot
POST	`/v1/agents/{agent_ref}/versions/{n}/activate`	roll back: that version goes live, the current one is archived
DELETE	`/v1/agents/{agent_ref}/versions/{n}`	remove an archived version (`409` for the active one)

a version carries the whole snapshot, not a diff, so any two can be compared without walking the chain.

call behaviour

callSettings is versioned with the rest of the config and sent to the bot on every call. both features are off unless enabled.

{
  "background_noise": { "enabled": true, "volume": 30 },
  "idle_ladder": {
    "enabled": true,
    "nudge_after_seconds": 5,
    "presence_after_seconds": 7,
    "hangup_after_seconds": 5
  }
}

object

mixes a quiet room tone under the voice. volume is 0–100 (default 30).

object

when the caller stays silent after the agent stops speaking: after nudge_after_seconds the agent says one short line to bring them back, presence_after_seconds later it asks whether they are still there, and hangup_after_seconds after that it says goodbye and ends the call (endReason: "customer_ended"). any reply restarts the ladder. each timing is 1–120 seconds.

on outbound calls you can override callSettings for one call without touching the agent.

list, get, delete

curl

curl https://silk-api.rumik.ai/v1/agents -H "Authorization: Bearer rk_live_•••••••••"
curl https://silk-api.rumik.ai/v1/agents/ua_fe3277d8 -H "Authorization: Bearer rk_live_•••••••••"
curl -X DELETE https://silk-api.rumik.ai/v1/agents/ua_fe3277d8 -H "Authorization: Bearer rk_live_•••••••••"

GET /v1/agents returns { "items": [...], "count": n }, newest first. DELETE answers 204; the agent’s calls stay in history and a number connected to it is detached.

this agent’s calls

read the account’s call history with GET /v1/calls and keep the ones whose agentSlug is this agent’s handle. every call carries its transcript and a short-lived recording url.

templates

GET /v1/agents/templates lists the starter templates the dashboard offers. to create from one, copy its systemInstruction, greeting and ttsConfig into POST /v1/agents with "source": "template" and its slug as templateSlug. next: voices.

documentation

sdk

integrations

cookbook

api reference

create

deploy

update

versions

call behaviour

list, get, delete

this agent’s calls

templates

​create

​deploy

​update

​versions

​call behaviour

​list, get, delete

​this agent’s calls

​templates

create

deploy

update

versions

call behaviour

list, get, delete

this agent’s calls

templates