Skip to main content

POST /v1/respond

POST 
/v1/respond

Generate a personality-modulated response to a user message. SPEC-13 §7.1. Supports stateless and stateful modes. With "return_format":"modulator_pack" uniqOS returns the prompt-building pack and does NOT call the LLM (the client does). "stream":true with modulator_pack returns 422. "llm_override" returns 501 until BYOLLM is shipped. A turn that exceeds the engine budget returns 504 turn_timeout and is NOT billed (ADR-0009).

Streaming (stream: true, text return_format only): the response is text/event-stream. Each SSE frame is event: <name> + data: <json>, where <name> is one of metadata | text | guardrail_modulation | completion | error and <json> matches the correspondingly-named StreamEvent* schema in components.schemas (with the type key supplied by the event: line). The full set is modeled as the RespondStreamEvent discriminated union. stream: true with return_format: modulator_pack returns 422.

Request​

Responses​

Default Response

Response Headers
    X-Request-Id

    ULID stamped on every response and propagated through error envelopes. Use it when filing support tickets — it identifies the exact request in the structured logs (requestId field).

    X-RateLimit-Limit

    Requests-per-second ceiling for the current bucket (per-organization for authenticated calls, per-IP for public ones).

    X-RateLimit-Remaining

    Tokens left in the bucket after this request.

    X-RateLimit-Reset

    ISO-8601 timestamp when the bucket will be fully refilled.