HTTP API reference

SoAI provides OpenAI-compatible and Anthropic-compatible inference endpoints alongside the authenticated APIs that power the WebUI. The inventory below lists the HTTP operations available in the current SoAI release.

Use the SoAI WebUI for routine administration. The management routes exist for integrations and automation, but they use the same access controls as their WebUI controls and can change with the product. For browser-facing tasks, start with the linked guide rather than calling a WebUI route directly.

Manage personal memory

The authenticated /api/v1/webui/users/me/memory/entries library returns stable entry IDs, opaque entry revisions, profile_form, and profile_revision. Relationships include both endpoint IDs and names. The original GET /api/v1/webui/users/me/memory snapshot retains its existing response shape.

Create a note with POST /entries under the memory route, supplying an opaque id that fits one URL path segment, name, and content. Creation does not overwrite an existing ID or title. Edit an entry with PATCH /entries/{entry_id}, an expected_revision, and an optional name or observation. An observation contains id and content; a null observation ID adds a fact, while an existing ID edits that fact alone.

Entry, observation, and relationship deletion require expected_revision in the query string. Relationship updates preserve the relationship ID and require from_entity_id, to_entity_id, relation_type, and expected_revision. One endpoint must remain connected to the addressed entry. A changed revision returns a conflict; reload and review before submitting another mutation. A lost response is not proof that a request failed, so inspect the current saved state rather than automatically repeating creation or deletion.

Structured profile facts use PUT /api/v1/webui/users/me/memory/chat-profile. Include the library's profile_revision as expected_revision to reject stale updates. Omitted fields remain unchanged in revision-checked requests. Legacy requests without this precondition retain their unconditional update behavior and existing response shape. Facts and display-name defaults save together; removing a profile entry does not remove those display-name defaults.

Choose and secure API access

Authentication and runtime schema

Finish the first-run setup wizard before using the compatible APIs. After setup, /v1/* is open while the API-key store has no records. Creating the first key makes API-key authentication required; removing every key deliberately restores the open state. An administrator with API key management (OPENAI_API_ADMIN) permission selects the Settings button at the right of the header, then chooses Settings and OpenAI to manage keys. See Authentication and API keys for the exact WebUI controls, quotas, assignments, and security consequences.

Authorization: Bearer <OPENAI_API_KEY>

Anthropic-compatible clients may send the same value in x-api-key or as a bearer token. If both are sent, they must match. The browser uses its signed-in WebUI session; direct state-changing calls to protected /api/v1/* routes also need the CSRF protection expected by that surface.

POST /api/v1/webui/skills/import-batch and GET /api/v1/webui/skills/import-batches/{upload_id} require MCP usage (MCP_USE). The WebUI uses these routes for all skill uploads. Library contents and conversation selections remain private to their owning account.

Fetch the live OpenAPI document from /api/v1/openapi.json or /v1/openapi.json. Both paths return the same schema and use the compatible API access policy. The document describes request parameters and response shapes more precisely than this route list.

Inference and management surfaces

The OpenAI-compatible surface uses ordinary REST responses. Where an endpoint supports stream=true, it emits OpenAI Server-Sent Events with data: {...} frames followed by data: [DONE]. Do not send WebSocket envelopes on those streams.

The Anthropic-compatible Messages surface requires anthropic-version: 2023-06-01. Its streaming response uses Anthropic named Server-Sent Events. It accepts the Messages and token-counting requests listed below; Claude Code explains its WebUI model setup and client configuration.

Responses is a full lifecycle surface rather than a create-only endpoint, with creation, retrieval, cancellation, deletion, input-item retrieval, input-token counting, and compaction. Read OpenAI-compatible Responses API before using stored or background responses.

Provider errors and retry guidance

A model that cannot satisfy a request's required capability returns HTTP 422 with error.type set to invalid_request_error and error.param set to model. For embeddings, select a model that supports embeddings. A virtual model remains usable when an eligible member supports the request; a request whose capability combination matches no single member is rejected with that explanation.

An unknown model ID returns HTTP 400 with error.code set to model_not_found and error.param set to model. Install or register the requested model, or choose an ID from /v1/models. A failed download does not make its intended model available to the API.

Provider failures use the standard error response object. When the provider identifies a rejected parameter, error.param names it; the safe error message includes available recovery guidance and a sanitized provider explanation. Authentication failures return HTTP 401, while permission failures return HTTP 403 with permission_error. Billing failures remain distinct from temporary rate limits.

A valid provider cooldown is returned in Retry-After when the HTTP response has not started. SoAI honors that minimum during eligible retries, including delays longer than 30 seconds. A retry that would consume the remaining recovery budget is declined. Once streaming has started, a terminal error uses the existing stream format; the HTTP status and headers cannot change. Partial output remains available and is not replayed automatically.

Model capability overrides

Managing capabilities requires MODEL_ADMIN permission. The /api/v1/models/{universal_id}/capabilities/openai route retains these operations:

The model collection includes a read-only openai_base_profile derived from model and plugin evidence before saved overrides and dependency suppression. It supplies the base capability values for Auto.

Conversation titles

Creating a conversation with POST /api/v1/webui/conversations preserves its supplied title by default. Set the optional boolean title_auto_update_allowed to true to allow first-message and automatic title updates. Saving a title with PATCH /api/v1/webui/conversations/{conv_id}/title disables automatic replacement, even when the saved text is unchanged. Conversation metadata responses and title update events include the committed title, permission, and last_modified_at_ms together. Clones preserve the source permission; imported conversations and existing saved conversations keep their names. Clients receiving older payloads should preserve known permission when the optional field is absent.

Conversation input queue

A steer sent to /api/v1/webui/conversations/{conv_id}/input-queue returns HTTP 409 when no running turn can accept it. Set fallback_to_prompt to true to have SoAI queue it as an ordinary prompt instead; the response's input_type shows which one was stored. The field is optional and only valid for steers.

WebUI-first management guides

Skill library and conversation selection

The authenticated WebUI skill routes manage a human account's private skill library and the saved selection of an ordinary conversation. They do not enable personal skills for external inference calls. Import takes a multipart file and an upload_id; reuse that ID only for the same bytes when recovering an uncertain result, and query its receipt before retrying. Selection updates supply expected_revision and skill_ids. A stale revision returns 409 with the current selection so the client can review the conflict instead of overwriting it.

Transport and network boundaries

/api/v1/system/ws is the WebUI WebSocket endpoint. It carries subscribed real-time resources and interactive sessions; it is not a general replacement for OpenAI streaming, MCP streamable HTTP, or the REST API. See Monitoring and observability for the freshness and reconnect behavior users see in the WebUI.

SoAI also has a separate port-discovery listener. It binds the first available port from 7950 through 7960; GET / on that listener reports the main API port and scheme. That endpoint does not belong to the main FastAPI schema below.

Reverse proxies and private access

Keep SoAI on the private network boundary defined in Security hardening. A reverse proxy does not make public internet exposure a recommended deployment. If a proxy serves private clients, it must preserve WebSocket upgrades for /api/v1/system/ws and must not buffer compatible API streams. If the proxy passes forwarded headers, configure SERVER.HTTP.PROXY.ENABLE_HEADERS and restrict SERVER.HTTP.PROXY.TRUSTED_NETWORKS to the proxy networks. Continue with Network and TLS and the Hardening checklist.

Complete HTTP inventory

This table covers every OpenAPI operation in the current Core route composition, including authenticated WebUI APIs. It intentionally excludes the separate port-discovery listener and the WebSocket endpoint because neither is an OpenAPI HTTP operation.

Actions and control

Anthropic API surface

Automations

Backup management

Configuration management

Dynamic routing

File explorer

Hardware management

Messaging and platforms

Metrics monitoring

Model Context Protocol

Model management

OpenAI API surface

OpenAI files

Plugin and provider management

Search

Software management

System and monitoring

Task management

WebUI and user management

These additional HTTP operations are present only when SoAI OS is the launched edition. They are unavailable in a Core installation. Use the SoAI OS WebUI pages and runbooks for host changes; several operations are destructive or depend on host capabilities.

SoAI OS host management

Related documentation

• Authentication and API keys
• OpenAI-compatible Responses API
• Models catalog
• MCP overview
• How SoAI works
• Administration overview
• Troubleshooting
• Glossary