{ "openapi": "3.1.0", "info": { "title": "AvA API — Assistants, Plugins & Knowledge Base", "version": "1.0.0", "description": "Build and run AI assistants over HTTPS with a scoped API key.\n\nHuman reference: https://console.ava.pathor.ai/api-docs\nPlain-text reference: https://console.ava.pathor.ai/api-docs/llms.txt\n\nEvery operation carries an `x-ava-scope` extension naming the module and\nlevel a key must hold. A key that falls short gets 403 `scope_denied`,\nwhose body names what was required and what the key holds.\n\nCampaigns, WhatsApp and journeys are intentionally absent — they spend\nmoney and reach real people, and are not part of the public reference." }, "servers": [ { "url": "https://avaai.pathor.in/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Assistants", "description": "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.", "externalDocs": { "url": "https://console.ava.pathor.ai/api-docs#assistants" } }, { "name": "Plugins", "description": "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.", "externalDocs": { "url": "https://console.ava.pathor.ai/api-docs#plugins" } }, { "name": "Knowledge Base", "description": "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.", "externalDocs": { "url": "https://console.ava.pathor.ai/api-docs#knowledge-base" } } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A scoped API key, prefixed `ava_ai_`. Minted at https://console.ava.pathor.ai/dashboard/api_key." } }, "responses": { "ScopeDenied": { "description": "The key is valid but is not scoped for this route, or the route is refused to keys entirely.", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth": { "type": "boolean" }, "success": { "type": "boolean" }, "code": { "type": "string", "enum": [ "key_revoked", "key_expired", "route_forbidden", "scope_denied", "route_not_in_scope_table" ] }, "module": { "type": "string" }, "required": { "type": "string" }, "held": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "paths": { "/persona/enterprise/getAllPersonas/{sessionId}": { "post": { "operationId": "assistants_list", "summary": "List assistants", "description": "Every assistant the key's account can see, paginated. This is the call the console's Assistants grid makes.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.list\n\n- This response carries **no `status` field** — unlike most of the API. Branch on the HTTP status, and treat a body with no `allPersonas` array as a failure rather than as an empty account.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "view" }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Vestigial. The handler reads the caller from the bearer and ignores this segment — send any non-empty value. The console sends the literal string :dummyData.", "example": ":dummyData", "schema": { "type": "string" } }, { "name": "isPublic", "in": "query", "required": false, "description": "private is what the console shows: assistants this account owns or was granted. public is the shared catalog.", "example": "private", "schema": { "type": "string", "enum": [ "private", "public", "all" ], "default": "all" } }, { "name": "isMainAgent", "in": "query", "required": false, "description": "false narrows to agentic tools — assistants that exist to be called by another assistant rather than talked to.", "example": "all", "schema": { "type": "string", "enum": [ "all", "true", "false" ], "default": "all" } }, { "name": "os", "in": "query", "required": false, "description": "Comma-separated targets: nt, android, web. Ignored when the request carries a browser Origin header — from a browser the server always widens this to web,nt,android, so a filtered list needs a server-side call.", "example": "nt", "schema": { "type": "string", "default": "nt" } }, { "name": "page", "in": "query", "required": false, "description": "", "example": "1", "schema": { "type": "number", "default": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "", "example": "20", "schema": { "type": "number", "default": "50" } }, { "name": "ret", "in": "query", "required": false, "description": "Send ret=count to get the total back without the documents.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "allPersonas": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "customPersonaId": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "isPublic": { "type": "boolean" }, "voice": { "type": "string" }, "os": { "type": "array", "items": { "type": "string" } }, "Is_main_agent": { "type": "boolean" }, "attached_kbs": { "type": "array", "items": { "type": "object", "properties": { "kbId": { "type": "string" }, "enabled": { "type": "boolean" }, "grounding_mode": { "type": "string" } } } }, "createdAt": { "type": "string" } } } }, "totalPersonas": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "allPersonas": [ { "_id": "66f2a1b4c5d6e70012345678", "customPersonaId": "orion-support", "name": "Orion Support", "title": "Customer support specialist", "isPublic": false, "voice": "66f1c0a4e2b1a90012ab34cd", "os": [ "nt" ], "Is_main_agent": true, "attached_kbs": [ { "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "enabled": true, "grounding_mode": "supplemental" } ], "createdAt": "2026-07-02T09:14:22.104Z" } ], "totalPersonas": 42, "currentPage": 1, "totalPages": 3 } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/searchPersonas": { "post": { "operationId": "assistants_search", "summary": "Search assistants", "description": "The same shape as the list, filtered by a free-text term across name and title.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.search", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "view" }, "parameters": [ { "name": "search", "in": "query", "required": true, "description": "", "example": "support", "schema": { "type": "string" } }, { "name": "isMainAgent", "in": "query", "required": false, "description": "", "example": "all", "schema": { "type": "string", "enum": [ "all", "true", "false" ], "default": "all" } }, { "name": "os", "in": "query", "required": false, "description": "", "example": "nt", "schema": { "type": "string", "default": "nt" } }, { "name": "page", "in": "query", "required": false, "description": "", "example": "1", "schema": { "type": "number", "default": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "", "example": "20", "schema": { "type": "number", "default": "30" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "allPersonas": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "customPersonaId": { "type": "string" }, "name": { "type": "string" } } } }, "totalPersonas": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "status": true, "allPersonas": [ { "_id": "66f2a1b4c5d6e70012345678", "customPersonaId": "orion-support", "name": "Orion Support" } ], "totalPersonas": 3, "currentPage": 1, "totalPages": 1 } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/getPersona/{sessionId}/{personaId}": { "post": { "operationId": "assistants_get", "summary": "Get one assistant", "description": "The full document, including the system prompt, attached knowledge bases and plugin ids.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.get\n\n- The document is under **`personaData`**, not `persona` — and the list endpoints return theirs under `allPersonas`. Three names, one object; this is the API's oldest wart.\n- An id the account cannot see answers **400**, not 404. The server does not distinguish “no such assistant” from “not yours”.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "view" }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Vestigial, as above. Any non-empty value.", "example": ":dummyData", "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "description": "The customPersonaId — the readable id you chose at creation, not the Mongo _id.", "example": "orion-support", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "personaData": { "type": "object", "properties": { "_id": { "type": "string" }, "customPersonaId": { "type": "string" }, "name": { "type": "string" }, "base_sys_prompt": { "type": "string" }, "voice": { "type": "string" }, "accessible_plugin": { "type": "array", "items": {} }, "attached_kbs": { "type": "array", "items": { "type": "object", "properties": { "kbId": { "type": "string" }, "enabled": { "type": "boolean" }, "grounding_mode": { "type": "string" } } } } } } } }, "example": { "status": true, "personaData": { "_id": "66f2a1b4c5d6e70012345678", "customPersonaId": "orion-support", "name": "Orion Support", "base_sys_prompt": "You handle billing and delivery questions for Orion…", "voice": "66f1c0a4e2b1a90012ab34cd", "accessible_plugin": [], "attached_kbs": [ { "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "enabled": true, "grounding_mode": "supplemental" } ] } } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/createPersona": { "post": { "operationId": "assistants_create", "summary": "Create an assistant", "description": "Mints a new assistant on the key's account. customPersonaId is unique platform-wide and is how every other call addresses it.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.create\n\n- A duplicate customPersonaId comes back as **404** with `persona already exists with …` — an unusual status for a conflict, but that is what the server sends.\n- The response does not echo the created document. Follow with **Get one assistant** if you need it.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "edit" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "customPersonaId": { "type": "string", "description": "Your own stable id — slug-like, unique platform-wide. Every later call uses this, so pick something you will not want to rename." }, "isPublic": { "type": "boolean", "description": "Listed in the shared catalog. false for anything account-specific. Must be present — an omitted isPublic is a 400, not a default." }, "voice": { "type": "string", "description": "A voice _id from the voice catalog below. Required even for a text-only assistant." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Send an array, even an empty one. General is appended server-side if you leave it out." }, "base_sys_prompt": { "type": "string", "description": "The system prompt. Capped at 5,000 characters for Android-only assistants and silently truncated past it." }, "title": { "type": "string", "description": "One-line role description shown under the name." }, "personality": { "type": "string", "description": "Free text, max 2,100 characters. Longer is a 400." }, "gender": { "type": "string", "description": "" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "" }, "behavior": { "type": "array", "items": { "type": "string" }, "description": "" }, "os": { "type": "array", "items": { "type": "string" }, "description": "Target platforms: nt, android, web. An android-only assistant takes the 5,000-character prompt cap." }, "Is_main_agent": { "type": "boolean", "description": "True for an assistant people talk to. Capital I — that is the wire name." }, "is_agentic_tool": { "type": "boolean", "description": "True when this assistant exists to be called by another one." }, "accessible_plugin": { "type": "array", "items": { "type": "string" }, "description": "Plugin _ids this assistant may run." }, "authorised_users_email": { "type": "array", "items": { "type": "string" }, "description": "Emails granted access. Each address is sent an invitation when the assistant is created." }, "logo": { "type": "string", "description": "Absolute image URL." }, "voice_language": { "type": "string", "description": "Accent code, e.g. en-IN." } }, "required": [ "name", "customPersonaId", "isPublic", "voice", "tags" ] }, "example": { "name": "Orion Support", "customPersonaId": "orion-support", "title": "Customer support specialist", "isPublic": false, "voice": "66f1c0a4e2b1a90012ab34cd", "voice_language": "en-IN", "gender": "female", "languages": [ "english" ], "tags": [ "Support" ], "behavior": [ "calm", "precise" ], "base_sys_prompt": "You handle billing and delivery questions for Orion. Answer from the attached knowledge base. Confirm the order number before quoting any refund amount.", "personality": "Warm, brisk, never over-promises.", "os": [ "nt" ], "Is_main_agent": true, "is_agentic_tool": false, "accessible_plugin": [], "authorised_users_email": [], "logo": "https://cdn.example.com/orion.png" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "New persona has been created" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/updatePersona": { "put": { "operationId": "assistants_update", "summary": "Update an assistant", "description": "Partial update. Send only the fields you are changing — but read the array rule before you send one.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.update\n\n- A personaId the key's account does not own returns **400** `unauthorized user`, not 404 — the server will not confirm whether the assistant exists.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "edit" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personaId": { "type": "string", "description": "The customPersonaId. Named personaId in this body only; everywhere else that name means the Mongo _id." }, "base_sys_prompt": { "type": "string", "description": "Replaced wholesale." }, "accessible_plugin": { "type": "string", "description": "Inverted from the fields above, and easy to get wrong: an array ADDS the plugin ids, a bare string REMOVES that one plugin." }, "name": { "type": "string", "description": "" }, "title": { "type": "string", "description": "" }, "isPublic": { "type": "boolean", "description": "" }, "voice": { "type": "string", "description": "" }, "logo": { "type": "string", "description": "" } }, "required": [ "personaId" ] }, "example": { "personaId": "orion-support", "base_sys_prompt": "You handle billing and delivery questions for Orion. Confirm the order number before quoting any refund amount.", "tags": [ "Support", "Billing" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "Persona has been updated!" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/deletePersona/{sessionId}/{personaId}": { "delete": { "operationId": "assistants_delete", "summary": "Delete an assistant", "description": "Permanent. The assistant, its share links and its knowledge-base attachments go with it.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.delete\n\n- Written to your account's activity trail as `assistant.deleted`, with the name captured before the delete so the entry still reads sensibly afterwards.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "manage" }, "x-ava-destructive": true, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Vestigial. Any non-empty value.", "example": ":dummyData", "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "description": "The customPersonaId.", "example": "orion-support", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "Persona has been deleted!" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/sharePersona/{customPersonaId}": { "post": { "operationId": "assistants_share", "summary": "Mint a share-link token", "description": "Returns a con_sh_… token that lets someone talk to this one assistant without an account.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.share\n\n- manage, not edit: minting a public link is a disclosure, not an edit.\n- A con_sh_ token is **not** an API key. It reaches one assistant, carries no scope map, and can never be widened.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "manage" }, "parameters": [ { "name": "customPersonaId", "in": "path", "required": true, "description": "", "example": "orion-support", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "string" } } }, "example": { "status": true, "message": "Sharable persona token generated successfully", "data": "con_sh_9f2c7a1b4e08" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/persona/enterprise/transferOwnership/{personaId}": { "post": { "operationId": "assistants_transfer", "summary": "Transfer ownership", "description": "Hands the assistant to another account by email.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.transfer", "tags": [ "Assistants" ], "x-ava-scope": { "module": "assistants", "level": "manage" }, "x-ava-destructive": true, "parameters": [ { "name": "personaId", "in": "path", "required": true, "description": "The Mongo _id here — the one route in this section that does not take customPersonaId. A non-ObjectId value is rejected with a 400.", "example": "66f2a1b4c5d6e70012345678", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newOwnerEmail": { "type": "string", "description": "Must already have an account." }, "keepAccess": { "type": "boolean", "description": "Leave yourself on the assistant as a full-access editor." } }, "required": [ "newOwnerEmail" ] }, "example": { "newOwnerEmail": "ops@example.com", "keepAccess": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "note": { "type": "string" } } }, "example": { "status": true, "message": "Ownership of \"Orion Support\" transferred to ops@example.com", "note": "You retain full-access editor rights" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/users/get_voice_clone": { "get": { "operationId": "assistants_voices", "summary": "Voice catalog", "description": "Every voice available to the account, cloned ones included. You need an _id from here before you can create an assistant at all.\n\nPermalink: https://console.ava.pathor.ai/api-docs#assistants.voices\n\n- The array is under **`data`**, and the `_id` — not `voice_id` — is what `createPersona` wants for its `voice` field. `voice_id` is the upstream provider's own id and the assistant routes will not accept it.\n- Lives under the **Voices** module, not Assistants — a key scoped to assistants alone gets a 403 here. The **Assistants & knowledge** preset already includes Voices at Read.", "tags": [ "Assistants" ], "x-ava-scope": { "module": "voices", "level": "view" }, "parameters": [ { "name": "title", "in": "query", "required": false, "description": "Narrow to one voice by exact title. Omit for the whole catalog.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" }, "gender": { "type": "string" }, "voice_language": { "type": "string" }, "voice_provider": { "type": "string" }, "voice_type": { "type": "string" }, "isPublic": { "type": "boolean" }, "voice_sample_uri": { "type": "string" } } } } } }, "example": { "status": true, "message": "voice_clone fetched successfully", "data": [ { "_id": "66f1c0a4e2b1a90012ab34cd", "title": "Aria", "gender": "female", "voice_language": "en-IN", "voice_provider": "cartesia", "voice_type": "non-custom", "isPublic": true, "voice_sample_uri": "https://cdn.example.com/voices/aria.mp3" } ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/users/enterprise/getallplugin/{userId}": { "post": { "operationId": "plugins_list", "summary": "List plugins", "description": "The plugin catalog visible to the key's account — your own plugins plus anything published platform-wide.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.list\n\n- The collection key is **`plugin`**, singular — not `plugins`. Every list endpoint in this section uses it.\n- An empty result is shaped differently: `{ status: \"true\", message: \"No plugin found\", tags: […] }` with **no `plugin` key at all**. Read it as `data.plugin || []` rather than indexing straight into it.\n- `func_run` and `func_schema` come back **AES-encrypted**. The console decrypts them in the browser; from a server you would need to do the same. Everything else on the document is plain.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "view" }, "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Vestigial, like the assistant routes: the caller comes from the bearer. Any non-empty value.", "example": ":dummyData", "schema": { "type": "string" } }, { "name": "isPublic", "in": "query", "required": false, "description": "private is the account's own catalog.", "example": "private", "schema": { "type": "string", "enum": [ "public", "private", "all" ], "default": "all" } }, { "name": "status", "in": "query", "required": false, "description": "", "example": "all", "schema": { "type": "string", "enum": [ "all", "approved", "pending" ], "default": "all" } }, { "name": "os", "in": "query", "required": false, "description": "nt, android, web, or all.", "example": "all", "schema": { "type": "string", "default": "all" } }, { "name": "page", "in": "query", "required": false, "description": "", "example": "1", "schema": { "type": "number", "default": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "", "example": "20", "schema": { "type": "number", "default": "50" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalPlugins": { "type": "integer" }, "totalPages": { "type": "integer" }, "currentPage": { "type": "integer" }, "plugin": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "isPublic": { "type": "boolean" }, "creator": { "type": "string" }, "os": { "type": "array", "items": { "type": "string" } } } } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "totalPlugins": 12, "totalPages": 1, "currentPage": 1, "plugin": [ { "_id": "66f3b2c5d6e7f80012345679", "title": "order_lookup", "name": "Order lookup", "tags": [ "commerce" ], "isPublic": false, "creator": "Orion Ltd", "os": [ "nt" ] } ], "tags": [ "new", "all", "connected" ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/users/enterprise/getPlugin": { "post": { "operationId": "plugins_get", "summary": "Get one plugin", "description": "One plugin, addressed by its unique title.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.get\n\n- `status` is the **string** `\"true\"` on this endpoint, not the boolean the assistant routes return. Do not branch on it — branch on the HTTP status.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "view" }, "parameters": [ { "name": "title", "in": "query", "required": true, "description": "The plugin's unique title — its identity, not its display name.", "example": "order_lookup", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "plugin": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "human_description": { "type": "string" }, "isPublic": { "type": "boolean" }, "isOwner": { "type": "boolean" } } } } }, "example": { "status": "true", "plugin": { "_id": "66f3b2c5d6e7f80012345679", "title": "order_lookup", "name": "Order lookup", "human_description": "Looks up an order by its reference number.", "isPublic": false, "isOwner": true } } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/users/enterprise/searchPlugin": { "post": { "operationId": "plugins_search", "summary": "Search plugins", "description": "Free-text search across plugin titles, names and descriptions.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.search\n\n- Same empty-result shape as the list: no `plugin` key when nothing matched.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "view" }, "parameters": [ { "name": "search", "in": "query", "required": true, "description": "", "example": "order", "schema": { "type": "string" } }, { "name": "os", "in": "query", "required": false, "description": "", "example": "all", "schema": { "type": "string", "default": "all" } }, { "name": "page", "in": "query", "required": false, "description": "", "example": "1", "schema": { "type": "number", "default": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "", "example": "20", "schema": { "type": "number", "default": "20" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalPlugins": { "type": "integer" }, "totalPages": { "type": "integer" }, "currentPage": { "type": "integer" }, "plugin": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "totalPlugins": 1, "totalPages": 1, "currentPage": 1, "plugin": [ { "_id": "66f3b2c5d6e7f80012345679", "title": "order_lookup" } ], "tags": [ "new", "all", "connected" ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/plugin/enterprise/createGlobalPlugin": { "post": { "operationId": "plugins_create", "summary": "Create a plugin", "description": "Publishes a new plugin to the account's catalog. Every field in the required list must be present — the server checks for presence, not truthiness, so send false and [] explicitly rather than omitting them.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.create\n\n- A missing required field returns **404** with a single message naming all of them at once. A duplicate title returns **400**.\n- Titles are reserved platform-wide. `browser_search` and `code_interpreter` are AvA's built-ins and are rejected outright.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "edit" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Unique identity, snake_case by convention. Also the function name the model calls." }, "name": { "type": "string", "description": "Display name." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "" }, "authentication_required": { "type": "boolean", "description": "When true, connection_url becomes required too." }, "os": { "type": "array", "items": { "type": "string" }, "description": "Platforms the plugin can run on: nt, android, web." }, "human_description": { "type": "string", "description": "What it does, for the person browsing the catalog." }, "ai_description": { "type": "string", "description": "What it does, for the model deciding whether to call it. Say when to call it and what comes back — this is the text the assistant reasons over." }, "parameters": { "type": "object", "description": "JSON-Schema object describing the arguments." }, "func_schema": { "type": "string", "description": "The tool schema the model is shown, as a JSON string." }, "func_run": { "type": "string", "description": "The Python body. Must define `def _run(self, …)` whose parameters match your schema. Encrypted at rest." }, "isPublic": { "type": "boolean", "description": "Publish to the platform-wide catalog." }, "isAnonymous": { "type": "boolean", "description": "Hide the author's name on the catalog card." }, "connection_url": { "type": "string", "description": "OAuth / connection endpoint. Required when authentication_required is true." }, "logo": { "type": "string", "description": "Absolute image URL." }, "is_agentic_tool": { "type": "object", "description": "{ status, object } — defaults to { status: false, object: null }." } }, "required": [ "title", "name", "tags", "authentication_required", "os", "human_description", "ai_description", "parameters", "func_schema", "func_run", "isPublic", "isAnonymous" ] }, "example": { "title": "order_lookup", "name": "Order lookup", "tags": [ "commerce" ], "authentication_required": false, "os": [ "nt" ], "human_description": "Looks up an order by its reference number.", "ai_description": "Call this when the customer gives an order number and wants its status. Returns the status string and the courier's tracking URL.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The customer's order reference." } }, "required": [ "order_id" ] }, "func_schema": "{\"name\":\"order_lookup\",\"description\":\"Look up an order by reference\",\"parameters\":{\"type\":\"object\",\"properties\":{\"order_id\":{\"type\":\"string\"}},\"required\":[\"order_id\"]}}", "func_run": "def _run(self, order_id):\n import requests\n r = requests.get(f\"https://api.example.com/orders/{order_id}\")\n r.raise_for_status()\n data = r.json()\n return {\"status\": data[\"status\"], \"tracking_url\": data[\"tracking_url\"]}\n", "isPublic": false, "isAnonymous": false, "logo": "https://cdn.example.com/plugins/order-lookup.png" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "plugin created successfully" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/plugin/enterprise/updateGlobalPlugin": { "put": { "operationId": "plugins_update", "summary": "Update a plugin", "description": "Partial update, addressed by title.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.update\n\n- Sending any of `_id`, `userId`, `status`, `appVersion`, `createdAt` or `__v` is rejected with **404** `Invalid Body`. Strip a document you fetched before you send it back.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "edit" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Identifies the plugin. Cannot itself be changed here." }, "name": { "type": "string", "description": "" }, "human_description": { "type": "string", "description": "" }, "ai_description": { "type": "string", "description": "" }, "parameters": { "type": "object", "description": "" }, "func_schema": { "type": "string", "description": "" }, "func_run": { "type": "string", "description": "" }, "isPublic": { "type": "boolean", "description": "" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "" }, "os": { "type": "array", "items": { "type": "string" }, "description": "" }, "logo": { "type": "string", "description": "" } }, "required": [ "title" ] }, "example": { "title": "order_lookup", "ai_description": "Call this when the customer gives an order number. Returns the status, the courier and the tracking URL." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "plugin updated successfully" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/plugin/enterprise/deleteGlobalPlugin": { "delete": { "operationId": "plugins_delete", "summary": "Delete a plugin", "description": "Removes the plugin from both catalogs. Assistants that referenced it lose the capability on their next turn.\n\nPermalink: https://console.ava.pathor.ai/api-docs#plugins.delete\n\n- Check **List assistants** for `accessible_plugin` references first — nothing blocks the delete, and the assistants simply stop being able to call it.", "tags": [ "Plugins" ], "x-ava-scope": { "module": "plugins", "level": "manage" }, "x-ava-destructive": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "" } }, "required": [ "title" ] }, "example": { "title": "order_lookup" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "status": true, "message": "plugin deleted successfully" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb": { "get": { "operationId": "kb_list", "summary": "List knowledge bases", "description": "Every knowledge base on the account, with its document count and size.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.list\n\n- `liveSourcesCount` counts inline-tier documents — the ones that sit in the assistant's context every turn instead of being retrieved. They are the expensive ones, which is why they are counted apart from the rest.\n- `shared` is true for a base another account owns and granted to you.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "view" }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbs": { "type": "array", "items": { "type": "object", "properties": { "kbId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "docsCount": { "type": "integer" }, "totalSize": { "type": "integer" }, "liveSourcesCount": { "type": "integer" }, "autoRefresh": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "intervalDays": { "type": "integer" }, "lastRefreshedAt": { "nullable": true }, "nextRefreshAt": { "nullable": true } } }, "createdAt": { "type": "string" }, "shared": { "type": "boolean" } } } } } }, "example": { "status": "ok", "kbs": [ { "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "name": "Orion product docs", "description": "Public manuals and the returns policy.", "docsCount": 14, "totalSize": 2841203, "liveSourcesCount": 1, "autoRefresh": { "enabled": false, "intervalDays": 3, "lastRefreshedAt": null, "nextRefreshAt": null }, "createdAt": "2026-06-19T11:02:41.882Z", "shared": false } ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } }, "post": { "operationId": "kb_create", "summary": "Create a knowledge base", "description": "Returns the kbId every other call in this section takes. It is a UUID, not a Mongo _id.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.create\n\n- Answers **201**, not 200 — the only endpoint in this reference that does. Branch on `res.ok`, not on `status === 200`.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "description": { "type": "string", "description": "" } }, "required": [ "name" ] }, "example": { "name": "Orion product docs", "description": "Public manuals and the returns policy." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "name": "Orion product docs", "description": "Public manuals and the returns policy." } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}": { "delete": { "operationId": "kb_delete", "summary": "Delete a knowledge base", "description": "The base, every document in it and every vector. Permanent.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.delete", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "manage" }, "x-ava-destructive": true, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "deleted": { "type": "boolean" }, "kbId": { "type": "string" } } }, "example": { "status": "ok", "deleted": true, "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/ingest-text": { "post": { "operationId": "kb_ingestText", "summary": "Ingest text", "description": "The workhorse. You extract the text, this chunks and embeds it. Use it for anything you can already read as a string.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.ingestText\n\n- An inline-tier document answers with `{ docId, mode, inlineChars, digestMethod, crawledChars }` instead of `chunksCreated`.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The document body." }, "title": { "type": "string", "description": "How it is listed, and what a retrieval cites." }, "mimeType": { "type": "string", "description": "" }, "source": { "type": "string", "description": "Free-text provenance label kept on the document." }, "mode": { "type": "string", "enum": [ "auto", "vector", "inline" ], "description": "vector chunks and embeds it for retrieval. inline keeps it whole and hands it to the assistant every turn — right for a short policy, expensive for a manual. auto decides on length." } }, "required": [ "text", "title" ] }, "example": { "title": "Returns policy 2026", "text": "Orion accepts returns within 30 days of delivery, provided the item is unused and in its original packaging. Refunds are issued to the original payment method within 5 working days of the item reaching our warehouse.", "mimeType": "text/plain", "source": "handbook", "mode": "auto" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "docId": { "type": "string" }, "chunksCreated": { "type": "integer" }, "title": { "type": "string" }, "kbId": { "type": "string" } } }, "example": { "status": "ok", "docId": "b81e5c0a-7d33-4f2e-9c11-2a4f6d8e0b55", "chunksCreated": 3, "title": "Returns policy 2026", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/ingest-url": { "post": { "operationId": "kb_ingestUrl", "summary": "Ingest a URL", "description": "The server fetches the page, extracts its text and ingests that.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.ingestUrl\n\n- A JavaScript-rendered page usually yields nothing useful. Extract the text yourself and use **Ingest text** when that happens.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "" }, "title": { "type": "string", "description": "Defaults to the page title." } }, "required": [ "url" ] }, "example": { "url": "https://example.com/returns", "title": "Returns policy" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "docId": { "type": "string" }, "mode": { "type": "string" }, "chunksCreated": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "kbId": { "type": "string" } } }, "example": { "status": "ok", "docId": "c92f6d1b-8e44-4a3f-8d22-3b5e7f9a1c66", "mode": "vector", "chunksCreated": 5, "title": "Returns policy", "url": "https://example.com/returns", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/ingest": { "post": { "operationId": "kb_ingestFile", "summary": "Upload a file", "description": "multipart/form-data with a `file` part and an optional `title`. PDF, DOCX, TXT and MD.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.ingestFile\n\n- A **scanned** PDF has no extractable text layer and ingests as an empty document. The console OCRs those in the browser before sending; from a server, OCR first and use **Ingest text**.\n- Not runnable from the playground — it needs a real multipart body. The snippets below are complete.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The multipart file part." }, "title": { "type": "string", "description": "Defaults to the filename." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "docId": { "type": "string" }, "chunksCreated": { "type": "integer" }, "title": { "type": "string" }, "kbId": { "type": "string" } } }, "example": { "status": "ok", "docId": "d03a7e2c-9f55-4b40-9e33-4c6f80ab2d77", "chunksCreated": 41, "title": "orion-manual.pdf", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/documents": { "get": { "operationId": "kb_documents", "summary": "List documents", "description": "Everything in the base, with per-document chunk counts and tier.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.documents", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "view" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "docId": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "string" }, "mimeType": { "type": "string" }, "chunksCount": { "type": "integer" }, "fileSize": { "type": "integer" }, "mode": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "documents": [ { "docId": "b81e5c0a-7d33-4f2e-9c11-2a4f6d8e0b55", "title": "Returns policy 2026", "source": "handbook", "mimeType": "text/plain", "chunksCount": 3, "fileSize": 1420, "mode": "vector", "createdAt": "2026-07-11T08:20:14.512Z" } ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/documents/{docId}": { "delete": { "operationId": "kb_deleteDocument", "summary": "Delete a document", "description": "Drops the document and its vectors. The rest of the base is untouched.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.deleteDocument", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "manage" }, "x-ava-destructive": true, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } }, { "name": "docId", "in": "path", "required": true, "description": "", "example": "b81e5c0a-7d33-4f2e-9c11-2a4f6d8e0b55", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "deleted": { "type": "boolean" }, "docId": { "type": "string" }, "kbId": { "type": "string" } } }, "example": { "status": "ok", "deleted": true, "docId": "b81e5c0a-7d33-4f2e-9c11-2a4f6d8e0b55", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13" } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/query": { "post": { "operationId": "kb_query", "summary": "Query a knowledge base", "description": "Semantic search over the base — the same retrieval an assistant runs, exposed directly. Use it to check what your assistant would actually be shown.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.query\n\n- A read behind a POST, so it needs only **Read** on Knowledge Base despite the verb.\n- Chunks whose document has since been deleted are filtered out of the result rather than returned as orphans.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "view" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Natural language." }, "topK": { "type": "number", "description": "Chunks to return. Capped at 20." } }, "required": [ "query" ] }, "example": { "query": "How long do I have to return something?", "topK": 3 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "score": { "type": "number" }, "docTitle": { "type": "string" }, "docId": { "type": "string" }, "chunkIndex": { "type": "integer" } } } } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "results": [ { "text": "Orion accepts returns within 30 days of delivery, provided the item is unused…", "score": 0.8821, "docTitle": "Returns policy 2026", "docId": "b81e5c0a-7d33-4f2e-9c11-2a4f6d8e0b55", "chunkIndex": 0 } ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/stats": { "get": { "operationId": "kb_stats", "summary": "Knowledge base stats", "description": "Counts and sizes for one base — cheap enough to poll after an ingest.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.stats", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "view" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "documentsCount": { "type": "integer" }, "vectorCount": { "type": "integer" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "documentsCount": 14, "vectorCount": 312 } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/persona/{personaId}": { "get": { "operationId": "kb_personaKbs", "summary": "Bases attached to an assistant", "description": "Which knowledge bases one assistant can retrieve from, and how.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.personaKbs", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "view" }, "parameters": [ { "name": "personaId", "in": "path", "required": true, "description": "The customPersonaId.", "example": "orion-support", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "personaId": { "type": "string" }, "kbs": { "type": "array", "items": { "type": "object", "properties": { "kbId": { "type": "string" }, "enabled": { "type": "boolean" }, "grounding_mode": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "docsCount": { "type": "integer" }, "totalSize": { "type": "integer" } } } } } }, "example": { "status": "ok", "personaId": "orion-support", "kbs": [ { "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "enabled": true, "grounding_mode": "supplemental", "name": "Orion product docs", "description": "Public manuals and the returns policy.", "docsCount": 14, "totalSize": 2841203 } ] } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/personas/{personaId}": { "post": { "operationId": "kb_attach", "summary": "Attach a base to an assistant", "description": "Gives the assistant retrieval over this base from its next turn onward.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.attach\n\n- **An assistant may hold at most three knowledge bases.** A fourth is a 400. Merge related material into one base rather than splitting it finely.\n- Re-posting a base that is already attached updates it instead, and answers `updated: true` rather than `attached: true`.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "description": "", "example": "orion-support", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grounding_mode": { "type": "string", "enum": [ "strict", "supplemental" ], "description": "strict confines the assistant to what it retrieves and makes it say so when it finds nothing. supplemental lets it answer from its own knowledge as well." }, "enabled": { "type": "boolean", "description": "" } } }, "example": { "grounding_mode": "supplemental", "enabled": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "personaId": { "type": "string" }, "grounding_mode": { "type": "string" }, "enabled": { "type": "boolean" }, "attached": { "type": "boolean" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "personaId": "orion-support", "grounding_mode": "supplemental", "enabled": true, "attached": true } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } }, "patch": { "operationId": "kb_updateAttachment", "summary": "Update an attachment", "description": "Change grounding mode, or switch a base off for one assistant without detaching it.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.updateAttachment", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "description": "", "example": "orion-support", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grounding_mode": { "type": "string", "enum": [ "strict", "supplemental" ], "description": "" }, "enabled": { "type": "boolean", "description": "" } } }, "example": { "grounding_mode": "strict" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "personaId": { "type": "string" }, "updated": { "type": "boolean" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "personaId": "orion-support", "updated": true } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } }, "delete": { "operationId": "kb_detach", "summary": "Detach a base", "description": "Removes the link. The base and its documents survive.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.detach\n\n- Only **Read & write**, not Full control — detaching an assistant destroys nothing, so it is not held to the same bar as deleting a base.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "description": "", "example": "orion-support", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "personaId": { "type": "string" }, "detached": { "type": "boolean" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "personaId": "orion-support", "detached": true } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/auto-refresh": { "patch": { "operationId": "kb_autoRefresh", "summary": "Schedule a re-crawl", "description": "Re-fetch every URL-sourced document in the base on an interval.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.autoRefresh", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "intervalDays": { "type": "number", "description": "Use with intervalHours." }, "intervalHours": { "type": "number", "description": "" } }, "required": [ "enabled" ] }, "example": { "enabled": true, "intervalDays": 7, "intervalHours": 0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "autoRefresh": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "intervalDays": { "type": "integer" }, "lastRefreshedAt": { "nullable": true }, "nextRefreshAt": { "type": "string" } } } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "autoRefresh": { "enabled": true, "intervalDays": 7, "lastRefreshedAt": null, "nextRefreshAt": "2026-08-27T09:00:00.000Z" } } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } }, "/kb/{kbId}/refresh-now": { "post": { "operationId": "kb_refreshNow", "summary": "Re-crawl now", "description": "Kicks the refresh immediately rather than waiting for the schedule. Returns as soon as the job is queued.\n\nPermalink: https://console.ava.pathor.ai/api-docs#kb.refreshNow\n\n- Only URL-sourced documents are re-crawled. An uploaded file or pasted text has no source to re-fetch, so it is left alone.", "tags": [ "Knowledge Base" ], "x-ava-scope": { "module": "knowledgeBase", "level": "edit" }, "parameters": [ { "name": "kbId", "in": "path", "required": true, "description": "", "example": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "kbId": { "type": "string" }, "refreshedDocs": { "type": "integer" }, "autoRefresh": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "intervalDays": { "type": "integer" }, "lastRefreshedAt": { "type": "string" }, "nextRefreshAt": { "type": "string" } } }, "message": { "type": "string" } } }, "example": { "status": "ok", "kbId": "3f6b1c22-8f0e-4a71-9a2e-5c1d0f9b7a13", "refreshedDocs": 4, "autoRefresh": { "enabled": true, "intervalDays": 7, "lastRefreshedAt": "2026-08-20T09:41:02.771Z", "nextRefreshAt": "2026-08-27T09:41:02.771Z" }, "message": "Successfully re-indexed 4 URL document(s)." } } } }, "403": { "$ref": "#/components/responses/ScopeDenied" } } } } }, "externalDocs": { "description": "Human-readable reference with a live playground", "url": "https://console.ava.pathor.ai/api-docs" } }