OpenAI-compatible Responses API

SoAI exposes the OpenAI-compatible Responses API at /v1/responses. Use it when a client needs a response object, background work, stored input items, token counting, or compaction. The selected model must support the Responses endpoint.

Prepare and send a response

Open Models, then select Edit model for the model you plan to use. The Capabilities section lists Responses only when the selected model's capability profile supports it. Its Response features section lists the supported feature profile for create, retrieval, deletion, cancellation, input items, and input-token counting. You can disable a supported capability or reset an override; you cannot add a capability that the plugin does not expose. Saving an override requires Model administration (MODEL_ADMIN). Select Save in the dialog after changing an override.

If the instance uses API keys, an administrator with API key management (OPENAI_API_ADMIN) selects the Settings button at the right of the header, then selects Settings and OpenAI before configuring a client. See Authentication and API keys and Models catalog.

Create a response

export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'

curl https://your-soai.example/v1/responses \
  -H "Authorization: Bearer $SOAI_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "input": "Summarize this workspace report."
  }'

store defaults to true. Set background to true for work that the client will retrieve later; background requests require store: true. A stored response is scoped to the API key or signed-in user that created it. Without either context, SoAI uses an anonymous-owner token; retain the returned X-SoAI-Anon-Token header or cookie to retrieve that response.

Manage the response lifecycle

Method Endpoint Use
POST /v1/responses Create a response. Use stream: true for an OpenAI-format stream.
GET /v1/responses/{response_id} Retrieve a response owned by the same API key, signed-in user, or anonymous-owner-token context.
DELETE /v1/responses/{response_id} Delete a stored response. SoAI first cancels an active task and deletes the record only after that task reaches a terminal state.
POST /v1/responses/{response_id}/cancel Request cancellation for a stored background response. Foreground responses cannot use this endpoint.
GET /v1/responses/{response_id}/input_items List the effective input items with pagination.
POST /v1/responses/input_tokens Count the model-aware input-token occupancy before creating a response.
POST /v1/responses/compact Create a compaction response that a later Responses request can include in its input.

Background streaming and cancellation

A client can retrieve a stored background response with stream=true only when the original background request also enabled streaming. Use the cancellation endpoint only for stored background responses. The first cancellation result can report cancelling while the task finishes its cleanup; retrieve the response again to read its final status.

Administrator settings

An administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, then Settings. Select Advanced in the Settings page header. The page becomes Advanced settings and the control changes to Basic. Edit the required setting and select Save. SoAI monitors a background Responses task for the duration set by API.OPENAI.RESPONSES.BACKGROUND_MONITOR_MAX_SEC. Stored streaming events use SERVER.HTTP.STREAMING.RESPONSES_PERSIST_FLUSH_INTERVAL_MS, SERVER.HTTP.STREAMING.RESPONSES_PERSIST_MAX_EVENTS_PER_FLUSH, and SERVER.HTTP.STREAMING.RESPONSES_PERSIST_MAX_PENDING_EVENTS.

Related documentation