Skip to content

Request Flow Overview

This page shows what happens after a request reaches your deployed Rafiki Worker. Use the API Usage Guide for exact routes, payloads, and response shapes.

Public Request Lifecycle

sequenceDiagram
    participant Client
    participant Worker as Cloudflare Worker
    participant Session as Session Durable Object
    participant Runtime as Internal Execution Backend

    Client->>Worker: Authenticated public request
    Worker->>Session: Resolve session and route work
    Session->>Runtime: Execute query or job
    Runtime-->>Session: Result or stream events
    Session-->>Worker: Public response envelope
    Worker-->>Client: JSON or WebSocket events

Synchronous Query

Use POST /query when the client can wait for the full answer.

  1. The client calls the Worker with a session token.
  2. The Worker validates auth and resolves the target session.
  3. The session Durable Object forwards execution to the internal backend.
  4. Rafiki returns messages, summary, and session_id in one response.

Streaming Query

Use GET /query_stream when the client needs live execution updates.

  1. The client opens a WebSocket connection to the Worker.
  2. Rafiki acknowledges the connection and binds it to the authenticated session.
  3. The session Durable Object streams execution events back to the client.
  4. The stream ends with query_complete or query_error.

Background Job

Use POST /submit when the work should continue after the request returns.

  1. The client submits a job through the Worker.
  2. Rafiki returns a job_id immediately.
  3. Internal execution continues in the background.
  4. The client checks status with GET /jobs/{job_id} and downloads artifacts from the corresponding Worker routes.

Choose The Right Pattern

Scenario Route Best for
quick request/response POST /query server actions, simple forms, API calls
real-time assistant UX GET /query_stream chat and live streaming interfaces
follow-up state or history /session/{session_id}/... queue, messages, state, stop
offline or long-running work POST /submit reports, analyses, batch jobs

Public vs Internal Detail

The public API stops at the Worker routes. Internal gateway URLs, sandbox lifecycle, rollout mechanics, and backend auth stay behind the Worker.