Impression API Reference

Impression now exposes one canonical streamed AI endpoint:

POST /api/ai/stream

This route replaces the old split /api/chat and /api/generate streaming APIs. It accepts the shared AiStreamRequest contract and returns Server-Sent Events where each data: frame is a typed AiRunEvent.

Authentication

You can authenticate in either of these ways:

• Authorization: Bearer <token> for user/session-backed requests
• X-Space-API-Key: <space_api_key> for server-to-server requests

When using X-Space-API-Key, the request body must include context.spaceId, and any context.brandId must belong to that space.

Request Contract

The request body is JSON and follows the canonical AiStreamRequest shape:

{
  "mode": "visible_chat",
  "agentId": "hudsonAgent",
  "threadId": "thread_123",
  "input": {
    "message": "Help me tighten this draft.",
    "uiSurface": "chat"
  },
  "context": {
    "spaceId": "space_123",
    "brandId": "brand_123",
    "requestedTargets": [
      {
        "target": "chat_only",
        "applyMode": "none"
      }
    ],
    "allowedMutationScope": "none",
    "createThreadIfMissing": false,
    "threadVisibility": "visible"
  }
}

Top-level fields

• runId optional: reuse an existing run id when reconnecting
• afterSequence optional: resume after the last event sequence you processed
• mode: visible_chat or hidden_action
• agentId: canonical product callers use hudsonAgent
• threadId optional: existing visible thread or hidden thread resume
• input: message, action id, tool response, attachments, and surface metadata
• context: space/brand/post scope, requested targets, mutation scope, and thread semantics

Input fields

• message optional: visible-chat user prompt
• actionId optional: hidden editor action preset such as a generate or rewrite action
• toolResponse optional: structured response to a question/choice tool
• uiSurface: chat or editor_button
• attachments optional: normalized file references for visible chat

Context fields

• spaceId: required
• brandId: optional but recommended when brand-scoped behavior is required
• postId optional: current post context
• requestedTargets: one or more explicit targets such as chat_only, post_node, post_selection, create_post, or open_post
• defaultTarget optional
• selectionSnapshot optional
• allowedMutationScope: none, selection_only, node_only, post_only, or post_or_create
• createThreadIfMissing: whether the run may create a thread
• threadVisibility: visible or hidden

Streaming Response

The response is SSE:

Content-Type: text/event-stream

Each frame contains a typed AiRunEvent. Common event types include:

• run.started
• assistant.delta
• assistant.completed
• tool.started
• tool.completed
• tool.failed
• editor.delta
• editor.completed
• artifact.ready
• run.failed
• run.completed

Every event includes runId, sequence, and timestamp.

Resume / Reconnect

To resume a dropped stream:

1. Keep the x-ai-run-id response header from the original request.
2. Keep the highest sequence you processed.
3. Reissue POST /api/ai/stream with:
   • runId
   • afterSequence
   • the same canonical request context

The server replays persisted events from ai_run_events and then continues live delivery.

Current Constraints

• JSON request bodies are supported
• Multipart voice uploads are not supported on the canonical route yet
• Product-visible streamed entry flows are Hudson-first
• Hidden editor actions should use mode: "hidden_action"

Error Handling

Errors return JSON when the request cannot be accepted before streaming starts, for example:

{
  "error": "Invalid AI stream request body"
}

Once streaming has started, terminal failures arrive as a run.failed SSE event.

Examples

See API Usage Examples for curl, JavaScript, and Python examples for visible chat, hidden actions, and resume flows.