{ "openapi": "3.1.0", "info": { "title": "AiHummer API", "version": "v1.0", "description": "The **AiHummer API** is the HTTP control surface of a self-hosted AiHummer instance — a host-native AI-agent platform for business.\nIt exposes an **OpenAI-compatible chat endpoint** plus the full **admin / operations API** (agents, conversations, knowledge, memory, modules, security, analytics and more).\n\n## Base URL\nEvery path is relative to your own instance, e.g. `https://your-instance.example.com`. Replace the example server below with your address.\n\n## Authentication\nMost endpoints require an AiHummer API key (`ah-…`) sent as a bearer token:\n\n```\nAuthorization: Bearer ah-xxxxxxxxxxxxxxxx\n```\n\nKeys are issued from the admin UI or `POST /v1/admin/apikeys`. An end-user key may call `/v1/chat/completions`; control-plane access requires a key with `admin:read` / `admin:write` (or `*`) scopes, or a logged-in admin session cookie (`POST /v1/admin/auth/login`).\nSome endpoints use a different credential: inbound channel webhooks use the shared inbound secret (`X-AIHummer-Inbound-Secret`), SCIM endpoints use the tenant SCIM bearer token, and SAML endpoints are unauthenticated SSO callbacks.\n\n## Errors\nErrors return a JSON body of the form `{\"error\":{\"message\":\"…\",\"type\":\"…\",\"code\":\"…\"}}` with the matching HTTP status (`400` invalid request, `401` unauthenticated, `403` forbidden, `404` not found, `429` rate-limited, `501` feature disabled).\n\n## Streaming\nSet `stream:true` on `/v1/chat/completions` to receive Server-Sent Events (`text/event-stream`). Event feeds (`/v1/events/stream`, `/v1/web/stream`) are also SSE and resumable via a cursor.\n\n## Idempotency & rate limits\nSide-effecting operations are idempotent on the server (a resume-stable ledger key prevents duplicate effects across retries). Per-key request rate limits can be set when issuing an API key (`rate_limit_rpm`); exceeding them returns `429`." }, "servers": [ { "url": "https://your-instance.example.com", "description": "Your AiHummer instance" }, { "url": "/" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Chat (OpenAI-compatible)" }, { "name": "Inbound & triggers" }, { "name": "Devices & pairing" }, { "name": "Auth & SSO" }, { "name": "SCIM" }, { "name": "Conversations" }, { "name": "Agents & orchestration" }, { "name": "Knowledge" }, { "name": "Memory" }, { "name": "Analytics" }, { "name": "Modules & plugins" }, { "name": "Security & governance" }, { "name": "Artifacts" }, { "name": "Voice & video" }, { "name": "Media & files" }, { "name": "MCP & A2A" }, { "name": "System" }, { "name": "Admin" } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "AiHummer API key (`ah-…`) sent as `Authorization: Bearer `." } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope returned on any non-2xx status.", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message." }, "type": { "type": "string", "description": "Error category, e.g. invalid_request_error, permission_error, rate_limit_error." }, "code": { "type": [ "string", "null" ], "description": "Short machine-readable code." } }, "required": [ "message" ] } }, "required": [ "error" ], "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } }, "Message": { "type": "object", "description": "A single chat message.", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "description": "Author role." }, "content": { "type": "string", "description": "Message text." }, "name": { "type": "string", "description": "Optional author name." } }, "example": { "role": "user", "content": "Summarise our refund policy in two sentences." } }, "Usage": { "type": "object", "description": "Token accounting for a completion.", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "example": { "prompt_tokens": 24, "completion_tokens": 27, "total_tokens": 51 } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model or agent name configured on your instance.", "example": "default" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Conversation so far, oldest first." }, "stream": { "type": "boolean", "default": false, "description": "Stream the answer as Server-Sent Events." }, "temperature": { "type": "number", "default": 1, "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "default": 1, "minimum": 0, "maximum": 1 }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate." } }, "example": { "model": "default", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Summarise our refund policy in two sentences." } ], "temperature": 0.3 } }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/Message" }, "finish_reason": { "type": "string", "example": "stop" } } } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "example": { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1750000000, "model": "default", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Refunds are issued within 14 days of purchase. Contact support with your order number to start one." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 24, "completion_tokens": 27, "total_tokens": 51 } } }, "InboundEnvelope": { "type": "object", "description": "A normalized inbound message from a channel or custom app.", "required": [ "channel", "external_id", "text" ], "properties": { "channel": { "type": "string", "description": "Channel identifier, e.g. \"generic\", \"telegram\", \"email\".", "example": "generic" }, "external_id": { "type": "string", "description": "Stable per-sender id used to thread the conversation.", "example": "user-42" }, "text": { "type": "string", "description": "Message text to deliver to the agent.", "example": "What is the status of order 1001?" } }, "example": { "channel": "generic", "external_id": "user-42", "text": "What is the status of order 1001?" } }, "PairingRedeem": { "type": "object", "description": "Redeem a one-time pairing code (shown as a QR) to provision a device.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The one-time pairing code from the QR / admin UI.", "example": "PAIR-7F3A-21BC" }, "device_name": { "type": "string", "description": "Human-readable device label.", "example": "Anna’s iPhone" }, "platform": { "type": "string", "description": "Device platform.", "example": "ios" }, "push_token": { "type": "string", "description": "Optional push-notification token." } }, "example": { "code": "PAIR-7F3A-21BC", "device_name": "Anna’s iPhone", "platform": "ios" } }, "ScimUser": { "type": "object", "description": "SCIM 2.0 core User resource (RFC 7643).", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }, "id": { "type": "string", "description": "Server-assigned unique id." }, "userName": { "type": "string", "description": "Login; mapped to the local account login." }, "active": { "type": "boolean" }, "name": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "primary": { "type": "boolean" } } } }, "meta": { "type": "object", "properties": { "resourceType": { "type": "string", "example": "User" } } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "a1b2c3d4", "userName": "jdoe@acme.com", "active": true, "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [ { "value": "jdoe@acme.com", "primary": true } ], "meta": { "resourceType": "User" } } }, "ScimListResponse": { "type": "object", "description": "SCIM 2.0 ListResponse envelope.", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "totalResults": { "type": "integer" }, "startIndex": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimUser" } } }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 20, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "a1b2c3d4", "userName": "jdoe@acme.com", "active": true } ] } }, "Conversation": { "type": "object", "description": "A conversation (thread). Field set is representative; your instance returns JSON.", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workspace_id": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "example": { "id": "conv_01H...", "title": "Refund question", "workspace_id": "ws_01H...", "project_id": null, "folder": "Support", "tags": [ "billing" ], "created_at": "2026-01-01T10:00:00Z", "updated_at": "2026-01-01T10:05:00Z" } }, "Paginated": { "type": "object", "description": "Generic list envelope. Some endpoints instead return a bare JSON array or a named array field.", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when no more." }, "total": { "type": "integer" } }, "example": { "items": [], "next_cursor": null, "total": 0 } } } }, "paths": { "/v1/admin/overview": { "get": { "tags": [ "Admin" ], "summary": "Tenant overview (counts, health).", "operationId": "get_v1_admin_overview", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Usage analytics over a window.", "operationId": "get_v1_admin_analytics", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/channels": { "get": { "tags": [ "Admin" ], "summary": "List connected channels.", "operationId": "get_v1_admin_channels", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations.", "operationId": "get_v1_admin_conversations", "responses": { "200": { "description": "A list of conversations.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "conversations": [ { "id": "conv_01H...", "title": "Refund question", "folder": "Support", "tags": [ "billing" ], "updated_at": "2026-01-01T10:05:00Z" } ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/conversations/messages": { "get": { "tags": [ "Conversations" ], "summary": "Messages of a conversation (?id=).", "operationId": "get_v1_admin_conversations_messages", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } } ] } }, "/v1/admin/conversations/export": { "get": { "tags": [ "Conversations" ], "summary": "Download a conversation (?conversation_id=&format=md|json).", "operationId": "get_v1_admin_conversations_export", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "conversation_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "md", "json" ] } } ] } }, "/v1/admin/conversations/turns": { "get": { "tags": [ "Conversations" ], "summary": "Recent turns of a conversation (status/model/tokens/duration).", "operationId": "get_v1_admin_conversations_turns", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/conversations/organize": { "post": { "tags": [ "Conversations" ], "summary": "Set a conversation folder + tags.", "operationId": "post_v1_admin_conversations_organize", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "folder": { "type": "string" }, "tags": { "type": "array", "items": {} } } }, "example": { "conversation_id": "...", "folder": "...", "tags": [] } } } } } }, "/v1/admin/conversations/feedback": { "post": { "tags": [ "Conversations" ], "summary": "Thumbs up/down on an assistant message.", "operationId": "post_v1_admin_conversations_feedback", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "rating": { "type": "integer" }, "comment": { "type": "string" } } }, "example": { "message_id": "...", "rating": 1, "comment": "" } } } } } }, "/v1/admin/conversations/post": { "post": { "tags": [ "Conversations" ], "summary": "Post a message / drive a turn.", "operationId": "post_v1_admin_conversations_post", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "text": { "type": "string" } } }, "example": { "conversation_id": "...", "text": "..." } } } } } }, "/v1/admin/conversations/reset": { "post": { "tags": [ "Conversations" ], "summary": "Reset a conversation's working context (keep history).", "operationId": "post_v1_admin_conversations_reset", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" } } }, "example": { "conversation_id": "..." } } } } } }, "/v1/admin/conversations/fork": { "post": { "tags": [ "Conversations" ], "summary": "Branch a conversation into a new one (optionally up to a message).", "operationId": "post_v1_admin_conversations_fork", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "until_message_id": { "type": "string" }, "title": { "type": "string" } } }, "example": { "conversation_id": "...", "until_message_id": "", "title": "" } } } } } }, "/v1/admin/conversations/regenerate": { "post": { "tags": [ "Conversations" ], "summary": "Re-run the last user prompt for a fresh answer (supersedes the previous assistant reply).", "operationId": "post_v1_admin_conversations_regenerate", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" } } }, "example": { "conversation_id": "..." } } } } } }, "/v1/admin/conversations/branch": { "post": { "tags": [ "Conversations" ], "summary": "Edit→branch: fork a conversation at a message and post an edited user prompt into the fork (original untouched).", "operationId": "post_v1_admin_conversations_branch", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "message_id": { "type": "string" }, "edited_text": { "type": "string" }, "title": { "type": "string" } } }, "example": { "conversation_id": "...", "message_id": "...", "edited_text": "...", "title": "" } } } } } }, "/v1/admin/batches": { "post": { "tags": [ "Conversations" ], "summary": "Submit an async batch of prompts for background processing (Batch API, #70); returns a batch id.", "operationId": "post_v1_admin_batches", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "prompts": { "type": "array", "items": { "type": "string" } } } }, "example": { "conversation_id": "", "prompts": [ "...", "..." ] } } } } } }, "/v1/admin/batches/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Get a batch's status + per-item results.", "operationId": "get_v1_admin_batches_id", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/workspaces/members": { "get": { "tags": [ "Admin" ], "summary": "List a workspace's team members (?workspace_id=).", "operationId": "get_v1_admin_workspaces_members", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Admin" ], "summary": "Add/upsert a workspace team member with a role (owner|admin|member).", "operationId": "post_v1_admin_workspaces_members", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "user_id": { "type": "string" }, "role": { "type": "string" } } }, "example": { "workspace_id": "...", "user_id": "...", "role": "member" } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Remove a workspace team member.", "operationId": "delete_v1_admin_workspaces_members", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "user_id": { "type": "string" } } }, "example": { "workspace_id": "...", "user_id": "..." } } } } } }, "/v1/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List tenant users + roles.", "operationId": "get_v1_admin_users", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/users/role": { "post": { "tags": [ "Admin" ], "summary": "Grant a role.", "operationId": "post_v1_admin_users_role", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "role": { "type": "string" } } }, "example": { "subject_id": "...", "role": "admin|owner" } } } } } }, "/v1/admin/users/role/revoke": { "post": { "tags": [ "Admin" ], "summary": "Revoke a role (last-owner + self guarded).", "operationId": "post_v1_admin_users_role_revoke", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "role": { "type": "string" } } }, "example": { "subject_id": "...", "role": "owner" } } } } } }, "/v1/admin/auth/login": { "post": { "tags": [ "Auth & SSO" ], "summary": "Log in with a local account; sets a session cookie.", "operationId": "post_v1_admin_auth_login", "responses": { "200": { "description": "Logged in; a session cookie is set.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "tenant_id": "ten_01H...", "roles": [ "owner" ] } } } }, "401": { "description": "Invalid login or password.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid credentials.", "type": "invalid_request_error", "code": "invalid_credentials" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "login", "password" ], "properties": { "login": { "type": "string" }, "password": { "type": "string", "format": "password" } } }, "example": { "login": "admin", "password": "s3cret" } } } } } }, "/v1/admin/auth/logout": { "post": { "tags": [ "Auth & SSO" ], "summary": "Revoke the current session.", "operationId": "post_v1_admin_auth_logout", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } } }, "/v1/admin/auth/me": { "get": { "tags": [ "Auth & SSO" ], "summary": "Current session identity (login, tenant, roles); 401 if none.", "operationId": "get_v1_admin_auth_me", "responses": { "200": { "description": "Current session identity.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "login": "admin", "tenant_id": "ten_01H...", "roles": [ "owner" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/auth/password": { "post": { "tags": [ "Auth & SSO" ], "summary": "Change your own password.", "operationId": "post_v1_admin_auth_password", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "string" }, "new": { "type": "string" } } }, "example": { "current": "...", "new": "..." } } } } } }, "/v1/admin/auth/reset/request": { "post": { "tags": [ "Auth & SSO" ], "summary": "Request a password-reset email (login or email).", "operationId": "post_v1_admin_auth_reset_request", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string" } } }, "example": { "identifier": "..." } } } } } }, "/v1/admin/auth/reset/confirm": { "post": { "tags": [ "Auth & SSO" ], "summary": "Complete a password reset with the emailed token.", "operationId": "post_v1_admin_auth_reset_confirm", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string" } } }, "example": { "token": "...", "password": "..." } } } } } }, "/v1/admin/local-users": { "get": { "tags": [ "Auth & SSO" ], "summary": "List local accounts (login, name, email, roles).", "operationId": "get_v1_admin_local_users", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Auth & SSO" ], "summary": "Create a local account (login+password required).", "operationId": "post_v1_admin_local_users", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string" }, "password": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string" }, "photo_url": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "example": { "login": "...", "password": "...", "full_name": "", "email": "", "photo_url": "", "roles": [ "admin" ] } } } } } }, "/v1/admin/local-users/update": { "post": { "tags": [ "Auth & SSO" ], "summary": "Update profile fields of a local account.", "operationId": "post_v1_admin_local_users_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string" }, "photo_url": { "type": "string" }, "status": { "type": "string" } } }, "example": { "id": "...", "full_name": "", "email": "", "photo_url": "", "status": "active" } } } } } }, "/v1/admin/local-users/delete": { "post": { "tags": [ "Auth & SSO" ], "summary": "Delete a local account (self-delete guarded).", "operationId": "post_v1_admin_local_users_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/local-users/password": { "post": { "tags": [ "Auth & SSO" ], "summary": "Reset another account's password.", "operationId": "post_v1_admin_local_users_password", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "password": { "type": "string" } } }, "example": { "id": "...", "password": "..." } } } } } }, "/v1/admin/audit": { "get": { "tags": [ "Admin" ], "summary": "Audit log: who/when/what (?limit=).", "operationId": "get_v1_admin_audit", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } } ] } }, "/v1/admin/budget": { "get": { "tags": [ "Analytics" ], "summary": "Read the tenant's spend/rate limits.", "operationId": "get_v1_admin_budget", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Analytics" ], "summary": "Set spend/rate limits (0=unlimited per field).", "operationId": "post_v1_admin_budget", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "daily_token_limit": { "type": "integer" }, "monthly_token_limit": { "type": "integer" }, "daily_cost_limit_usd": { "type": "integer" }, "monthly_cost_limit_usd": { "type": "integer" }, "rpm_limit": { "type": "integer" }, "per_conversation_token_limit": { "type": "integer" } } }, "example": { "daily_token_limit": 0, "monthly_token_limit": 0, "daily_cost_limit_usd": 0, "monthly_cost_limit_usd": 0, "rpm_limit": 0, "per_conversation_token_limit": 0 } } } } } }, "/v1/admin/usage": { "get": { "tags": [ "Analytics" ], "summary": "Token/cost consumption for the current day + month.", "operationId": "get_v1_admin_usage", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/usage/chargeback": { "get": { "tags": [ "Analytics" ], "summary": "Spend attributed per agent/cost-center (?window=day|month).", "operationId": "get_v1_admin_usage_chargeback", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "day", "month" ] } } ] } }, "/v1/admin/analytics/dashboard": { "get": { "tags": [ "Analytics" ], "summary": "Dashboard-ready aggregates (deterministic SQL): per-day token/cost/turn series, turn volume + avg latency, thumbs up/down ratio, top agents by spend (?window=24h|7d|30d|90d).", "operationId": "get_v1_admin_analytics_dashboard", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ] } } ] } }, "/v1/admin/analytics/quality": { "get": { "tags": [ "Analytics" ], "summary": "Deterministic per-agent + overall answer-quality score combining thumbs up/down feedback ratio (#65) and turn success rate; quality = 0.5*feedback_score + 0.5*success_rate (?window=24h|7d|30d|90d).", "operationId": "get_v1_admin_analytics_quality", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ] } } ] } }, "/v1/admin/analytics/anomalies": { "get": { "tags": [ "Analytics" ], "summary": "Spend/usage anomaly detection: flags days whose daily cost exceeds the tenant's own baseline mean + k*stddev (deterministic stats, ?window=24h|7d|30d|90d&k=2.5).", "operationId": "get_v1_admin_analytics_anomalies", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ] } }, { "name": "k", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "number", "example": 2.5 } } ] } }, "/v1/admin/analytics/sentiment": { "get": { "tags": [ "Analytics" ], "summary": "Stored per-conversation topics/sentiment/CSAT analytics (#81): sentiment label + signed score [-1,1], short topic labels, a 1..5 CSAT proxy and a one-line summary (?conversation_id=…). 404 until analyzed.", "operationId": "get_v1_admin_analytics_sentiment", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "conversation_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Analytics" ], "summary": "Analyze one conversation (#81): derives sentiment/topics/CSAT from the dialog using the configured model and upserts. Idempotent — skips the model when the message watermark is unchanged unless force=true.", "operationId": "post_v1_admin_analytics_sentiment", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "force": { "type": "boolean" } } }, "example": { "conversation_id": "…", "force": false } } } } } }, "/v1/admin/analytics/sentiment/rollup": { "get": { "tags": [ "Analytics" ], "summary": "Tenant-wide rollup over stored conversation analytics (#81, deterministic): conversation count, mean sentiment, mean CSAT, negative/neutral/positive distribution and top topics (?window=24h|7d|30d|90d).", "operationId": "get_v1_admin_analytics_sentiment_rollup", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ] } } ] } }, "/v1/admin/analytics/export": { "get": { "tags": [ "Analytics" ], "summary": "DWH export: streams the raw usage ledger for the window as an attachment (?window=24h|7d|30d|90d&format=csv|json).", "operationId": "get_v1_admin_analytics_export", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ] } }, { "name": "format", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "csv", "json" ] } } ] } }, "/v1/admin/branding": { "get": { "tags": [ "Admin" ], "summary": "Read the instance branding (logo/name/push photo) the app shows after pairing.", "operationId": "get_v1_admin_branding", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Admin" ], "summary": "Set the instance branding.", "operationId": "post_v1_admin_branding", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "logo_url": { "type": "string" }, "push_photo_url": { "type": "string" } } }, "example": { "name": "Acme Assistant", "logo_url": "https://...", "push_photo_url": "https://..." } } } } } }, "/v1/admin/instructions": { "get": { "tags": [ "Admin" ], "summary": "Read the tenant-wide custom instructions (prepended to every agent).", "operationId": "get_v1_admin_instructions", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Admin" ], "summary": "Set the tenant-wide custom instructions.", "operationId": "post_v1_admin_instructions", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_instructions": { "type": "string" } } }, "example": { "custom_instructions": "..." } } } } } }, "/v1/admin/playground": { "post": { "tags": [ "Admin" ], "summary": "Run a one-shot prompt on a model (test prompts/params).", "operationId": "post_v1_admin_playground", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "system": { "type": "string" }, "prompt": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number" } } }, "example": { "system": "...", "prompt": "...", "model": "...", "temperature": 0.2 } } } } } }, "/v1/admin/knowledge": { "get": { "tags": [ "Knowledge" ], "summary": "List ingested knowledge-base documents.", "operationId": "get_v1_admin_knowledge", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/knowledge/ingest": { "post": { "tags": [ "Knowledge" ], "summary": "Ingest a document into the knowledge base.", "operationId": "post_v1_admin_knowledge_ingest", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "source": { "type": "string" }, "text": { "type": "string" } } }, "example": { "title": "...", "source": "...", "text": "..." } } } } } }, "/v1/admin/knowledge/ingest-url": { "post": { "tags": [ "Knowledge" ], "summary": "Fetch a URL and ingest its text (PDFs auto-detected and parsed).", "operationId": "post_v1_admin_knowledge_ingest_url", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } }, "example": { "url": "https://..." } } } } } }, "/v1/admin/knowledge/ingest-pdf": { "post": { "tags": [ "Knowledge" ], "summary": "Extract text from an uploaded PDF (base64) and ingest it.", "operationId": "post_v1_admin_knowledge_ingest_pdf", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "pdf_base64": { "type": "string" } } }, "example": { "title": "...", "pdf_base64": "..." } } } } } }, "/v1/admin/knowledge/connectors/drive/config": { "get": { "tags": [ "Knowledge" ], "summary": "Report whether the Google Drive connector is configured (never returns credentials).", "operationId": "get_v1_admin_knowledge_connectors_drive_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Knowledge" ], "summary": "Store the Google Drive service-account credentials (kept in the Secrets vault).", "operationId": "post_v1_admin_knowledge_connectors_drive_config", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials_json": { "type": "string" }, "folder_id": { "type": "string" }, "subject": { "type": "string" } } }, "example": { "credentials_json": "{...}", "folder_id": "...", "subject": "..." } } } } } }, "/v1/admin/knowledge/connectors/drive/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Sync Google Drive: list files and ingest each supported one into the knowledge base.", "operationId": "post_v1_admin_knowledge_connectors_drive_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" } } }, "example": { "workspace_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/msgraph/config": { "get": { "tags": [ "Knowledge" ], "summary": "Report whether the Microsoft Graph (SharePoint/OneDrive) connector is configured (never returns client_secret).", "operationId": "get_v1_admin_knowledge_connectors_msgraph_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Knowledge" ], "summary": "Store the Microsoft Graph app credentials (kept in the Secrets vault).", "operationId": "post_v1_admin_knowledge_connectors_msgraph_config", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "drive_id": { "type": "string" }, "site_id": { "type": "string" } } }, "example": { "tenant_id": "...", "client_id": "...", "client_secret": "...", "drive_id": "...", "site_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/msgraph/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Sync Microsoft Graph (SharePoint/OneDrive): list drive files and ingest each supported one.", "operationId": "post_v1_admin_knowledge_connectors_msgraph_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" } } }, "example": { "workspace_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/s3/config": { "get": { "tags": [ "Knowledge" ], "summary": "Report whether the S3/GCS object-store connector is configured (never returns access keys).", "operationId": "get_v1_admin_knowledge_connectors_s3_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Knowledge" ], "summary": "Store the S3-compatible (AWS S3 / GCS / MinIO) connector config + keys (kept in the Secrets vault).", "operationId": "post_v1_admin_knowledge_connectors_s3_config", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "region": { "type": "string" }, "bucket": { "type": "string" }, "prefix": { "type": "string" }, "access_key_id": { "type": "string" }, "secret_access_key": { "type": "string" }, "path_style": { "type": "boolean" } } }, "example": { "endpoint": "...", "region": "us-east-1", "bucket": "...", "prefix": "...", "access_key_id": "...", "secret_access_key": "...", "path_style": false } } } } } }, "/v1/admin/knowledge/connectors/s3/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Sync an S3/GCS bucket: list objects under the prefix and ingest each supported one (docx/xlsx/pdf/text).", "operationId": "post_v1_admin_knowledge_connectors_s3_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" } } }, "example": { "workspace_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/db/config": { "get": { "tags": [ "Knowledge" ], "summary": "Report whether the SQL database connector is configured (never returns the DSN).", "operationId": "get_v1_admin_knowledge_connectors_db_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Knowledge" ], "summary": "Store the SQL connector config + DSN (kept in the Secrets vault). driver=postgres (mysql deferred); query must be read-only.", "operationId": "post_v1_admin_knowledge_connectors_db_config", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driver": { "type": "string" }, "dsn": { "type": "string" }, "query": { "type": "string" }, "id_column": { "type": "string" } } }, "example": { "driver": "postgres", "dsn": "postgres://...", "query": "SELECT id, body FROM faqs ORDER BY id", "id_column": "id" } } } } } }, "/v1/admin/knowledge/connectors/db/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Sync a SQL query: run the read-only query and ingest each row as a document.", "operationId": "post_v1_admin_knowledge_connectors_db_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" } } }, "example": { "workspace_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/confluence/config": { "get": { "tags": [ "Knowledge" ], "summary": "Report whether the Confluence connector is configured (never returns the api_token).", "operationId": "get_v1_admin_knowledge_connectors_confluence_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Knowledge" ], "summary": "Store the Confluence Cloud connector config + API token (kept in the Secrets vault).", "operationId": "post_v1_admin_knowledge_connectors_confluence_config", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_url": { "type": "string" }, "email": { "type": "string" }, "api_token": { "type": "string" }, "space_key": { "type": "string" } } }, "example": { "base_url": "https://org.atlassian.net", "email": "...", "api_token": "...", "space_key": "..." } } } } } }, "/v1/admin/knowledge/connectors/confluence/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Sync Confluence: list pages and ingest each one's storage body as text.", "operationId": "post_v1_admin_knowledge_connectors_confluence_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" } } }, "example": { "workspace_id": "..." } } } } } }, "/v1/admin/knowledge/connectors/slack_export/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Ingest a Slack workspace export ZIP (base64): one document per channel from its message files.", "operationId": "post_v1_admin_knowledge_connectors_slack_export_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "zip_base64": { "type": "string" } } }, "example": { "workspace_id": "...", "zip_base64": "..." } } } } } }, "/v1/admin/license": { "get": { "tags": [ "Admin" ], "summary": "Commercial license status (state, licensee, expiry).", "operationId": "get_v1_admin_license", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Admin" ], "summary": "Install a signed license token.", "operationId": "post_v1_admin_license", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } }, "example": { "token": "." } } } } } }, "/v1/admin/schedules": { "get": { "tags": [ "Admin" ], "summary": "List scheduled jobs.", "operationId": "get_v1_admin_schedules", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/schedules/pause": { "post": { "tags": [ "Admin" ], "summary": "Pause a schedule.", "operationId": "post_v1_admin_schedules_pause", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/schedules/resume": { "post": { "tags": [ "Admin" ], "summary": "Resume a schedule.", "operationId": "post_v1_admin_schedules_resume", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/memory/review": { "get": { "tags": [ "Memory" ], "summary": "Memory candidates awaiting review.", "operationId": "get_v1_admin_memory_review", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/memory/review/promote": { "post": { "tags": [ "Memory" ], "summary": "Promote a memory candidate.", "operationId": "post_v1_admin_memory_review_promote", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/memory/review/reject": { "post": { "tags": [ "Memory" ], "summary": "Reject a memory candidate.", "operationId": "post_v1_admin_memory_review_reject", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/memory/facts": { "get": { "tags": [ "Memory" ], "summary": "List a user's personal cross-conversation facts (?user_id=, default self).", "operationId": "get_v1_admin_memory_facts", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Memory" ], "summary": "Add a personal fact for a user (stored reviewed).", "operationId": "post_v1_admin_memory_facts", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "text": { "type": "string" } } }, "example": { "user_id": "", "text": "..." } } } } } }, "/v1/admin/memory/facts/forget": { "post": { "tags": [ "Memory" ], "summary": "Delete one of the user's personal facts.", "operationId": "post_v1_admin_memory_facts_forget", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/apikeys": { "get": { "tags": [ "Admin" ], "summary": "List personal end-user API keys (metadata only).", "operationId": "get_v1_admin_apikeys", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Admin" ], "summary": "Issue an API key (plaintext returned once). Optional scopes grant control-plane access: chat, admin:read, admin:write, '*' (or 'area:*'). Empty scopes = end-user chat key. rate_limit_rpm (0=unlimited) throttles the key (§5.2).", "operationId": "post_v1_admin_apikeys", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "user_ref": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit_rpm": { "type": "integer" } } }, "example": { "workspace_id": "", "user_ref": "...", "name": "", "scopes": [ "admin:read" ], "rate_limit_rpm": 60 } } } } } }, "/v1/admin/apikeys/revoke": { "post": { "tags": [ "Admin" ], "summary": "Revoke a personal API key.", "operationId": "post_v1_admin_apikeys_revoke", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/apikeys/register-client": { "post": { "tags": [ "Admin" ], "summary": "Register a key as an OAuth2 service-account client (§5.2). Returns client_id + client_secret once; use them at POST /v1/oauth/token (client_credentials).", "operationId": "post_v1_admin_apikeys_register_client", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/models/access": { "get": { "tags": [ "Admin" ], "summary": "List the tenant's allowed models (empty=all allowed).", "operationId": "get_v1_admin_models_access", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Admin" ], "summary": "Set the tenant's allowed-models list (empty clears it).", "operationId": "post_v1_admin_models_access", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_models": { "type": "array", "items": { "type": "string" } } } }, "example": { "allowed_models": [ "gpt-5.5", "claude-opus-4-8" ] } } } } } }, "/v1/admin/byok": { "get": { "tags": [ "Admin" ], "summary": "Report whether a tenant BYOK LLM provider key is set (never returns the key).", "operationId": "get_v1_admin_byok", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Admin" ], "summary": "Set the tenant's own LLM provider key, or clear it (clear=true / empty api_key).", "operationId": "post_v1_admin_byok", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "api_key": { "type": "string" }, "base_url": { "type": "string" }, "model": { "type": "string" } } }, "example": { "provider": "groq", "api_key": "...", "base_url": "https://...", "model": "..." } } } } } }, "/v1/admin/webhooks": { "get": { "tags": [ "Admin" ], "summary": "List the tenant's outbound webhooks (never returns the secret).", "operationId": "get_v1_admin_webhooks", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Admin" ], "summary": "Register an outbound webhook that fires on events (e.g. turn.completed); payloads are HMAC-SHA256 signed.", "operationId": "post_v1_admin_webhooks", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string" }, "allow_internal": { "type": "boolean" } } }, "example": { "url": "https://hooks.example.com/x", "events": [ "turn.completed" ], "secret": "...", "allow_internal": false } } } } } }, "/v1/admin/webhooks/delete": { "post": { "tags": [ "Admin" ], "summary": "Delete an outbound webhook by id.", "operationId": "post_v1_admin_webhooks_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/credentials": { "get": { "tags": [ "Security & governance" ], "summary": "List the caller's own + shared credential vault entries (personal-plugins foundation). Metadata only: plugin_slug, format, label, sharing, expiry — NEVER the secret.", "operationId": "get_v1_admin_credentials", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Security & governance" ], "summary": "Store (encrypted) a credential for a personal plugin. Owner defaults to the authenticated user; set shared=true (admin) to store a workspace-shared credential. Secret is write-only. Formats: oauth2|api_key|basic|app_password|json|cert. The resolver hands the acting user's credential to that plugin's tools at turn time.", "operationId": "post_v1_admin_credentials", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_slug": { "type": "string" }, "format": { "type": "string" }, "secret": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expiry": { "type": "string" } } }, "label": { "type": "string" }, "sharing": { "type": "string" }, "mode": { "type": "string" } } }, "example": { "plugin_slug": "google", "format": "oauth2", "secret": { "access_token": "...", "refresh_token": "...", "expiry": "2026-01-01T00:00:00Z" }, "label": "personal", "sharing": "private", "mode": "autonomous" } } } } } }, "/v1/admin/credentials/delete": { "post": { "tags": [ "Security & governance" ], "summary": "Revoke (delete) a credential the caller owns.", "operationId": "post_v1_admin_credentials_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_slug": { "type": "string" }, "label": { "type": "string" } } }, "example": { "plugin_slug": "google", "label": "personal" } } } } } }, "/v1/admin/credentials/share": { "post": { "tags": [ "Security & governance" ], "summary": "Set a credential's sharing: private|workspace, plus explicit shared_user_ids / shared_agent_ids grants.", "operationId": "post_v1_admin_credentials_share", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_slug": { "type": "string" }, "label": { "type": "string" }, "sharing": { "type": "string" }, "shared_user_ids": { "type": "array", "items": {} }, "shared_agent_ids": { "type": "array", "items": {} } } }, "example": { "plugin_slug": "google", "label": "personal", "sharing": "workspace", "shared_user_ids": [], "shared_agent_ids": [] } } } } } }, "/v1/integrations/trigger": { "post": { "tags": [ "Inbound & triggers" ], "summary": "Native Zapier/Make inbound trigger (#90): a no-code platform POSTs a generic JSON event here. Auth is a shared inbound secret — sign the body as sha256 HMAC in X-AIHummer-Signature, or send it as Authorization: Bearer (NOT the admin session). The verified event is journaled to its workspace and its text relayed to the configured Teams/Discord channels. Disabled (501) until AIHUMMER_INBOUND_TRIGGER_SECRET is set. Outbound events to Zapier/Make use the standard outbound webhooks above (register the platform's Catch-Hook URL).", "operationId": "post_v1_integrations_trigger", "responses": { "200": { "description": "Event accepted, journaled and relayed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "accepted": true, "conversation_id": "conv_01H..." } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "501": { "description": "Inbound triggers are disabled until the inbound-trigger secret is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Inbound trigger not configured.", "type": "invalid_request_error", "code": "not_configured" } } } } } }, "description": "Native Zapier/Make inbound trigger. A no-code platform POSTs a generic JSON event here. Authenticate with the shared inbound-trigger secret: either sign the raw body as an HMAC-SHA256 hex digest in `X-AIHummer-Signature`, or send it as `Authorization: Bearer ` (this is NOT an admin session). The verified event is journaled to its workspace and its text relayed to the configured Teams/Discord channels. Returns `501` until the inbound-trigger secret is configured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "workspace": { "type": "string" }, "conversation": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "string" }, "data": { "type": "object", "properties": {} } } }, "example": { "event": "crm.deal.created", "workspace": "ws_01H...", "text": "New deal: Acme $5k", "source": "zapier", "data": { "amount": 5000 } } } } } } }, "/v1/admin/scim/token": { "get": { "tags": [ "SCIM" ], "summary": "SCIM 2.0 provisioning token status (configured?, role, timestamps). #74 SSO.", "operationId": "get_v1_admin_scim_token", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "SCIM" ], "summary": "Issue/rotate the tenant SCIM bearer token (shown once); role is granted to provisioned users.", "operationId": "post_v1_admin_scim_token", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" } } }, "example": { "role": "member" } } } } }, "delete": { "tags": [ "SCIM" ], "summary": "Revoke the tenant SCIM token (disables IdP provisioning).", "operationId": "delete_v1_admin_scim_token", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/scim/v2/Users": { "post": { "tags": [ "SCIM" ], "summary": "SCIM 2.0: provision a user (IdP-facing; auth=tenant SCIM bearer token, not OIDC). Maps userName→login, grants the token's role.", "operationId": "post_scim_v2_Users", "responses": { "201": { "description": "User provisioned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "409": { "description": "A user with this userName already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "userName already exists.", "type": "invalid_request_error", "code": "uniqueness" } } } } } }, "description": "SCIM 2.0: provision (create) a user. IdP-facing — authenticate with the tenant SCIM bearer token, not an admin session. `userName` maps to the local login and the token’s role is granted.", "requestBody": { "required": true, "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "jdoe@acme.com", "active": true, "emails": [ { "value": "jdoe@acme.com", "primary": true } ] } } } } }, "get": { "tags": [ "SCIM" ], "summary": "SCIM 2.0: list users, optional filter ?filter=userName eq \"x\" (IdP-facing; SCIM bearer token).", "operationId": "get_scim_v2_Users", "responses": { "200": { "description": "Matching users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "SCIM 2.0: list provisioned users with optional filtering. IdP-facing — authenticate with the tenant SCIM bearer token.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SCIM filter, e.g. `userName eq \"jdoe@acme.com\"`." }, { "name": "startIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based index of the first result." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Maximum number of results to return." } ] } }, "/scim/v2/Users/{id}": { "get": { "tags": [ "SCIM" ], "summary": "SCIM 2.0: get a provisioned user by id (SCIM bearer token).", "operationId": "get_scim_v2_Users_id", "responses": { "200": { "description": "The user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Not found.", "type": "invalid_request_error", "code": "not_found" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "SCIM 2.0: fetch a provisioned user by id. IdP-facing — authenticate with the tenant SCIM bearer token." }, "patch": { "tags": [ "SCIM" ], "summary": "SCIM 2.0: PatchOp to activate/deactivate (active:true|false). DELETE deprovisions (deactivate).", "operationId": "patch_scim_v2_Users_id", "responses": { "200": { "description": "Updated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Not found.", "type": "invalid_request_error", "code": "not_found" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "SCIM 2.0: apply a PatchOp to activate/deactivate a user (`active:true|false`). Deactivating deprovisions access. IdP-facing — authenticate with the tenant SCIM bearer token.", "requestBody": { "required": true, "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "replace", "value": { "active": false } } ] } } } } } }, "/saml/metadata": { "get": { "tags": [ "Auth & SSO" ], "summary": "SAML 2.0 SP metadata XML — give this to the IdP. #74 SSO (no auth; only present when SAML enabled).", "operationId": "get_saml_metadata", "responses": { "200": { "description": "SP metadata XML.", "content": { "application/xml": { "schema": { "type": "string" }, "example": "…" } } } }, "description": "SAML 2.0 Service-Provider metadata XML — hand this to your IdP. Present only when SAML is enabled; no auth.", "security": [] } }, "/saml/acs": { "post": { "tags": [ "Auth & SSO" ], "summary": "SAML 2.0 Assertion Consumer Service — the IdP POSTs the signed assertion here (validated against IdP metadata).", "operationId": "post_saml_acs", "responses": { "302": { "description": "Redirect to the admin UI with a session established." }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } } }, "description": "SAML 2.0 Assertion Consumer Service. Your IdP POSTs the signed assertion here; on success an admin session is established. No API-key auth.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "SAMLResponse": { "type": "string" }, "RelayState": { "type": "string" } } } } } } } }, "/saml/login": { "get": { "tags": [ "Auth & SSO" ], "summary": "Start SAML SSO: redirect to the IdP, then establish an admin session from the validated assertion.", "operationId": "get_saml_login", "responses": { "302": { "description": "Redirect to the configured IdP." } }, "description": "Start SAML SSO: redirects the browser to the IdP, then returns establishing an admin session from the validated assertion. No API-key auth.", "security": [] } }, "/v1/admin/security/ip-allowlist": { "get": { "tags": [ "Security & governance" ], "summary": "List the tenant's admin IP allowlist (empty=open).", "operationId": "get_v1_admin_security_ip_allowlist", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Security & governance" ], "summary": "Set the admin IP allowlist (CIDRs or IPs; empty clears it).", "operationId": "post_v1_admin_security_ip_allowlist", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_cidrs": { "type": "array", "items": { "type": "string" } } } }, "example": { "allowed_cidrs": [ "10.0.0.0/8", "203.0.113.7" ] } } } } } }, "/v1/admin/security/guardrails": { "get": { "tags": [ "Security & governance" ], "summary": "List the tenant's custom input guardrail phrases.", "operationId": "get_v1_admin_security_guardrails", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Security & governance" ], "summary": "Set custom guardrail phrases (refused on top of built-in rules).", "operationId": "post_v1_admin_security_guardrails", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "patterns": { "type": "array", "items": { "type": "string" } } } }, "example": { "patterns": [ "secret project zeta" ] } } } } } }, "/v1/admin/secrets": { "put": { "tags": [ "Security & governance" ], "summary": "Store a secret (scope+name+value).", "operationId": "put_v1_admin_secrets", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } } }, "example": { "scope": "llm", "name": "openai", "value": "..." } } } } } }, "/v1/admin/secrets/get": { "post": { "tags": [ "Security & governance" ], "summary": "Read a secret (audited).", "operationId": "post_v1_admin_secrets_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" } } }, "example": { "scope": "...", "name": "..." } } } } } }, "/v1/admin/approvals": { "get": { "tags": [ "Security & governance" ], "summary": "Pending tool approvals.", "operationId": "get_v1_admin_approvals", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/approvals/decide": { "post": { "tags": [ "Security & governance" ], "summary": "Approve/deny a tool call.", "operationId": "post_v1_admin_approvals_decide", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "approve": { "type": "boolean" } } }, "example": { "id": "...", "approve": true } } } } } }, "/v1/admin/changes": { "get": { "tags": [ "Security & governance" ], "summary": "List change requests in the maker-checker workflow (?status=pending|approved|rejected|all; default pending).", "operationId": "get_v1_admin_changes", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "all" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Security & governance" ], "summary": "Propose a sensitive change for a second approver (maker-checker, #78).", "operationId": "post_v1_admin_changes", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "payload": { "type": "object", "properties": {} } } }, "example": { "action": "...", "payload": {} } } } } } }, "/v1/admin/changes/approve": { "post": { "tags": [ "Security & governance" ], "summary": "Approve a pending change (the approver must differ from the proposer).", "operationId": "post_v1_admin_changes_approve", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/changes/reject": { "post": { "tags": [ "Security & governance" ], "summary": "Reject a pending change (the approver must differ from the proposer).", "operationId": "post_v1_admin_changes_reject", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/settings": { "get": { "tags": [ "Admin" ], "summary": "List settings (values; secrets masked).", "operationId": "get_v1_admin_settings", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/settings/set": { "post": { "tags": [ "Admin" ], "summary": "Set a setting (hot-applied when possible).", "operationId": "post_v1_admin_settings_set", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "example": { "key": "AIHUMMER_...", "value": "..." } } } } } }, "/v1/admin/devices": { "get": { "tags": [ "Devices & pairing" ], "summary": "List connected iOS app devices + their status (online, enabled on-device sources, AppMetrica metrics). Returns {configured, devices[]}; configured:false when the device bridge (AIHUMMER_IOS_PROXY_URL) isn't set.", "operationId": "get_v1_admin_devices", "responses": { "200": { "description": "Connected devices and bridge status.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true, "devices": [ { "id": "dev_01H...", "online": true, "platform": "ios" } ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/agents": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List agents.", "operationId": "get_v1_admin_agents", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Create an agent (name, avatar, system prompt, model, tools, generation params).", "operationId": "post_v1_admin_agents", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "system_prompt": { "type": "string" }, "model": { "type": "string" }, "tool_allow": { "type": "array", "items": {} }, "tool_deny": { "type": "array", "items": {} }, "temperature": { "type": "number" }, "top_p": { "type": "integer" }, "max_tokens": { "type": "integer" }, "response_format": { "type": "string" }, "reasoning_effort": { "type": "string" } } }, "example": { "name": "...", "system_prompt": "...", "model": "...", "tool_allow": [], "tool_deny": [], "temperature": 0.2, "top_p": 1, "max_tokens": 1024, "response_format": "json_object", "reasoning_effort": "medium" } } } } } }, "/v1/admin/agents/update": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Update an agent.", "operationId": "post_v1_admin_agents_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": "string" }, "model": { "type": "string" } } }, "example": { "id": "...", "name": "...", "avatar_url": "...", "model": "..." } } } } } }, "/v1/admin/agents/delete": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Delete an agent.", "operationId": "post_v1_admin_agents_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/agents/versions": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List an agent's persona/prompt version history (?agent_id=).", "operationId": "get_v1_admin_agents_versions", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "agent_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/agents/rollback": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Roll an agent's persona back to a saved version.", "operationId": "post_v1_admin_agents_rollback", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version_id": { "type": "string" } } }, "example": { "agent_id": "...", "version_id": "..." } } } } } }, "/v1/admin/agents/clone": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Clone an agent (persona/model/tools) under a new name.", "operationId": "post_v1_admin_agents_clone", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_agent_id": { "type": "string" }, "target_workspace_id": { "type": "string" }, "name": { "type": "string" } } }, "example": { "source_agent_id": "...", "target_workspace_id": "", "name": "" } } } } } }, "/v1/admin/graphs": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List a workspace's declarative orchestration graphs (?workspace_id=).", "operationId": "get_v1_admin_graphs", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Create an orchestration graph (nodes bound to agents + conditional edges).", "operationId": "post_v1_admin_graphs", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "definition": { "type": "object", "properties": { "start": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agent": { "type": "string" }, "prompt": { "type": "string" }, "edges": { "type": "array", "items": {} } } } } } }, "enabled": { "type": "boolean" } } }, "example": { "workspace_id": "", "name": "...", "definition": { "start": "triage", "nodes": [ { "id": "triage", "agent": "Triage", "prompt": "{{input}}", "edges": [ { "when": "contains", "value": "refund", "to": "__end__" } ] } ] }, "enabled": true } } } } } }, "/v1/admin/graphs/{id}": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Update an orchestration graph (definition re-validated).", "operationId": "put_v1_admin_graphs_id", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "definition": { "type": "object", "properties": { "start": { "type": "string" }, "nodes": { "type": "array", "items": {} } } }, "enabled": { "type": "boolean" } } }, "example": { "name": "...", "definition": { "start": "a", "nodes": [] }, "enabled": true } } } } }, "delete": { "tags": [ "Agents & orchestration" ], "summary": "Delete an orchestration graph.", "operationId": "delete_v1_admin_graphs_id", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/v1/admin/graphs/validate": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Statically validate a graph definition without saving.", "operationId": "post_v1_admin_graphs_validate", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": { "type": "object", "properties": { "start": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" } } } } } } } }, "example": { "definition": { "start": "a", "nodes": [ { "id": "a", "prompt": "hi" } ] } } } } } } }, "/v1/admin/graphs/{id}/run": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Execute a stored graph against an input; returns the step trace.", "operationId": "post_v1_admin_graphs_id_run", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string" } } }, "example": { "input": "..." } } } } } }, "/v1/admin/prompts": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List reusable prompt templates.", "operationId": "get_v1_admin_prompts", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Save a reusable prompt template ({{var}} placeholders).", "operationId": "post_v1_admin_prompts", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "template": { "type": "string" }, "description": { "type": "string" } } }, "example": { "name": "...", "template": "Hello {{name}}", "description": "" } } } } } }, "/v1/admin/prompts/delete": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Delete a prompt template by name.", "operationId": "post_v1_admin_prompts_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } }, "example": { "name": "..." } } } } } }, "/v1/admin/prompts/render": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Render a template with variables.", "operationId": "post_v1_admin_prompts_render", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "variables": { "type": "object", "properties": { "name": { "type": "string" } } } } }, "example": { "name": "...", "variables": { "name": "Ann" } } } } } } }, "/v1/admin/projects": { "get": { "tags": [ "Conversations" ], "summary": "List project spaces (?workspace_id=).", "operationId": "get_v1_admin_projects", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Conversations" ], "summary": "Create a project (name + shared instructions).", "operationId": "post_v1_admin_projects", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" } } }, "example": { "workspace_id": "...", "name": "...", "instructions": "" } } } } } }, "/v1/admin/projects/update": { "post": { "tags": [ "Conversations" ], "summary": "Edit a project's name/instructions.", "operationId": "post_v1_admin_projects_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" } } }, "example": { "id": "...", "name": "...", "instructions": "" } } } } } }, "/v1/admin/projects/delete": { "post": { "tags": [ "Conversations" ], "summary": "Delete a project (conversations detached).", "operationId": "post_v1_admin_projects_delete", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/projects/assign": { "post": { "tags": [ "Conversations" ], "summary": "Move a conversation into a project (empty project_id clears).", "operationId": "post_v1_admin_projects_assign", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "project_id": { "type": "string" } } }, "example": { "conversation_id": "...", "project_id": "..." } } } } } }, "/v1/admin/modules/catalog": { "get": { "tags": [ "Modules & plugins" ], "summary": "Marketplace catalog.", "operationId": "get_v1_admin_modules_catalog", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/modules/catalog/sync": { "post": { "tags": [ "Modules & plugins" ], "summary": "Re-sync the catalog.", "operationId": "post_v1_admin_modules_catalog_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } } }, "/v1/admin/modules": { "get": { "tags": [ "Modules & plugins" ], "summary": "Installed modules.", "operationId": "get_v1_admin_modules", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/modules/install": { "post": { "tags": [ "Modules & plugins" ], "summary": "Install a module.", "operationId": "post_v1_admin_modules_install", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "version": { "type": "string" } } }, "example": { "slug": "...", "version": "" } } } } } }, "/v1/admin/modules/configure": { "post": { "tags": [ "Modules & plugins" ], "summary": "Set a module's config.", "operationId": "post_v1_admin_modules_configure", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "config": { "type": "object", "properties": {} } } }, "example": { "id": "...", "config": {} } } } } } }, "/v1/admin/modules/redeploy": { "post": { "tags": [ "Modules & plugins" ], "summary": "Redeploy a module.", "operationId": "post_v1_admin_modules_redeploy", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/modules/update": { "post": { "tags": [ "Modules & plugins" ], "summary": "Update a module to latest.", "operationId": "post_v1_admin_modules_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/modules/auto-update": { "post": { "tags": [ "Modules & plugins" ], "summary": "Set a module's auto-update (off|check|apply).", "operationId": "post_v1_admin_modules_auto_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string" } } }, "example": { "id": "...", "mode": "apply" } } } } } }, "/v1/admin/modules/stop": { "post": { "tags": [ "Modules & plugins" ], "summary": "Stop a module.", "operationId": "post_v1_admin_modules_stop", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/modules/uninstall": { "post": { "tags": [ "Modules & plugins" ], "summary": "Uninstall a module.", "operationId": "post_v1_admin_modules_uninstall", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/system/version": { "get": { "tags": [ "System" ], "summary": "Running version + update availability.", "operationId": "get_v1_admin_system_version", "responses": { "200": { "description": "Running version and update availability.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "version": "v1.0.1", "update_available": false, "channel": "stable" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/system/update": { "post": { "tags": [ "System" ], "summary": "Apply a host update (privileged, detached).", "operationId": "post_v1_admin_system_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" } } }, "example": { "version": "vX.Y.Z" } } } } } }, "/v1/admin/system/logs": { "get": { "tags": [ "System" ], "summary": "Recent gateway logs.", "operationId": "get_v1_admin_system_logs", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/agents/{id}/profile": { "get": { "tags": [ "Agents & orchestration" ], "summary": "Get an agent's full profile (identity + sections).", "operationId": "get_v1_admin_agents_id_profile", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/agents/{id}/profile/identity": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Update an agent's identity fields.", "operationId": "put_v1_admin_agents_id_profile_identity", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" }, "role": { "type": "string" }, "address_user_as": { "type": "string" } } }, "example": { "display_name": "...", "role": "...", "address_user_as": "..." } } } } } }, "/v1/admin/agents/{id}/sections/{kind}": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Upsert one agent profile section (by kind).", "operationId": "put_v1_admin_agents_id_sections_kind", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Section kind." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } } }, "example": { "content": "..." } } } } } }, "/v1/admin/agents/{id}/mail-password": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Set an agent's mailbox password (stored in the secrets vault, write-only).", "operationId": "put_v1_admin_agents_id_mail_password", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } } }, "example": { "password": "..." } } } } } }, "/v1/admin/shared-sections": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List shared profile sections.", "operationId": "get_v1_admin_shared_sections", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Create a shared profile section.", "operationId": "post_v1_admin_shared_sections", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" } } }, "example": { "name": "...", "content": "..." } } } } } }, "/v1/admin/shared-sections/{id}": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Update a shared profile section.", "operationId": "put_v1_admin_shared_sections_id", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" } } }, "example": { "name": "...", "content": "..." } } } } }, "delete": { "tags": [ "Agents & orchestration" ], "summary": "Delete a shared profile section.", "operationId": "delete_v1_admin_shared_sections_id", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/v1/admin/agents/{id}/shared-sections/{sharedId}": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Link a shared section to an agent.", "operationId": "post_v1_admin_agents_id_shared_sections_sharedId", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "sharedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shared section id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } }, "delete": { "tags": [ "Agents & orchestration" ], "summary": "Unlink a shared section from an agent.", "operationId": "delete_v1_admin_agents_id_shared_sections_sharedId", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "sharedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shared section id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/v1/admin/skills": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List shared skills.", "operationId": "get_v1_admin_skills", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Create a shared skill (SKILL.md).", "operationId": "post_v1_admin_skills", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" } } }, "example": { "name": "...", "content": "..." } } } } } }, "/v1/admin/skills/{id}": { "put": { "tags": [ "Agents & orchestration" ], "summary": "Update a shared skill.", "operationId": "put_v1_admin_skills_id", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" } } }, "example": { "name": "...", "content": "..." } } } } }, "delete": { "tags": [ "Agents & orchestration" ], "summary": "Delete a shared skill.", "operationId": "delete_v1_admin_skills_id", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/v1/admin/skills/{id}/optimize": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Optimize a skill's instructions (SkillOpt). Returns a review-gated PROPOSAL ({result, proposal_id}); never auto-applies.", "operationId": "post_v1_admin_skills_id_optimize", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "rubric": { "type": "string" } } } }, "config": { "type": "object", "properties": { "max_iterations": { "type": "integer" } } } } }, "example": { "cases": [ { "input": "...", "rubric": "..." } ], "config": { "max_iterations": 2 } } } } } } }, "/v1/admin/skills/optimizations": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List skill-optimization proposals for a workspace (§1.3 review-gate). ?workspace_id=&pending=1.", "operationId": "get_v1_admin_skills_optimizations", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "pending", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string", "example": "1." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/skills/optimizations/{id}/accept": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Accept a proposal: apply its body to the skill + mark applied.", "operationId": "post_v1_admin_skills_optimizations_id_accept", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } } }, "/v1/admin/skills/optimizations/{id}/reject": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Reject (discard) a pending skill-optimization proposal.", "operationId": "post_v1_admin_skills_optimizations_id_reject", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } } }, "/v1/admin/agents/{id}/skills": { "get": { "tags": [ "Agents & orchestration" ], "summary": "List the skills attached to an agent.", "operationId": "get_v1_admin_agents_id_skills", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ], "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." }, "post": { "tags": [ "Agents & orchestration" ], "summary": "Create+attach a skill for an agent.", "operationId": "post_v1_admin_agents_id_skills", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" } } }, "example": { "name": "...", "content": "..." } } } } } }, "/v1/admin/agents/{id}/skills/{skillId}": { "post": { "tags": [ "Agents & orchestration" ], "summary": "Attach an existing skill to an agent.", "operationId": "post_v1_admin_agents_id_skills_skillId", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } }, "delete": { "tags": [ "Agents & orchestration" ], "summary": "Detach a skill from an agent.", "operationId": "delete_v1_admin_agents_id_skills_skillId", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill id." } ], "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log." } }, "/v1/admin/plugins": { "get": { "tags": [ "Modules & plugins" ], "summary": "List enabled plugins for the workspace.", "operationId": "get_v1_admin_plugins", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/plugins/enable": { "post": { "tags": [ "Modules & plugins" ], "summary": "Enable or disable a plugin.", "operationId": "post_v1_admin_plugins_enable", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "enabled": { "type": "boolean" } } }, "example": { "slug": "...", "enabled": true } } } } } }, "/v1/admin/modules/test": { "post": { "tags": [ "Modules & plugins" ], "summary": "Run an installed module's self-test.", "operationId": "post_v1_admin_modules_test", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "module_id": { "type": "string" } } }, "example": { "module_id": "..." } } } } } }, "/v1/admin/modules/reprobe": { "post": { "tags": [ "Modules & plugins" ], "summary": "Re-probe an installed module's health.", "operationId": "post_v1_admin_modules_reprobe", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "module_id": { "type": "string" } } }, "example": { "module_id": "..." } } } } } }, "/v1/admin/artifacts": { "get": { "tags": [ "Artifacts" ], "summary": "List canvas artifacts.", "operationId": "get_v1_admin_artifacts", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/artifacts/get": { "get": { "tags": [ "Artifacts" ], "summary": "Get one canvas artifact (?id=).", "operationId": "get_v1_admin_artifacts_get", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } } ] } }, "/v1/admin/artifacts/update": { "post": { "tags": [ "Artifacts" ], "summary": "Create/update a canvas artifact.", "operationId": "post_v1_admin_artifacts_update", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "id_01H...", "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" } } }, "example": { "id": "", "title": "...", "content": "..." } } } } } }, "/v1/admin/artifacts/run": { "post": { "tags": [ "Artifacts" ], "summary": "Run a canvas artifact (live execution).", "operationId": "post_v1_admin_artifacts_run", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } }, "example": { "id": "..." } } } } } }, "/v1/admin/artifacts/versions": { "get": { "tags": [ "Artifacts" ], "summary": "List an artifact's versions (?id=).", "operationId": "get_v1_admin_artifacts_versions", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/artifacts/restore": { "post": { "tags": [ "Artifacts" ], "summary": "Restore an artifact to a prior version.", "operationId": "post_v1_admin_artifacts_restore", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" } } }, "example": { "id": "...", "version": 1 } } } } } }, "/v1/admin/memory/contradictions": { "get": { "tags": [ "Memory" ], "summary": "List unresolved memory contradictions.", "operationId": "get_v1_admin_memory_contradictions", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "items": [] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional: maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional: number of items to skip (pagination)." } ] } }, "/v1/admin/memory/dream": { "post": { "tags": [ "Memory" ], "summary": "Run memory consolidation (\"dream\") now.", "operationId": "post_v1_admin_memory_dream", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } } } }, "/v1/admin/knowledge/connectors/notion/config": { "get": { "tags": [ "Knowledge" ], "summary": "Get the Notion knowledge-connector config.", "operationId": "get_v1_admin_knowledge_connectors_notion_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/knowledge/connectors/notion/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Trigger a Notion knowledge sync.", "operationId": "post_v1_admin_knowledge_connectors_notion_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/knowledge/connectors/slack/config": { "get": { "tags": [ "Knowledge" ], "summary": "Get the Slack knowledge-connector config.", "operationId": "get_v1_admin_knowledge_connectors_slack_config", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "configured": true } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/knowledge/connectors/slack/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Trigger a Slack knowledge sync.", "operationId": "post_v1_admin_knowledge_connectors_slack_sync", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/migrate/claims": { "post": { "tags": [ "Admin" ], "summary": "Migrate legacy memory into the claims store.", "operationId": "post_v1_admin_migrate_claims", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/migrate/parity": { "get": { "tags": [ "Admin" ], "summary": "Check parity between legacy and migrated stores.", "operationId": "get_v1_admin_migrate_parity", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/migrate/history": { "post": { "tags": [ "Admin" ], "summary": "Migrate conversation history.", "operationId": "post_v1_admin_migrate_history", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/migrate/secrets": { "post": { "tags": [ "Admin" ], "summary": "Re-wrap/migrate secrets to the current KEK.", "operationId": "post_v1_admin_migrate_secrets", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/migrate/cutover": { "post": { "tags": [ "Admin" ], "summary": "Cut over to the migrated store.", "operationId": "post_v1_admin_migrate_cutover", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/backup/download": { "get": { "tags": [ "Admin" ], "summary": "Download a full backup archive.", "operationId": "get_v1_admin_backup_download", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/onboarding/init": { "post": { "tags": [ "Admin" ], "summary": "Initialize first-run onboarding.", "operationId": "post_v1_admin_onboarding_init", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative endpoint for your AiHummer instance. Requires a key with `admin:write` scope (or an admin session); the action is authorized by role and recorded in the audit log.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/v1/admin/onboarding/status": { "get": { "tags": [ "Admin" ], "summary": "Onboarding progress/status.", "operationId": "get_v1_admin_onboarding_status", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/admin/connections/oauth/start": { "get": { "tags": [ "Admin" ], "summary": "Begin a personal-connection OAuth2 flow (?slug=).", "operationId": "get_v1_admin_connections_oauth_start", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session).", "parameters": [ { "name": "slug", "in": "query", "required": false, "description": "See endpoint description.", "schema": { "type": "string" } } ] } }, "/v1/admin/connections/oauth/callback": { "get": { "tags": [ "Admin" ], "summary": "Personal-connection OAuth2 redirect callback.", "operationId": "get_v1_admin_connections_oauth_callback", "responses": { "200": { "description": "Success. Returns a JSON payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Administrative read endpoint for your AiHummer instance. Requires a key with `admin:read` scope (or an admin session)." } }, "/v1/voice/diarize": { "post": { "tags": [ "Voice & video" ], "summary": "Speaker diarization (#47): upload audio (raw body, audio's Content-Type) to the host-native pyannote sidecar; returns who-spoke-when as JSON {\"segments\":[{\"start\":sec,\"end\":sec,\"speaker\":\"SPEAKER_00\"}]}. Only present when AIHUMMER_DIARIZE_URL is set.", "operationId": "post_v1_voice_diarize", "responses": { "200": { "description": "Diarization segments.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "segments": [ { "start": 0, "end": 2.4, "speaker": "SPEAKER_00" }, { "start": 2.4, "end": 5.1, "speaker": "SPEAKER_01" } ] } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "501": { "description": "Disabled until the corresponding sidecar URL is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Sidecar not configured.", "type": "invalid_request_error", "code": "not_configured" } } } } } }, "description": "Speaker diarization. Upload audio as the raw request body (with the audio’s `Content-Type`); the host-native pyannote sidecar returns who-spoke-when. Available only when the diarization sidecar URL is configured.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/voice/clone": { "post": { "tags": [ "Voice & video" ], "summary": "Voice cloning (#48): upload a reference voice sample (raw body, audio's Content-Type) with the target text in ?text= (or X-Voice-Text header); the host-native OpenVoice V2 sidecar (MIT) synthesizes the text in the reference speaker's timbre and returns audio/wav. Optional ?language= and ?speed=. Only present when AIHUMMER_VOICECLONE_URL is set.", "operationId": "post_v1_voice_clone", "responses": { "200": { "description": "Synthesized audio in the reference speaker’s voice.", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "501": { "description": "Disabled until the corresponding sidecar URL is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Sidecar not configured.", "type": "invalid_request_error", "code": "not_configured" } } } } } }, "description": "Voice cloning. Upload a reference voice sample as the raw request body and pass the target text in `?text=` (or the `X-Voice-Text` header); the host-native OpenVoice V2 sidecar synthesizes the text in the reference speaker’s timbre and returns `audio/wav`. Available only when the voice-clone sidecar URL is configured.", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Text to synthesize (or send via the X-Voice-Text header)." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "speed", "in": "query", "required": false, "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/video/understand": { "post": { "tags": [ "Voice & video" ], "summary": "Video understanding (#32): upload a video (raw body, video's Content-Type) to the host-native ffmpeg sidecar; it demuxes the audio (transcribed by the existing Whisper STT sidecar) and samples keyframes at scene changes. Returns JSON {\"duration\":sec,\"transcript\":\"...\",\"keyframes\":[{\"ts\":sec,\"image_b64\":\"...\",\"content_type\":\"image/jpeg\"}],\"metadata\":{...}}. Transcript needs AIHUMMER_STT_URL. Only present when AIHUMMER_VIDEO_URL is set.", "operationId": "post_v1_video_understand", "responses": { "200": { "description": "Transcript, keyframes and metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "duration": 42, "transcript": "Welcome to the demo…", "keyframes": [ { "ts": 1.5, "image_b64": "…", "content_type": "image/jpeg" } ], "metadata": {} } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "501": { "description": "Disabled until the corresponding sidecar URL is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Sidecar not configured.", "type": "invalid_request_error", "code": "not_configured" } } } } } }, "description": "Video understanding. Upload a video as the raw request body; the host-native ffmpeg sidecar demuxes the audio (transcribed by the Whisper STT sidecar) and samples keyframes at scene changes. Available only when the video sidecar URL is configured.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Chat (OpenAI-compatible)" ], "summary": "OpenAI-compatible chat completion. Send model + messages[]; set stream:true for SSE deltas.", "operationId": "post_v1_chat_completions", "responses": { "200": { "description": "Chat completion. With `stream:true` the response is instead `text/event-stream` carrying `chat.completion.chunk` events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "OpenAI-compatible Chat Completions. Point any OpenAI SDK at your AiHummer instance, set the API key to an `ah-…` key, and call this endpoint. Set `stream:true` to receive `chat.completion.chunk` deltas over Server-Sent Events terminated by `data: [DONE]`. This is the only chat endpoint — there is no `/v1/models` or `/v1/embeddings`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } } } }, "/v1/ping": { "get": { "tags": [ "System" ], "summary": "Liveness probe (unauthenticated).", "operationId": "get_v1_ping", "responses": { "200": { "description": "The gateway is alive.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } } }, "description": "Liveness probe. Unauthenticated.", "security": [] } }, "/v1/time": { "get": { "tags": [ "System" ], "summary": "Current gateway server time (unauthenticated).", "operationId": "get_v1_time", "responses": { "200": { "description": "Server time.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "time": "2026-01-01T12:00:00Z" } } } } }, "description": "Current gateway server time (RFC 3339). Unauthenticated.", "security": [] } }, "/v1/inbound/telegram": { "post": { "tags": [ "Inbound & triggers" ], "summary": "Native Telegram inbound payloads (HMAC X-AIHummer-Inbound-Secret).", "operationId": "post_v1_inbound_telegram", "responses": { "202": { "description": "Accepted and queued for an agent turn.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "accepted": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Receives native Telegram update payloads from the Telegram connector. Authenticate with the shared inbound secret via `X-AIHummer-Inbound-Secret`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "update_id": 1, "message": { "chat": { "id": 123 }, "text": "Hello" } } } } } } }, "/v1/inbound/generic": { "post": { "tags": [ "Inbound & triggers" ], "summary": "Generic inbound for email→webhook, cron and custom apps (HMAC secret).", "operationId": "post_v1_inbound_generic", "responses": { "202": { "description": "Accepted and queued for an agent turn.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "accepted": true, "conversation_id": "conv_01H..." } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Generic inbound webhook for email→webhook bridges, cron jobs and custom apps. Authenticate with the shared inbound secret via `X-AIHummer-Inbound-Secret` (HMAC of the body). The message is routed to the matching agent and answered through the originating channel.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundEnvelope" } } } } } }, "/v1/inbound/binding/status": { "post": { "tags": [ "Inbound & triggers" ], "summary": "Report channel-binding status (HMAC secret).", "operationId": "post_v1_inbound_binding_status", "responses": { "200": { "description": "Status recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "A connector reports the live status of a channel binding (connected / disconnected). Authenticate with the shared inbound secret via `X-AIHummer-Inbound-Secret`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "channel": "telegram", "binding_id": "bnd_01H...", "status": "connected" } } } } } }, "/v1/web/session": { "post": { "tags": [ "Inbound & triggers" ], "summary": "Open an embeddable web-widget visitor session.", "operationId": "post_v1_web_session", "responses": { "200": { "description": "Session opened.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "conversation_id": "conv_01H...", "branding": { "name": "Acme Assistant", "logo_url": "https://…/logo.png" } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } } }, "description": "Open an embeddable web-widget visitor session. Public and workspace-scoped (no admin auth). Returns the conversation id and branding the widget renders; replies then stream over `GET /v1/web/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace" ], "properties": { "workspace": { "type": "string", "description": "Target workspace id." }, "agent": { "type": "string", "description": "Optional agent id; defaults to the workspace fallback." }, "session": { "type": "string", "description": "Opaque per-visitor session token." } } }, "example": { "workspace": "ws_01H...", "session": "visitor-abc" } } } } } }, "/v1/web/stream": { "get": { "tags": [ "Inbound & triggers" ], "summary": "Stream web-widget assistant replies as Server-Sent Events.", "operationId": "get_v1_web_stream", "responses": { "200": { "description": "An SSE stream (`text/event-stream`) of assistant deltas.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"delta\":\"Hello\"}\n\ndata: [DONE]\n\n" } } } }, "description": "Server-Sent Events stream of web-widget assistant replies for a visitor session. Public and workspace-scoped.", "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Conversation id from `POST /v1/web/session`." } ] } }, "/v1/events/stream": { "get": { "tags": [ "Inbound & triggers" ], "summary": "Resumable Server-Sent Events feed of gateway events (?since= cursor).", "operationId": "get_v1_events_stream", "responses": { "200": { "description": "An SSE stream (`text/event-stream`) of gateway events.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "id: 42\nevent: turn.completed\ndata: {\"conversation_id\":\"conv_01H...\"}\n\n" } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Resumable Server-Sent Events feed of gateway events. Pass `?since=` to resume after a disconnect.", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor of the last event received; resumes after it." } ] } }, "/v1/pairing/redeem": { "post": { "tags": [ "Devices & pairing" ], "summary": "Redeem a pairing code and provision a device.", "operationId": "post_v1_pairing_redeem", "responses": { "200": { "description": "Device provisioned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "device_id": "dev_01H...", "token": "eyJhbGciOi...", "branding": { "name": "Acme Assistant", "logo_url": "https://…/logo.png" } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Invalid or expired pairing code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Pairing code invalid or expired.", "type": "invalid_request_error", "code": "invalid_code" } } } } } }, "description": "Redeem a one-time pairing code (shown as a QR in the admin UI / app) to provision a device. Returns the device credentials and instance branding the app shows after pairing. No admin auth.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingRedeem" } } } } } }, "/v1/pairing/device/validate": { "post": { "tags": [ "Devices & pairing" ], "summary": "Validate an already-paired device.", "operationId": "post_v1_pairing_device_validate", "responses": { "200": { "description": "Device is valid.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "valid": true, "device_id": "dev_01H..." } } } }, "401": { "description": "Device is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Device revoked or unknown.", "type": "invalid_request_error", "code": "device_invalid" } } } } } }, "description": "Validate that an already-paired device is still authorized. The app calls this on launch. No admin auth.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "device_id", "token" ], "properties": { "device_id": { "type": "string" }, "token": { "type": "string" } } }, "example": { "device_id": "dev_01H...", "token": "eyJhbGciOi..." } } } } } }, "/v1/oauth/token": { "post": { "tags": [ "Auth & SSO" ], "summary": "OAuth2 token endpoint (client_credentials for service-account API keys).", "operationId": "post_v1_oauth_token", "responses": { "200": { "description": "Access token issued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "access_token": "ah-...", "token_type": "Bearer", "expires_in": 3600, "scope": "admin:read" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Invalid client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "invalid_client", "type": "invalid_request_error", "code": "invalid_client" } } } } } }, "description": "OAuth2 token endpoint. Exchange a service-account API key registered as an OAuth2 client (see `POST /v1/admin/apikeys/register-client`) for a bearer access token using the `client_credentials` grant.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string" } } }, "example": { "grant_type": "client_credentials", "client_id": "cid_01H...", "client_secret": "csec_...", "scope": "admin:read" } } } } } }, "/v1/mcp": { "post": { "tags": [ "MCP & A2A" ], "summary": "MCP server endpoint — publish AiHummer tools to MCP clients (opt-in, AIHUMMER_MCP_PUBLISH=1).", "operationId": "post_v1_mcp", "responses": { "200": { "description": "JSON-RPC result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [] } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Model Context Protocol (MCP) server endpoint — publishes selected AiHummer tools to MCP clients over JSON-RPC. Opt-in; present only when MCP publishing is enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } } } }, "/.well-known/agent.json": { "get": { "tags": [ "MCP & A2A" ], "summary": "A2A agent card / discovery document (opt-in).", "operationId": "get_well_known_agent_json", "responses": { "200": { "description": "The agent card.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "AiHummer", "description": "Self-hosted AI agent", "url": "https://your-instance.example.com/a2a/message", "capabilities": {} } } } } }, "description": "Agent-to-Agent (A2A) discovery document / agent card. Opt-in; present only when A2A publishing is enabled.", "security": [] } }, "/a2a/message": { "post": { "tags": [ "MCP & A2A" ], "summary": "Receive an Agent-to-Agent message (opt-in, AIHUMMER_A2A_PUBLISH=1).", "operationId": "post_a2a_message", "responses": { "200": { "description": "The agent’s reply.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "message": { "role": "agent", "parts": [ { "text": "Hello back" } ] } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "description": "Receive an Agent-to-Agent (A2A) message from another agent. Opt-in; present only when A2A publishing is enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "message": { "role": "user", "parts": [ { "text": "Hello from agent B" } ] } } } } } } }, "/v1/media/{id}/content": { "put": { "tags": [ "Media & files" ], "summary": "Upload the bytes for a media object.", "operationId": "put_v1_media_id_content", "responses": { "200": { "description": "Bytes stored.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "media_01H...", "size": 20480, "content_type": "image/png" } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request payload.", "type": "invalid_request_error", "code": "bad_request" } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Upload the raw bytes for a previously created media object. Send the file as the request body with its own `Content-Type`.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/files/{id}": { "get": { "tags": [ "Media & files" ], "summary": "Download a stored file.", "operationId": "get_v1_files_id", "responses": { "200": { "description": "The file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Missing or invalid API key.", "type": "invalid_request_error", "code": "unauthorized" } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Not found.", "type": "invalid_request_error", "code": "not_found" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "description": "Download a stored file by id. Returns the raw bytes with the stored `Content-Type`." } } } }