> ## Documentation Index > Fetch the complete documentation index at: https://docs.svantic.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a knowledge base > Updates config or metadata for an existing knowledge base. Requires 'full' scope. ## OpenAPI ````yaml /api-reference/openapi-bundled.yaml post /knowledge_base/update openapi: 3.1.0 info: title: Svantic API version: 1.0.0 description: > Svantic is a secured API platform that connects your existing systems to AI agent fleets. It supports the full agent-to-agent path—discovery, orchestration, governance, and knowledge—so you can ship AI-driven automation on a predictable foundation. At its core, the API streamlines multi-agent collaboration. Agents authenticate with client credentials, discover one another through A2A-compliant agent cards, and exchange messages via session-scoped JSON-RPC. Svantic orchestrates work across fleets, enforces guardrails and policies, and pairs semantic search with tamper-proof audit trails. The platform covers lifecycle management for agent conversations, continuous learning, governance with alerts and notification channels, and human-in-the-loop approvals — all exposed as straightforward POST-based APIs. You focus on domain logic inside each agent; Svantic handles discovery, routing, safety, and observability. contact: name: Svantic Support email: support@svantic.com servers: - url: https://api.svantic.com description: Production - url: https://mesh.svantic.com description: Mesh runtime security: - bearerAuth: [] tags: - name: Introduction description: > #### Welcome to the Svantic API Svantic is a production runtime for AI agent fleets. It handles discovery, orchestration, learning, governance, and collaboration — so you can focus on the domain logic inside each agent. #### How it works 1. **Authenticate** — Exchange client credentials for a JWT via `POST /auth/get_token`. 2. **Create a session** — Call `POST /sessions/init` with an `instance_id`. The gateway generates a `session_id`, extracts `tenant_id` from your JWT, and returns the session details. 3. **Communicate** — Send messages via `POST /send` using the A2A JSON-RPC protocol. Supports both synchronous (`message/send`) and streaming (`message/stream`) responses. 4. **Manage knowledge** — Ingest documents, run semantic searches, and track processing jobs through the Knowledge Base endpoints. 5. **Handle approvals & human input** — When agents need human input (approvals, forms, confirmations), messages enter `input-required` state. Resolve via the dashboard, `POST /messages/{id}/resolve`, or webhook callbacks. - name: API Protocols & Headers description: > ## Protocols All Svantic API endpoints use **HTTP POST** with JSON request and response bodies. The only exceptions are: - `GET /.well-known/agent-card.json` — A2A agent card discovery - `GET /health` — infrastructure health check Streaming responses (e.g., `message/stream` via `/send`) use **Server-Sent Events (SSE)** over the same HTTP POST connection. ## Required Headers | Header | Value | When | |---|---|---| | `Content-Type` | `application/json` | All POST requests | | `Authorization` | `Bearer ` | Authenticated endpoints — all tokens are JWTs with scopes | ## JSON-RPC 2.0 The `/send` endpoint accepts JSON-RPC 2.0 payloads. Supported methods: | Method | Description | |---|---| | `message/send` | Synchronous message — waits for full response | | `message/stream` | Streaming message — returns SSE event stream | Request format: ```json { "jsonrpc": "2.0", "id": "req-001", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "msg-001", "role": "user", "parts": [{ "kind": "text", "text": "Your prompt here" }] } } } ``` - name: Environments description: > | Environment | Base URL | Description | |---|---|---| | **Production** | `https://api.svantic.com` | Live production environment | - name: Credentials & Access description: > ### Authentication All authenticated requests use `Authorization: Bearer `. There is a single token format — a JWT signed by the gateway. #### Obtaining a token Exchange client credentials for a JWT via `POST /auth/get_token`: ```bash curl -X POST https://api.svantic.com/auth/get_token \ -H "Content-Type: application/json" \ -d '{"client_id": "your-credential-id", "client_secret": "your-secret", "agent_type": "my-agent"}' ``` The response contains a `token` field — a JWT valid for 24 hours. Use it in subsequent requests: ```bash curl -X POST https://api.svantic.com/sessions/init \ -H "Authorization: Bearer eyJ..." \ -H "Content-Type: application/json" \ -d '{"instance_id": "inst-001"}' ``` ### Callback Token Outbound webhook notifications include a single-use, time-limited `callback_token`. External systems resolve pending messages via `POST /messages/{id}/resolve` by passing this token in the request body — no JWT required. Authenticated callers use a JWT instead. - name: Versioning description: > ## API Versioning The Svantic API is currently at **v1.0.32**. All endpoints are unversioned in the URL path. ### Stability Guarantees - **Stable endpoints** (Auth, Agents, Sessions, Knowledge Base): Breaking changes will be communicated with at least 30 days notice and a migration guide. - **Experimental endpoints** : May change without notice. Marked with `x-experimental: true` in the spec when applicable. ### Deprecation Policy Deprecated endpoints return a `Deprecation` header with the sunset date. They continue to function until the sunset date, after which they return `410 Gone`. - name: Endpoints description: > ## Endpoint Conventions All Svantic API endpoints follow these conventions: - **HTTP Method**: All operations use `POST` unless explicitly stated otherwise. - **Request bodies**: JSON. Identifiers are passed in the body, not in the URL path - **Response format**: JSON with consistent envelope (`ok`, `error`, resource-specific fields) ### Error Responses All errors follow a consistent format: ```json { "error": "Human-readable error message", "code": "MACHINE_READABLE_CODE" } ``` ### Common HTTP Status Codes | Code | Meaning | |---|---| | `200` | Success | | `400` | Validation error — missing or invalid fields | | `401` | Authentication failed — missing, invalid, or expired credentials | | `403` | Insufficient scope — JWT scopes do not include required permission | | `404` | Resource not found | | `409` | Conflict — duplicate or already-processed resource | | `410` | Gone — expired resource (e.g., callback token) | | `500` | Internal server error — unexpected error in the application code | | `502` | Upstream service unavailable (e.g., Knowledge Service, LLM provider) | | `503` | Service not configured due to internal configuration error | ### Async Operations & Job Tracking Several operations (ingest, refresh, create) may run asynchronously for large payloads. These endpoints return a `job_id` with an initial `status` of `"processing"`. Poll `POST /knowledge_base/get_status` with the `job_id` until `status` is `"completed"` or `"failed"`. When an agent needs human input, the message enters `input-required` state. Authenticated callers resolve via `POST /messages/{id}/resolve` with a JWT. External systems that received a webhook notification resolve via the same endpoint using a `callback_token` in the request body — no JWT required. - name: Agents description: >- Purpose: connect your running agents to Svantic so they are discoverable, eligible for orchestration, and aligned with your access rules—this is the resource you use to bring your fleet into the platform and keep that picture current. - name: Messages description: >- The unified resource for all agent interactions. Send messages via A2A JSON-RPC (`POST /send`), query message history (`/messages/get`, `/messages/get_by_id`), cancel running messages (`/messages/cancel`), list those awaiting human input (`/messages/pending`), and submit resolutions (`/messages/{id}/resolve`). Every message belongs to a session and tracks the full lifecycle — submitted, working, input-required, completed, failed, or canceled. - name: Sessions description: >- Session lifecycle — create (`init`), close, and interrupt — plus query endpoints for listing sessions and retrieving session detail. Pending work within sessions (approvals, human input) is managed via the Messages resource (`/messages/pending`, `/messages/{id}/resolve`). - name: Knowledge Base description: > Knowledge base management — CRUD, document ingest, semantic search, embedding refresh, and job status tracking. All knowledge operations go through the gateway (`POST /knowledge_base/*`); there is no separate direct-to-backend path for callers. The gateway validates the JWT and routes requests downstream with the caller's token context. All endpoints require JWT authentication via `Authorization: Bearer `. Read operations (list, get, query, stats) require `read` scope or higher. Mutations (create, update, delete, ingest, refresh) require `full` scope. - name: Policies description: > Guard policies control what agents can do — tool access, admission, dispatch. Alert rules define when and where the platform sends notifications, with inline notification targets using built-in channel types (webhook, Slack, email). To permanently allow a previously blocked tool, update the policy decision. All endpoints require `admin` scope. - name: Telemetry description: > Read-only telemetry data — traces, usage statistics, events, and real-time event streaming. Provides observability into agent fleet activity for dashboards and monitoring. All endpoints require `read` scope. - name: Webhooks description: > Svantic sends outbound webhooks to notify your systems when significant events occur. Webhooks are **outbound only** — Svantic pushes event payloads to URLs you configure as notification channels. To receive webhooks, register a webhook notification channel via the dashboard or API, then attach it to an alert rule or policy. When a matching event fires, Svantic delivers a signed JSON payload to your endpoint. ### Delivery - **Method**: `POST` with `Content-Type: application/json` - **Retries**: Up to 3 attempts with exponential backoff (1s, 5s, 30s) - **Timeout**: 10 seconds per attempt - **Idempotency**: Each delivery includes a unique `delivery_id`; use it to deduplicate - **Success**: Any `2xx` response is treated as successful delivery - **Client errors**: `4xx` responses stop retries immediately (no point retrying a bad endpoint) - **Server errors**: `5xx` responses trigger retries ### Signature Verification Every outbound webhook includes an `X-Svantic-Signature` header containing an HMAC-SHA256 signature computed over the raw request body using the channel's configured `secret`. To verify: ```typescript import { createHmac, timingSafeEqual } from "node:crypto"; const expected = createHmac("sha256", secret).update(rawBody).digest("hex"); const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-svantic-signature"]!)); ``` ### Event Categories Svantic emits webhook notifications for events across these categories: | Category | Description | |---|---| | `agent` | Agent lifecycle — registration, health changes, capacity | | `session` | Session creation and closure | | `dispatch` | Work dispatched to agents — success or failure | | `message` | Message lifecycle — received, completed, errors | | `policy` | Policy evaluation outcomes — denied, approval required | | `guard` | Guard decisions — allowed, denied, approval required | | `plan` | Execution plans — created, approved, completed, failed | | `system` | Platform events — alerts triggered | | `tenant` | Tenant lifecycle — created, deleted | ### Webhook Payload Schema Every webhook delivery uses this envelope: ```json { "delivery_id": "d-a1b2c3d4", "event_type": "agent.health_changed", "timestamp": "2026-04-17T14:30:00.000Z", "tenant_id": "tenant-abc", "session_id": "sess-123", "rule_name": "Agent unhealthy", "severity": "critical", "type": "alert", "event": { }, "callback_token": "rAnDoM_base64url_token", "resolve_url": "https://api.svantic.com/messages/{id}/resolve" } ``` | Field | Type | Description | |---|---|---| | `delivery_id` | string | Unique identifier for this delivery attempt (for idempotency) | | `event_type` | string | The specific event that triggered this webhook (e.g., `agent.health_changed`) | | `timestamp` | string (ISO 8601) | When the event occurred | | `tenant_id` | string | Tenant that owns the resource | | `session_id` | string | Session context (empty string if not session-scoped) | | `rule_name` | string | Name of the alert rule or policy that matched | | `severity` | string | `info`, `warning`, or `critical` | | `type` | string | `alert` for event notifications, `approval_required` for human-in-the-loop | | `event` | object | Event-specific data (see per-event schemas below) | | `callback_token` | string | Single-use token for resolving approval requests without JWT auth | | `resolve_url` | string | URL to POST resolution to (only present for `approval_required` type) | ### Event Types Reference #### Agent Events **`agent.registered`** — An agent instance registered with the platform. ```json { "agent_type": "my-agent", "instance_id": "inst-001", "tenant_id": "tenant-abc", "connect_mode": "connected" } ``` **`agent.deregistered`** — An agent instance was removed (explicit deregistration or reaped for inactivity). ```json { "agent_type": "my-agent", "instance_id": "inst-001", "reason": "explicit" } ``` **`agent.health_changed`** — An agent's health status transitioned. ```json { "agent_type": "my-agent", "instance_id": "inst-001", "status": "unhealthy", "previous_status": "available" } ``` **`agent.capacity_changed`** — An agent's session capacity changed. ```json { "agent_type": "my-agent", "instance_id": "inst-001", "current_sessions": 5, "max_concurrent_sessions": 10 } ``` #### Session Events **`session.created`** — A new session was initialized. ```json { "session_id": "sess-123", "tenant_id": "tenant-abc", "created_by": "inst-001" } ``` **`session.closed`** — A session was closed. ```json { "session_id": "sess-123", "reason": "user_closed", "duration_ms": 45000 } ``` #### Dispatch Events **`dispatch.sent`** — Work was dispatched to an agent. ```json { "dispatch_id": "d-001", "instance_id": "inst-001", "skill_id": "summarize", "session_id": "sess-123" } ``` **`dispatch.success`** — A dispatch completed successfully. ```json { "dispatch_id": "d-001", "instance_id": "inst-001", "duration_ms": 1200 } ``` **`dispatch.failed`** — A dispatch failed. ```json { "dispatch_id": "d-001", "instance_id": "inst-001", "error": "timeout", "duration_ms": 30000 } ``` #### Message Events **`message.received`** — A user message was received. ```json { "message_id": "msg-001", "session_id": "sess-123", "role": "user" } ``` **`message.completed`** — An agent response was delivered. ```json { "message_id": "msg-002", "session_id": "sess-123", "role": "agent", "duration_ms": 3400 } ``` **`message.error`** — A message processing error occurred. ```json { "message_id": "msg-001", "session_id": "sess-123", "error": "LLM provider timeout" } ``` #### Policy & Guard Events **`policy.denied`** — A policy denied an action. ```json { "policy_id": "pol-001", "policy_name": "No PII export", "action": "tool_call", "tool": "export_csv", "reason": "PII detected" } ``` **`policy.approval_required`** — A policy requires human approval before proceeding. ```json { "policy_id": "pol-001", "policy_name": "High-value actions", "action": "tool_call", "tool": "delete_records", "message_id": "msg-001", "session_id": "sess-123" } ``` **`guard.denied`** — A guard blocked an operation. ```json { "guard": "resource_budget", "action": "tool_call", "tool": "batch_delete", "reason": "Budget exceeded" } ``` **`guard.approval_required`** — A guard requires approval. ```json { "guard": "file_access", "action": "tool_call", "tool": "read_file", "path": "/etc/config", "message_id": "msg-001" } ``` #### Plan Events **`plan.created`** — An execution plan was generated. ```json { "plan_id": "plan-001", "session_id": "sess-123", "step_count": 4, "description": "Research and summarize quarterly results" } ``` **`plan.approved`** — A plan was approved for execution. ```json { "plan_id": "plan-001", "approved_by": "user@example.com" } ``` **`plan.completed`** — A plan finished executing. ```json { "plan_id": "plan-001", "session_id": "sess-123", "steps_completed": 4, "duration_ms": 120000 } ``` **`plan.failed`** — A plan failed during execution. ```json { "plan_id": "plan-001", "session_id": "sess-123", "failed_step": 3, "error": "Agent timeout on step 'analyze'" } ``` #### System Events **`system.alert_triggered`** — A system-level alert rule fired. ```json { "rule_id": "rule-001", "rule_name": "High error rate", "threshold": 5, "window_seconds": 300, "count": 7 } ``` **`tenant.created`** — A new tenant was provisioned. ```json { "tenant_id": "tenant-new", "name": "Acme Corp" } ``` ### Approval Webhooks When a policy or guard requires human approval, the webhook payload uses `type: "approval_required"` and includes `callback_token` and `resolve_url`. Your system can resolve the request by POSTing back: ```bash curl -X POST https://api.svantic.com/messages/msg-001/resolve \ -H "Content-Type: application/json" \ -d '{"callback_token": "rAnDoM_base64url_token", "resolution": "approved"}' ``` The `callback_token` is single-use, time-limited (default 24 hours), and does not require JWT authentication. See the [Long-Running Operations Guide](/guides/long-running-operations) for details. ### Configuring Webhooks Webhook channels are managed through the notification channels API or the dashboard: 1. Create a webhook channel with your endpoint URL and optional HMAC secret 2. Attach the channel to an alert rule or policy 3. Svantic delivers matching events to your endpoint with signature verification All deliveries are logged with status code, response time, and success/failure for audit and debugging. paths: /knowledge_base/update: post: tags: - Knowledge Base summary: Update a knowledge base description: >- Updates config or metadata for an existing knowledge base. Requires 'full' scope. operationId: knowledge_base_update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/kb_update_request' examples: sample: $ref: '#/components/examples/knowledge_base_update_request' responses: '200': description: Knowledge base updated. content: application/json: schema: $ref: '#/components/schemas/kb_update_response' '400': $ref: '#/components/responses/bad_request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/not_found' '408': $ref: '#/components/responses/request_timeout' '500': $ref: '#/components/responses/internal_error' '502': $ref: '#/components/responses/bad_gateway' '503': $ref: '#/components/responses/service_unavailable' security: - bearerAuth: [] components: schemas: kb_update_request: type: object required: - namespace properties: namespace: type: string display_name: type: string description: type: string config: type: object kb_update_response: type: object required: - ok - knowledge_base properties: ok: type: boolean knowledge_base: $ref: '#/components/schemas/kb_detail' kb_detail: type: object required: - namespace properties: namespace: type: string display_name: type: string description: type: string visibility: type: string config: type: object properties: top_k: type: integer min_score: type: number created_at: type: string format: date-time error_response: type: object required: - error properties: error: type: string description: Human-readable error message. code: type: string description: Machine-readable error code, when available. request_id: type: string description: > Correlation id for support — present on some gateway catch-all responses (e.g. unmatched route, unhandled error). timestamp: type: string format: date-time description: >- ISO 8601 time when the error was produced, when returned by the gateway. examples: knowledge_base_update_request: summary: Sample request body for knowledge base update value: namespace: string display_name: string description: string config: {} error_bad_request_example: summary: Validation or malformed JSON body value: error: Invalid request body code: BAD_REQUEST error_unauthorized_example: summary: Authentication failed value: error: Invalid or expired token code: unauthorized error_forbidden_example: summary: Insufficient scope value: error: JWT does not include the required scope for this operation code: forbidden error_not_found_example: summary: Resource or route not found value: error: Not found code: NOT_FOUND request_id: req_01EXAMPLE timestamp: '2026-03-31T12:00:00.000Z' error_request_timeout_example: summary: Client or gateway request timeout value: error: Request timeout code: REQUEST_TIMEOUT error_internal_example: summary: Unhandled gateway error value: error: Internal server error code: INTERNAL_ERROR request_id: req_01EXAMPLE timestamp: '2026-03-31T12:00:00.000Z' error_bad_gateway_example: summary: Upstream or proxy failure value: error: Bad gateway code: BAD_GATEWAY error_service_unavailable_example: summary: Dependency or signing unavailable value: error: Service temporarily unavailable code: SERVICE_UNAVAILABLE responses: bad_request: description: > Malformed JSON, failed request validation, or missing required fields in the body (gateway returns before the handler runs in some cases). content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_bad_request_example' unauthorized: description: Authentication failed — missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_unauthorized_example' forbidden: description: >- Insufficient scope — JWT does not carry the required scope for this operation. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_forbidden_example' not_found: description: > Unknown resource identifier, tenant mismatch for the requested resource, or (for unmatched HTTP routes) the gateway catch-all `NOT_FOUND` envelope. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_not_found_example' request_timeout: description: | Request exceeded the gateway timeout window (HTTP 408). content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_request_timeout_example' internal_error: description: > Unhandled exception in the gateway — `INTERNAL_ERROR` with optional `request_id` and `timestamp` for correlation. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_internal_example' bad_gateway: description: > Gateway received an invalid or failed response from an upstream dependency (MCP Servers, Mesh, Gateway, etc.), or could not complete a proxied request. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_bad_gateway_example' service_unavailable: description: > Temporary failure — e.g. JWT signing not configured (`MESH_SECRET` missing on token route), mesh or upstream unreachable, or dependency unavailable. content: application/json: schema: $ref: '#/components/schemas/error_response' examples: sample: $ref: '#/components/examples/error_service_unavailable_example' ````