{"openapi":"3.1.0","info":{"title":"AiServa API","version":"1.3.0","description":"Run AI Agent tasks, search knowledge, manage memory and receive signed webhooks. Every request runs as the person who created the key, with their rights today."},"servers":[{"url":"https://aiserva.com/app/api/v1/index.php"}],"security":[{"ApiKey":[]}],"paths":{"/health":{"get":{"tags":["Account"],"summary":"Health Check","description":"Is the API up. Needs no key.","operationId":"healthCheck","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"time":{"type":"string"}}},"example":{"status":"ok","version":"v1","time":"2026-09-30T02:14:05+00:00"}}}}},"security":[]}},"/me":{"get":{"tags":["Account"],"summary":"Who Am I","description":"The key you sent: its name, permissions, organisation and expiry.","operationId":"whoAmI","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"organisation":{"type":"string"},"env":{"type":"string"},"pinned_app":{"type":"null"},"expires_at":{"type":"null"}}},"example":{"object":"key","name":"Order Portal","scopes":["tasks:read","tasks:write"],"organisation":"China Harbour","env":"live","pinned_app":null,"expires_at":null}}}}}}},"/models":{"get":{"tags":["AI Agent Tasks"],"summary":"List Models","description":"The models the key's creator may use in AI Agent, default first, and whether a model may be picked. Permission: tasks:read.","operationId":"listModels","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"where":{"type":"string"},"reads_images":{"type":"boolean"},"effort":{"type":"boolean"},"default":{"type":"boolean"}}}},"can_pick":{"type":"boolean"},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"id":17,"name":"Qwen3 32B","where":"Local","reads_images":false,"effort":true,"default":true}],"can_pick":true,"has_more":false,"next_cursor":null}}}}}}},"/tasks":{"post":{"tags":["AI Agent Tasks"],"summary":"Start a Task","description":"Starts a new AI Agent task with its first message and returns the run (202 Accepted, status queued). The run happens in the background as the key's creator, with the organisation's models, tools, knowledge, Rules and limits. Permission: tasks:write.","operationId":"startATask","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}},"output":{"type":"object","properties":{"message_id":{"type":"integer"},"text":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"bytes":{"type":"integer"}}}}}},"trace_id":{"type":"string"},"model":{"type":"string"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"estimated_cost":{"type":"integer"},"tool_calls":{"type":"integer"},"refused_steps":{"type":"integer"}}}}},"example":{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"},"output":{"message_id":99120,"text":"The quotation is ready: 3 lines, total RM 12,480.00 including 8% SST.","files":[{"id":3301,"name":"Quotation QT-0192.pdf","type":"pdf","bytes":48211}]},"trace_id":"4f1c9a07be2d8e61","model":"Qwen3 32B","usage":{"input_tokens":18204,"output_tokens":911,"estimated_cost":0,"tool_calls":3,"refused_steps":0}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"What AI Agent should do, in plain words (up to 20,000 characters). Write it complete: nobody can answer questions during the run."},"model":{"type":"integer","description":"A model id from GET /models. Leave it out to use the organisation's default."},"effort":{"type":"string","description":"auto (default), low, medium or high. Sets how many steps AI Agent may take and, for models that support it, how hard it thinks."},"metadata":{"type":"object","description":"Up to 16 of your own string keys and values (for example your order number). Returned on the run and in webhooks; AI Agent never reads it."},"wait":{"type":"integer","description":"Seconds (1 to 10) to wait for the run to finish before answering. Without it you get 202 at once and poll or take the webhook."},"title":{"type":"string","description":"A title for the task in AI Agent (it starts with \"API: \"). Defaults to the start of the input."}},"required":["input"]}}}}},"get":{"tags":["AI Agent Tasks"],"summary":"List Tasks","description":"Tasks started with this key, newest first. scope=all lists every AI Agent task of the key's creator. Permission: tasks:read.","operationId":"listTasks","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"title":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"archived":{"type":"boolean"},"latest_run":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}}}}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"object":"task","id":4410,"title":"API: Quote for Kestrel Marine","created_at":"2026-09-30T02:14:05+00:00","updated_at":"2026-09-30T02:14:41+00:00","archived":false,"latest_run":{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"}}}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"scope","in":"query","required":false,"description":"key (default) or all","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 100, default 20","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page","schema":{"type":"string"}}]}},"/tasks/{id}":{"get":{"tags":["AI Agent Tasks"],"summary":"Get a Task","description":"One task with its latest run. Permission: tasks:read.","operationId":"getATask","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"title":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"archived":{"type":"boolean"},"latest_run":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}}}}}},"example":{"object":"task","id":4410,"title":"API: Quote for Kestrel Marine","created_at":"2026-09-30T02:14:05+00:00","updated_at":"2026-09-30T02:14:41+00:00","archived":false,"latest_run":{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"}}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/tasks/{id}/messages":{"post":{"tags":["AI Agent Tasks"],"summary":"Continue a Task","description":"Sends the next message in a task (AI Agent sees the whole conversation) and returns the new run. 409 while a run is still working in that task. Permission: tasks:write.","operationId":"continueATask","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}},"output":{"type":"object","properties":{"message_id":{"type":"integer"},"text":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"bytes":{"type":"integer"}}}}}},"trace_id":{"type":"string"},"model":{"type":"string"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"estimated_cost":{"type":"integer"},"tool_calls":{"type":"integer"},"refused_steps":{"type":"integer"}}}}},"example":{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"},"output":{"message_id":99120,"text":"The quotation is ready: 3 lines, total RM 12,480.00 including 8% SST.","files":[{"id":3301,"name":"Quotation QT-0192.pdf","type":"pdf","bytes":48211}]},"trace_id":"4f1c9a07be2d8e61","model":"Qwen3 32B","usage":{"input_tokens":18204,"output_tokens":911,"estimated_cost":0,"tool_calls":3,"refused_steps":0}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"What AI Agent should do, in plain words (up to 20,000 characters). Write it complete: nobody can answer questions during the run."},"model":{"type":"integer","description":"A model id from GET /models. Leave it out to use the organisation's default."},"effort":{"type":"string","description":"auto (default), low, medium or high. Sets how many steps AI Agent may take and, for models that support it, how hard it thinks."},"metadata":{"type":"object","description":"Up to 16 of your own string keys and values (for example your order number). Returned on the run and in webhooks; AI Agent never reads it."},"wait":{"type":"integer","description":"Seconds (1 to 10) to wait for the run to finish before answering. Without it you get 202 at once and poll or take the webhook."}},"required":["input"]}}}}},"get":{"tags":["AI Agent Tasks"],"summary":"List Messages","description":"The conversation, oldest first: your messages and AI Agent's answers with the files it made. Permission: tasks:read.","operationId":"listMessages","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"role":{"type":"string"},"text":{"type":"string"},"files":{"type":"array","items":{}},"created_at":{"type":"string"}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"object":"message","id":99119,"role":"user","text":"Quote 3 lines for Kestrel Marine...","files":[],"created_at":"2026-09-30T02:14:05+00:00"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"1 to 100, default 50","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page","schema":{"type":"string"}}]}},"/tasks/{id}/runs":{"get":{"tags":["AI Agent Tasks"],"summary":"List Runs of a Task","description":"Every API run in the task, newest first. Permission: tasks:read.","operationId":"listRunsOfATask","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}},"trace_id":{"type":"string"},"model":{"type":"string"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"estimated_cost":{"type":"integer"},"tool_calls":{"type":"integer"},"refused_steps":{"type":"integer"}}}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"},"trace_id":"4f1c9a07be2d8e61","model":"Qwen3 32B","usage":{"input_tokens":18204,"output_tokens":911,"estimated_cost":0,"tool_calls":3,"refused_steps":0}}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/tasks/{id}/stop":{"post":{"tags":["AI Agent Tasks"],"summary":"Stop a Task","description":"Stops the running answer and any queued run in the task. The run ends as stopped. Permission: tasks:write.","operationId":"stopATask","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer"},"stopped":{"type":"boolean"}}},"example":{"task_id":4410,"stopped":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}]}},"/runs/{id}":{"get":{"tags":["AI Agent Tasks"],"summary":"Get a Run","description":"A run's status and, when completed, AI Agent's answer and files. Add ?wait=N (up to 10) to wait for it to finish. Permission: tasks:read.","operationId":"getARun","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error":{"type":"null"},"metadata":{"type":"object","properties":{"order_ref":{"type":"string"}}},"output":{"type":"object","properties":{"message_id":{"type":"integer"},"text":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"bytes":{"type":"integer"}}}}}},"trace_id":{"type":"string"},"model":{"type":"string"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"estimated_cost":{"type":"integer"},"tool_calls":{"type":"integer"},"refused_steps":{"type":"integer"}}}}},"example":{"object":"run","id":812,"task_id":4410,"status":"completed","created_at":"2026-09-30T02:14:05+00:00","started_at":"2026-09-30T02:14:06+00:00","finished_at":"2026-09-30T02:14:41+00:00","error":null,"metadata":{"order_ref":"SO-20931"},"output":{"message_id":99120,"text":"The quotation is ready: 3 lines, total RM 12,480.00 including 8% SST.","files":[{"id":3301,"name":"Quotation QT-0192.pdf","type":"pdf","bytes":48211}]},"trace_id":"4f1c9a07be2d8e61","model":"Qwen3 32B","usage":{"input_tokens":18204,"output_tokens":911,"estimated_cost":0,"tool_calls":3,"refused_steps":0}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"wait","in":"query","required":false,"description":"Seconds to wait for completion, 0 to 10","schema":{"type":"integer"}}]}},"/files/{id}":{"get":{"tags":["AI Agent Tasks"],"summary":"Get a File","description":"A file AI Agent made: name, type and size. Permission: tasks:read.","operationId":"getAFile","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"bytes":{"type":"integer"},"task_id":{"type":"integer"},"message_id":{"type":"integer"},"created_at":{"type":"string"}}},"example":{"object":"file","id":3301,"name":"Quotation QT-0192.pdf","type":"pdf","bytes":48211,"task_id":4410,"message_id":99120,"created_at":"2026-09-30T02:14:41+00:00"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/files/{id}/content":{"get":{"tags":["AI Agent Tasks"],"summary":"Download a File","description":"The file itself (PDF, Word, Excel, PowerPoint, CSV, Markdown, text, JSON or HTML), always as a download. Permission: tasks:read.","operationId":"downloadAFile","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/knowledge-bases":{"get":{"tags":["Knowledge Bases"],"summary":"List Knowledge Bases","description":"The knowledge bases the key's creator may search through AI Agent. Local Only knowledge bases never leave the organisation's own servers, so they are listed under not_searchable_here. Permission: knowledge:read.","operationId":"listKnowledgeBases","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"}}}},"not_searchable_here":{"type":"array","items":{"type":"string"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"id":9,"name":"Contracts","description":"Signed contracts and variations"}],"not_searchable_here":["Outlook Mail"],"has_more":false,"next_cursor":null}}}}}}},"/knowledge-bases/search":{"post":{"tags":["Knowledge Bases"],"summary":"Search Knowledge","description":"Finds passages by meaning and keywords, with the same access rules as AI Agent. Permission: knowledge:read.","operationId":"searchKnowledge","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"knowledge_base_id":{"type":"integer"},"document_id":{"type":"integer"},"title":{"type":"string"},"page":{"type":"integer"},"section":{"type":"string"},"text":{"type":"string"},"score":{"type":"number"}}}},"errors":{"type":"array","items":{}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"knowledge_base_id":9,"document_id":1204,"title":"Kestrel Marine MSA 2025.pdf","page":4,"section":"7 Payment Terms","text":"Invoices are payable within 45 days...","score":0.8412}],"errors":[],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"What to look for (2 to 500 characters)."},"knowledge_base_ids":{"type":"array","description":"Search only these (ids from the list).","items":{"type":"integer"}},"limit":{"type":"integer","description":"1 to 20, default 8"}},"required":["query"]}}}}}},"/memories":{"get":{"tags":["Memory"],"summary":"List Memories","description":"The key creator's own memories. status: active (default), pending_review or all. as_of=YYYY-MM-DD rebuilds what was known that day. Permission: memories:read.","operationId":"listMemories","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"memory":{"type":"string"},"status":{"type":"string"},"origin":{"type":"string"},"verification":{"type":"string"},"pinned":{"type":"boolean"},"revision":{"type":"integer"},"created":{"type":"string"},"updated":{"type":"string"},"times_used":{"type":"integer"}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"id":12,"type":"preference","memory":"Prefers answers in Malay","status":"active","origin":"app","verification":"stated","pinned":false,"revision":3,"created":"2026-09-01 04:12:00","updated":"2026-09-20 09:40:00","times_used":14}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"q","in":"query","required":false,"description":"words to match","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"fact, preference, ...","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"active, pending_review or all","schema":{"type":"string"}},{"name":"as_of","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 100","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor","schema":{"type":"string"}}]},"post":{"tags":["Memory"],"summary":"Add a Memory","description":"Screened like every memory (no secrets, no hidden instructions); the review policy may hold it. 201 with action added, reinforced, revised, superseded or held. 422 policy:secret, policy:injection, policy:consent, policy:gov_id, policy:bank, policy:never or policy:guardrail when a safeguard refuses it. Permission: memories:write.","operationId":"addAMemory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"action":{"type":"string"},"status":{"type":"string"}}},"example":{"id":31,"action":"added","status":"active"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memory":{"type":"string","description":"The memory text"},"type":{"type":"string","description":"fact (default), preference, ..."}},"required":["memory"]}}}}}},"/me/memories":{"get":{"tags":["Memory"],"summary":"Export Memories","description":"Everything the key creator's memory holds, with origin, verification and revision. Permission: memories:read.","operationId":"exportMemories","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"cursor","in":"query","required":false,"description":"next_cursor","schema":{"type":"string"}}]}},"/memories/search":{"post":{"tags":["Memory"],"summary":"Search Memories","description":"Hybrid recall (keywords, full text and meaning). Reading here does not count as use. Permission: memories:read.","operationId":"searchMemories","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"What to find"},"limit":{"type":"integer","description":"1 to 15"},"as_of":{"type":"string","description":"YYYY-MM-DD"}},"required":["query"]}}}}}},"/memories/{id}":{"get":{"tags":["Memory"],"summary":"Get a Memory","description":"One memory; the ETag is its revision. Permission: memories:read.","operationId":"getAMemory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]},"patch":{"tags":["Memory"],"summary":"Change a Memory","description":"Send If-Match with the revision you read (or \"revision\" in the body). 409 revision_conflict if someone changed it first; 428 without a revision. Permission: memories:write.","operationId":"changeAMemory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memory":{"type":"string","description":"The new text"},"type":{"type":"string","description":"Its type"},"revision":{"type":"integer","description":"Instead of If-Match"}},"required":["memory"]}}}}},"delete":{"tags":["Memory"],"summary":"Delete a Memory","description":"Forgets it and its history text; the tombstone id stops it coming back from an import. Permission: memories:write.","operationId":"deleteAMemory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"deleted":{"type":"boolean"},"tombstone":{"type":"integer"}}},"example":{"id":12,"deleted":true,"tombstone":88}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/memories/{id}/history":{"get":{"tags":["Memory"],"summary":"Memory History","description":"Every version of one memory, newest first. Permission: memories:read.","operationId":"memoryHistory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/memories/{id}/pin":{"post":{"tags":["Memory"],"summary":"Pin a Memory","description":"A pinned memory is always given to the AI. Permission: memories:write.","operationId":"pinAMemory","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"pinned":{"type":"boolean"}}},"example":{"id":12,"pinned":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pinned":{"type":"boolean","description":"true to pin, false to unpin"}},"required":["pinned"]}}}}}},"/apps":{"get":{"tags":["Organisation"],"summary":"List Apps","description":"The apps the key's creator may open. Permission: apps:read.","operationId":"listApps","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"app":{"type":"string"},"name":{"type":"string"},"slots":{"type":"array","items":{"type":"string"}}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"}}},"example":{"data":[{"app":"agent","name":"AI Agent","slots":["chat"]}],"has_more":false,"next_cursor":null}}}}}}},"/usage":{"get":{"tags":["Organisation"],"summary":"Usage","description":"Requests and errors per app per day, last 30 days. Needs the creator to have the Usage right. Permission: usage:read.","operationId":"usage","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"app":{"type":"string"},"requests":{"type":"integer"},"errors":{"type":"integer"}}}}}},"example":{"data":[{"day":"2026-09-29","app":"agent","requests":412,"errors":3}]}}}}}}},"/reports":{"get":{"tags":["Organisation"],"summary":"List Reports","description":"Your organisation's bug reports and feature requests to AiServa (everyone's with the Bug Reports right, otherwise the creator's own). Permission: reports:read.","operationId":"listReports","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"type","in":"query","required":false,"description":"bug or feature","schema":{"type":"string"}}]},"post":{"tags":["Organisation"],"summary":"File a Report","description":"Reports a bug or asks for a feature. 201 with the report. Permission: reports:write.","operationId":"fileAReport","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"bug or feature"},"description":{"type":"string","description":"What happened or what you need (10 to 10,000 characters)."}},"required":["type","description"]}}}}}},"/reports/{id}":{"get":{"tags":["Organisation"],"summary":"Get a Report","description":"One report with its messages. Permission: reports:read.","operationId":"getAReport","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/reports/{id}/messages":{"post":{"tags":["Organisation"],"summary":"Reply to a Report","description":"Adds your reply. Permission: reports:write.","operationId":"replyToAReport","responses":{"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}},"example":{"ok":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe (up to 100 characters).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Your message"},"reopen":{"type":"boolean","description":"true to open a closed report again (default false). Only the person who filed it or someone who may edit Bug Reports can reply."}},"required":["body"]}}}}}}},"webhooks":{"task.completed":{"post":{"summary":"task.completed","description":"An AI Agent run started through the API finished with an answer. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"task.completed"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"run_id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"key_id":{"type":"integer"},"metadata":{"type":"object"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"task.failed":{"post":{"summary":"task.failed","description":"An AI Agent run started through the API failed or was stopped. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"task.failed"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"run_id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"key_id":{"type":"integer"},"metadata":{"type":"object"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"scheduled_task.completed":{"post":{"summary":"scheduled_task.completed","description":"A scheduled task ran and finished. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"scheduled_task.completed"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"scheduled_task_id":{"type":"integer"},"execution_id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"paused":{"type":"boolean"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"scheduled_task.failed":{"post":{"summary":"scheduled_task.failed","description":"A scheduled task run failed (after 3 failures in a row it is paused). Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"scheduled_task.failed"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"scheduled_task_id":{"type":"integer"},"execution_id":{"type":"integer"},"task_id":{"type":"integer"},"status":{"type":"string"},"paused":{"type":"boolean"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"approval.requested":{"post":{"summary":"approval.requested","description":"Someone asked for an approval. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"approval.requested"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"approval_id":{"type":"integer"},"action":{"type":"string"},"requester_id":{"type":"integer"},"stage":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"approval.decided":{"post":{"summary":"approval.decided","description":"An approval was approved or rejected. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"approval.decided"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"approval_id":{"type":"integer"},"action":{"type":"string"},"status":{"type":"string"},"decided_by":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"agent.emergency_stop":{"post":{"summary":"agent.emergency_stop","description":"Emergency Stop was turned on or lifted for AI Agent. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"agent.emergency_stop"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"on":{"type":"boolean"},"stopped_runs":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"server.online":{"post":{"summary":"server.online","description":"An AI server came online. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"server.online"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"server_id":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"server.offline":{"post":{"summary":"server.offline","description":"An AI server went offline. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"server.offline"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"server_id":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"user.created":{"post":{"summary":"user.created","description":"A person was added to the organisation. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"user.created"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"user_id":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"user.updated":{"post":{"summary":"user.updated","description":"A person was changed or turned on again. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"user.updated"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"user_id":{"type":"integer"},"status":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"user.deactivated":{"post":{"summary":"user.deactivated","description":"A person was turned off. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"user.deactivated"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"user_id":{"type":"integer"},"status":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"app.binding.changed":{"post":{"summary":"app.binding.changed","description":"Which model or knowledge base an app uses changed. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"app.binding.changed"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"app":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"subscription.ending":{"post":{"summary":"subscription.ending","description":"The subscription ends in 7 days, then again 1 day before. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"subscription.ending"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"notice":{"type":"string"},"ends_on":{"type":"string"},"days_left":{"type":"integer"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"subscription.ended":{"post":{"summary":"subscription.ended","description":"The subscription ended. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"subscription.ended"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"notice":{"type":"string"},"ends_on":{"type":"string"},"ended_at":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}},"report.updated":{"post":{"summary":"report.updated","description":"A bug report or feature request got a reply or a new status. Signed with X-Aiserva-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of \"event_id.time.body\">.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"report.updated"},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"report_id":{"type":"integer"},"type":{"type":"string"},"change":{"type":"string"},"status":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Received. Anything else is retried."}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":"string"}}}}}}}}