Build assistants without the console
Everything the AvA Console does to assistants, plugins and knowledge bases, it does through these endpoints. Same API, same auth, same account — one scoped key and you can provision a whole tenant from your own CI.
One base URL, one header
Every endpoint on this page is JSON over HTTPS and takes a single Authorization header. There is no SDK to install and no handshake to complete.
https://avaai.pathor.in/api/v1Authorization: Bearer ava_ai_…application/jsonExcept the knowledge-base file upload, which is multipart.
# Never inline the key. Read it from the environment.
export AVA_API_KEY="ava_ai_live_xxxxxxxxxxxxxxxxxxxx"
curl 'https://avaai.pathor.in/api/v1/kb' \
-H "Authorization: Bearer $AVA_API_KEY"/:sessionId or /:userId. They are vestigial — the caller is resolved from the bearer and the segment is ignored. Send any non-empty value; the console sends the literal string :dummyData.An API key is a non-human teammate
A key carries the same per-module capability map a person on your team does. You decide, per module, whether it can read, write or manage — so the string sitting in somebody's CI config can only do the one job it was issued for.
Console → API keys → Create. Pick a preset or set each module by hand.
Assistants & knowledge covers everything on this page. Leave campaigns and WhatsApp at No access unless you need them.
Defaults to Never. A dated key is one you find out about before somebody else does.
Read the 403, it tells you what to fix
Every endpoint on this page names the module and level it needs. When a key falls short the response says which module, what was required and what the key actually holds — you do not have to guess.
| Status | code | What happened |
|---|---|---|
| 401 | invalid bearer token | The key does not exist, or the header was not sent as Bearer <key>. |
| 403 | key_revoked | The key was revoked in the console. Revoking takes effect on the next request — reissue rather than trying to un-revoke. |
| 403 | key_expired | The key passed its expiry. The message carries the date it lapsed. |
| 403 | route_forbidden | No key may ever reach this route — key management, team, profile writes, payments, platform admin. Not a scope you can grant yourself out of. |
| 403 | scope_denied | The key is valid but holds a lower level in this module than the request needs. The body names module, required and held. |
| 403 | route_not_in_scope_table | A scoped key hit a route with no rule. Scoped keys fail closed by design: a route added tomorrow is not inherited by every key issued today. |
{
"auth": false,
"success": false,
"code": "scope_denied",
"module": "assistants",
"required": "manage",
"held": "edit",
"message": "This API key has \"edit\" access to Assistants and this request needs \"manage\"."
}Empty account to grounded assistant
Four calls, in this order. The ordering is the part worth copying: an assistant can be attached to a knowledge base only after both exist, and the retrieval query at the end is how you check it is actually being shown what you think it is.
# 1 — a knowledge base
curl -X POST 'https://avaai.pathor.in/api/v1/kb' \
-H "Authorization: Bearer $AVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Orion product docs"}'
# → { "status": "ok", "kbId": "3f6b1c22-…" }
# 2 — put something in it
curl -X POST 'https://avaai.pathor.in/api/v1/kb/3f6b1c22-…/ingest-text' \
-H "Authorization: Bearer $AVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Returns policy","text":"Orion accepts returns within 30 days…"}'
# 3 — an assistant (voice id from GET /users/get_voice_clone)
curl -X POST 'https://avaai.pathor.in/api/v1/persona/enterprise/createPersona' \
-H "Authorization: Bearer $AVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name":"Orion Support",
"customPersonaId":"orion-support",
"isPublic":false,
"voice":"66f1c0a4e2b1a90012ab34cd",
"tags":["Support"],
"base_sys_prompt":"Answer billing and delivery questions from the attached knowledge base."
}'
# 4 — wire them together
curl -X POST 'https://avaai.pathor.in/api/v1/kb/3f6b1c22-…/personas/orion-support' \
-H "Authorization: Bearer $AVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"grounding_mode":"supplemental","enabled":true}'
# check what it will actually retrieve
curl -X POST 'https://avaai.pathor.in/api/v1/kb/3f6b1c22-…/query' \
-H "Authorization: Bearer $AVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"how long do I have to return something","topK":3}'An assistant is a prompt, a voice, a set of plugins and a set of knowledge bases. Everything else in this reference hangs off one — plugins give it hands, knowledge bases give it facts.
A plugin is a function definition the model is shown plus a Python body that runs when it decides to call it. Authoring one is a write; deleting one can break every assistant referencing it, so it takes Full control.
A knowledge base is a set of documents, chunked and embedded, that an attached assistant retrieves from at answer time. You can query one directly — the fastest way to find out whether an assistant is being shown what you think it is.
Machine-readable copies of this page
This page is a disclosure UI — fetch its HTML and you get thirty summaries with the detail still collapsed. If you are an agent, or you are handing this reference to one, use one of these instead. Both are generated from the same catalog, so they can never fall behind what is rendered above.
/api-docs/llms.txtThe complete reference as flat markdown — every parameter, sample and caveat, nothing behind a click. Each heading carries a permalink back into this page, so anything read there can be cited as a link.
/api-docs/openapi.jsonOpenAPI 3.1 for the same endpoints — load it into Postman, an SDK generator or a tool-calling harness. Every operation carries an x-ava-scope extension naming the key scope it needs, so you can work that out before the 403 rather than after it.
Addressing this page directly
Every section and every endpoint has a stable fragment. Link straight to the one that matters instead of asking someone to scroll.
/api-docs#knowledge-base | A whole section |
/api-docs#kb.query | One endpoint, arriving already expanded |
/api-docs?q=ingest | A search — shareable as a result list |
/api-docs?try=kb.query | The playground, open on that endpoint |
/api-docs?expand=all | Every endpoint expanded, for scraping or printing |