API reference

Assistants

List the assistants a key can reach, and read one in full.

Base URL for every endpoint in this reference:

Code
https://studio.zeevaa.ai/api/v1

List assistants#

HTTP
GET /v1/assistants

Every assistant in the key's workspace, newest first. A restricted key lists only the assistants it may reach.

Query parameters#

statusstringFilter to draft, published or disabled. Omit for all.
limitinteger1–100. Default 50.

Request#

Terminal
curl "https://studio.zeevaa.ai/api/v1/assistants?status=published" \
  -H "Authorization: Bearer $ZEEVAA_API_KEY"

Response#

JSON
{
  "assistants": [
    {
      "id": "9f2b1c84-6e3a-4d17-b0c5-2e7a8f41d9b3",
      "name": "Marina sales desk",
      "description": "Answers questions about available units.",
      "status": "published",
      "channels": { "chat": true, "voice": true },
      "has_catalogue": true,
      "has_knowledge": true,
      "created_at": "2026-06-02T11:04:19.442Z",
      "updated_at": "2026-07-28T16:20:51.006Z"
    }
  ],
  "has_more": false
}
idstringThe identifier every other endpoint takes. Stable — it is not the token in a shared link, and it never rotates.
statusstringOnly published accepts chat and speech.
channelsobjectWhich doors are enabled.
has_cataloguebooleanWhether structured record search is available.
has_knowledgebooleanWhether any linked knowledge base has content. An empty base reads as false, because a tool that can only return nothing is worse than no tool.

Retrieve an assistant#

HTTP
GET /v1/assistants/{assistant_id}

Everything needed to render an interface: the opening line, the starters, the form to collect, the branding, the vocabulary.

Request#

Terminal
curl "https://studio.zeevaa.ai/api/v1/assistants/9f2b1c84-6e3a-4d17-b0c5-2e7a8f41d9b3" \
  -H "Authorization: Bearer $ZEEVAA_API_KEY"

Response#

JSON
{
  "id": "9f2b1c84-6e3a-4d17-b0c5-2e7a8f41d9b3",
  "name": "Marina sales desk",
  "description": "Answers questions about available units.",
  "status": "published",
  "greeting": "Hi! How can I help you today?",
  "starter_prompts": [
    "What's available under 2M?",
    "How do service charges work?"
  ],
  "channels": { "chat": true, "voice": true },
  "branding": {
    "display_name": "Marina Sales",
    "tagline": "Ask us anything about the development",
    "accent": "#0ea5a4",
    "logo_url": null,
    "theme": "system"
  },
  "pre_chat_form": {
    "enabled": true,
    "intro": "So we can follow up:",
    "fields": [
      { "key": "name", "label": "Your name", "type": "text", "required": true },
      { "key": "email", "label": "Email", "type": "email", "required": true }
    ]
  },
  "catalogue": {
    "record_label": "property",
    "record_label_plural": "properties"
  },
  "limits": { "max_call_seconds": 600 },
  "created_at": "2026-06-02T11:04:19.442Z",
  "updated_at": "2026-07-28T16:20:51.006Z"
}

Fields#

greetingstringThe opening line. Show it as the first message. Not a turn — it costs no tokens and never appears in the transcript.
starter_promptsstring[]Tappable openers. May be empty.
brandingobject | nullPresent so an embedded surface can match its parent. Ignore it if your interface has its own design.
pre_chat_formobject | nullWhen enabled, collect these before opening a session and pass them as visitor.
catalogueobject | nullThe nouns this assistant uses for a record, singular and plural. Use them in your own copy. null when no catalogue is attached.
limits.max_call_secondsintegerHard ceiling on one conversation.

Field types on pre_chat_form.fields are text, email or tel — enough to pick the right input mode on a phone keyboard.

For what is deliberately not returned — the system prompt, the model, your credentials, your webhook definitions — see Assistants.

Errors#

404 assistant_not_foundNo such assistant in this workspace, or the key is restricted and does not include it. The two are not distinguished, so a key cannot be used to discover what exists.

Next#