Docs navigation

Developer API

API Reference

A REST API for creating configured voice agents and queueing calls. Base URL:

https://api.artic.in/api/v1

Authentication

Authenticate every request with your secret key in the Authorization header as a Bearer token. Keys are created and revoked in the dashboard; the full token is shown only once at creation. A missing, malformed, or revoked key returns 401. All requests are tenant-scoped to the key's owner.

bash

curl https://api.artic.in/api/v1/agents \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Rate limits

Requests are limited to 60 per minute per API key (fixed 60-second window). Exceeding the limit returns 429. The limiter is currently per-instance and resets on deploy — design clients to back off on 429 rather than depend on exact counts.

Errors

Errors return a non-2xx status with a JSON body of the shape { "error": string, "message": string }. Validation failures additionally include a "fields" object mapping each invalid field to its problem.

400 bad_request — Malformed input, e.g. an invalid id.
400 validation_error — Body failed schema validation; see fields.
401 unauthorized — Missing, invalid, or revoked API key.
404 not_found — The resource does not exist or is not yours.
429 rate_limited — More than 60 requests in the current minute.

Agents

POST/v1/agents

Create a fully configured agent from a catalog template in one shot. businessDetails fill the template's placeholders; the response includes the generated agentConfig consumed by the voice runtime.

Parameters

Field	Type	Required	Description
templateSlug	string	Yes	Slug of a seeded catalog template.
businessDetails	object<string,string>	Yes	Key/value business fields that fill the template placeholders.
outputVariables	array	No	Optional structured values to extract from each call (dynamic templates only).
transferTriggers	array<{ when: string }>	No	Optional human-handoff conditions (dynamic templates only).

bash

curl -X POST https://api.artic.in/api/v1/agents \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "dental-appointment",
    "businessDetails": {
      "clinicName": "Smile Dental",
      "city": "Chennai"
    }
  }'

javascript

const res = await fetch("https://api.artic.in/api/v1/agents", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateSlug: "dental-appointment",
    businessDetails: { clinicName: "Smile Dental", city: "Chennai" },
  }),
});
const agent = await res.json();

Response

json

{
  "id": "665f1c2a9b3e4a0012ab34cd",
  "name": "Dental Appointment Agent",
  "status": "configured",
  "agentConfig": { "flowType": "dentiq_appointment", "dynamicVariables": { } },
  "assembledPrompt": "You are the front-desk assistant for Smile Dental…"
}

Errors

404 not_found — No template matches templateSlug.
400 validation_error — Required businessDetails fields are missing; see fields.

GET/v1/agents

List every agent in your account, newest first.

bash

curl https://api.artic.in/api/v1/agents \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

javascript

const res = await fetch("https://api.artic.in/api/v1/agents", {
  headers: { Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const agents = await res.json();

Response

json

[
  {
    "id": "665f1c2a9b3e4a0012ab34cd",
    "name": "Dental Appointment Agent",
    "status": "configured",
    "agentConfig": { "flowType": "dentiq_appointment" }
  }
]

GET/v1/agents/:id

Fetch a single agent by id.

Parameters

Field	Type	Required	Description
id	string (path)	Yes	The agent id.

bash

curl https://api.artic.in/api/v1/agents/665f1c2a9b3e4a0012ab34cd \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

javascript

const res = await fetch("https://api.artic.in/api/v1/agents/" + id, {
  headers: { Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const agent = await res.json();

Response

json

{
  "id": "665f1c2a9b3e4a0012ab34cd",
  "name": "Dental Appointment Agent",
  "status": "configured",
  "agentConfig": { "flowType": "dentiq_appointment" }
}

Errors

400 bad_request — id is not a valid object id.
404 not_found — No agent with that id in your account.

DELETE/v1/agents/:id

Delete an agent by id.

Parameters

Field	Type	Required	Description
id	string (path)	Yes	The agent id.

bash

curl -X DELETE https://api.artic.in/api/v1/agents/665f1c2a9b3e4a0012ab34cd \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

javascript

const res = await fetch("https://api.artic.in/api/v1/agents/" + id, {
  method: "DELETE",
  headers: { Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const out = await res.json();

Response

json

{ "ok": true }

Errors

400 bad_request — id is not a valid object id.
404 not_found — No agent with that id in your account.

Calls

POST/v1/calls

Queue a call request for an agent. The request is persisted with status "queued"; no live call is placed in this phase. billableMinutes is derived from the supplied estimatedMinutes.

Parameters

Field	Type	Required	Description
agentId	string	Yes	Id of an agent in your account.
phone	string	Yes	Destination phone number in E.164 form.
variables	object<string,string>	No	Per-call values merged into the agent's dynamic variables.
estimatedMinutes	number	No	Estimated call length (0–600). Sets billableMinutes for the queued request.

bash

curl -X POST https://api.artic.in/api/v1/calls \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "665f1c2a9b3e4a0012ab34cd",
    "phone": "+919876543210",
    "estimatedMinutes": 3
  }'

javascript

const res = await fetch("https://api.artic.in/api/v1/calls", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "665f1c2a9b3e4a0012ab34cd",
    phone: "+919876543210",
    estimatedMinutes: 3,
  }),
});
const call = await res.json();

Response

json

{
  "id": "665f20119b3e4a0012ab9900",
  "agentId": "665f1c2a9b3e4a0012ab34cd",
  "phone": "+919876543210",
  "status": "queued",
  "billableMinutes": 3,
  "createdAt": "2026-06-22T08:30:01.000Z"
}

Errors

400 bad_request — agentId is not a valid object id.
400 validation_error — Body failed schema validation; see fields.
404 not_found — No agent with that id in your account.

GET/v1/calls

List every call request in your account, newest first.

bash

curl https://api.artic.in/api/v1/calls \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

javascript

const res = await fetch("https://api.artic.in/api/v1/calls", {
  headers: { Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const calls = await res.json();

Response

json

[
  {
    "id": "665f20119b3e4a0012ab9900",
    "agentId": "665f1c2a9b3e4a0012ab34cd",
    "phone": "+919876543210",
    "status": "queued",
    "billableMinutes": 3,
    "createdAt": "2026-06-22T08:30:01.000Z"
  }
]

GET/v1/calls/:id

Fetch a single call request by id. Poll this to observe status changes.

Parameters

Field	Type	Required	Description
id	string (path)	Yes	The call request id.

bash

curl https://api.artic.in/api/v1/calls/665f20119b3e4a0012ab9900 \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

javascript

const res = await fetch("https://api.artic.in/api/v1/calls/" + id, {
  headers: { Authorization: "Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const call = await res.json();

Response

json

{
  "id": "665f20119b3e4a0012ab9900",
  "agentId": "665f1c2a9b3e4a0012ab34cd",
  "phone": "+919876543210",
  "status": "queued",
  "billableMinutes": 3,
  "createdAt": "2026-06-22T08:30:01.000Z"
}

Errors

400 bad_request — id is not a valid object id.
404 not_found — No call with that id in your account.