Skip to main content

Assistants API

CRUD operations for your Voilo Assistants.

Looking for auth, base URLs, pagination, or error formats? Head over to API Foundations.

Endpoints at a glance​

Method & PathPurpose
POST /v1/assistantsCreate a new Assistant
GET /v1/assistantsList existing Assistants (cursor‑paginated)
GET /v1/assistants/{id}Show a single Assistant
PATCH /v1/assistants/{id}Update part (or all) of an Assistant
DELETE /v1/assistants/{id}Delete (soft‑archive) an Assistant

Tip: Assistants default to status: active. The DELETE operation flips status to archived.

Archived Assistants are omitted from GET /v1/assistants and returning 404 on lookup.

Assistant object schema​

FieldTypeNotes
idstringasst_‑prefixed Assistant ID
namestringDisplay name shown in Console
modelstringLLM powering the Assistant (e.g. gpt-4o)
statusstring"active" (default) or "archived"
toolsstring[]Array of tool IDs enabled for this Assistant
configobjectFull Assistant Configuration payload (see Assistant Configuration guide)
tagsstring[]Arbitrary labels for your own grouping
owner_idstringWorkspace that owns the Assistant
created_atRFC‑3339 timestampCreation time
updated_atRFC‑3339 timestampLast modification time

Create an Assistant​

POST /v1/assistants

Example request​

curl -X POST https://api.voilo.io/assistants \
  -H "Authorization: Bearer $VOILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Assistant",
    "model": "gpt-4o",
    "tools": ["tool_transcribe", "tool_actions"],
    "tags": ["sales", "demo"],
    "config": {
      "prompt_template": "You are a Sales Assistant...",
      "transcription": {
        "provider": "openai",
        "model": "gpt-4o-mini-transcribe",
        "mode": "realtime"
      },
      "diarization": { "enabled": true },
      "key_terms": { "enabled": true, "files": ["glossary.txt"] }
    }
  }'

Response 201 Created​

{
  "id": "asst_6z4p2MbrA8nVYP",
  "name": "Sales Assistant",
  "model": "gpt-4o",
  "status": "active",
  "tools": ["tool_transcribe", "tool_actions"],
  "tags": ["sales", "demo"],
  "default_prompt": "Stay upbeat, concise, and always log next steps.",
  "config": { … },
  "owner_id": "org_9hksJ4",
  "created_at": "2025-06-10T14:01:22Z",
  "updated_at": "2025-06-10T14:01:22Z"
}

List Assistants​

GET /v1/assistants

Example request​

curl "https://api.voilo.io/assistants?cursor=MjAyNS0wNi0xMFQxNDozMDowMFo&limit=20" \
  -H "Authorization: Bearer $VOILO_API_KEY"

Response 200​

{
  "data": [ {…}, {…} ],
  "next_cursor": "MjAyNS0wNi0xMFQxNDo1MDozMFo",
  "has_more": true
}

Cursor semantics live in API Foundations → Pagination.

Show an Assistant​

GET /v1/assistants/{id}

Example request​

curl https://api.voilo.io/assistants/asst_6z4p2MbrA8nVYP \
  -H "Authorization: Bearer $VOILO_API_KEY"

200 OK – returns the Assistant object.

404 Not Found – ID unknown or archived.

Update an Assistant​

PATCH /v1/assistants/{id}

Example request​

curl -X PATCH https://api.voilo.io/assistants/asst_6z4p2MbrA8nVYP \
  -H "Authorization: Bearer $VOILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "archived", "tags": ["sales", "legacy"] }'

200 OK – returns the updated resource.

Delete (archive) an Assistant​

DELETE /v1/assistants/{id}

Example request​

curl -X DELETE https://api.voilo.io/assistants/asst_6z4p2MbrA8nVYP \
  -H "Authorization: Bearer $VOILO_API_KEY"

204 No Content – the Assistant is now archived.

Error handling recap​

All non‑2xx responses follow the shared envelope documented in API Foundations → Error Envelope. For example:

{
  "error": {
    "code": "invalid_auth",
    "message": "API key expired"
  }
}

See also​