Skip to content
Chatevo Docs
← Site Start free trial

Assistants API

Manage assistants programmatically — create, update, attach knowledge bases and tools, and archive.

Endpoints

Section titled “Endpoints”
MethodPathDescription
GET/api/v1/assistantsList assistants
POST/api/v1/assistantsCreate assistant
GET/api/v1/assistants/{id}Get assistant
PATCH/api/v1/assistants/{id}Update assistant
DELETE/api/v1/assistants/{id}Archive assistant
POST/api/v1/assistants/{id}/knowledge-basesAttach knowledge base
DELETE/api/v1/assistants/{id}/knowledge-bases/{kb_id}Detach knowledge base
POST/api/v1/assistants/{id}/toolsAttach tool
DELETE/api/v1/assistants/{id}/tools/{tool_id}Detach tool

Requires API key or session auth.

Create assistant

Section titled “Create assistant”
POST /api/v1/assistants
Authorization: Bearer ch_live_xxx
Content-Type: application/json
{
  "name": "Website Support",
  "description": "Answers FAQs from our help center",
  "master_prompt": "You are a helpful support agent. Answer from the knowledge base and tools only. Cite sources.",
  "model": "gpt-5.4-mini",
  "rag_settings": {
    "top_k": 8,
    "min_score": 0.72
  }
}

Response 201:

{
  "id": "asst_7xK9mN2p",
  "name": "Website Support",
  "model": "gpt-5.4-mini",
  "status": "active",
  "created_at": "2026-07-16T10:00:00Z"
}

List assistants

Section titled “List assistants”
GET /api/v1/assistants?limit=20&status=active
Query paramDescription
limitPage size (max 100)
cursorPagination cursor
statusactive, archived, or omit for all

Update assistant

Section titled “Update assistant”
PATCH /api/v1/assistants/asst_7xK9mN2p
{
  "master_prompt": "Updated instructions…",
  "model": "gpt-5.4"
}

Only include fields you want to change. Omitted fields are left unchanged.

Attach knowledge base

Section titled “Attach knowledge base”
POST /api/v1/assistants/asst_7xK9mN2p/knowledge-bases
{
  "knowledge_base_id": "kb_3fG8hJ1k"
}

Attach tool

Section titled “Attach tool”
POST /api/v1/assistants/asst_7xK9mN2p/tools
{
  "tool_id": "tool_9aB2cD4e"
}

Archive

Section titled “Archive”
DELETE /api/v1/assistants/asst_7xK9mN2p

Archiving stops new conversations on linked deployments. Existing conversation history is retained per your retention policy.

Plan limits

Section titled “Plan limits”

Creating assistants or attaching tools beyond your plan quota returns 403 with plan_limit_exceeded. See Plan limits.

Section titled “Related”