Streaming Responses
The session and plan push endpoints (POST /api/v1/sessions and POST /api/v1/plans) return NDJSON (newline-delimited JSON) streams. Each line is a JSON object representing a progress step.
Event format
Each event has a step field indicating the current stage:
{"step":"redacting","detail":"Scanning session records..."}
{"step":"compressing","detail":"Compressing 2.5 MB..."}
{"step":"generating_preview","detail":"Generating preview image..."}
{"step":"storing","detail":"Saving session..."}
{"step":"done","nanoid":"abc123xyz456","url":"https://rockstar.ninja/s/abc123xyz456","version":1,"changed":true}
Steps
| Step | Description |
|---|---|
redacting |
Applying secret redaction patterns (sessions only) |
compressing |
Compressing session data with zstd (sessions only) |
checking |
Checking for content changes (plans only) |
generating_preview |
Creating the OG preview image |
storing |
Writing to the database |
linking_plans |
Creating or updating plans found in the session (sessions only) |
done |
Push complete |
error |
Something went wrong |
Done event
The final done event includes:
| Field | Type | Description |
|---|---|---|
nanoid |
string | The 12-character URL identifier |
url |
string | Full URL to view the content |
version |
int | Version number |
changed |
bool | Whether content was different from previous version |
project_nanoid |
string | Project nanoid (if linked to a project) |
project_label |
string | Project label (if linked to a project) |
plans |
array | Plans created or updated from the session (see below) |
Linked plans
When a session push creates or updates plans (from plan files written during the session), the done event includes a plans array:
| Field | Type | Description |
|---|---|---|
nanoid |
string | Plan URL identifier |
name |
string | Plan filename (e.g. my-plan.md) |
url |
string | Full URL to view the plan |
version |
int | Plan version number |
created |
bool | Whether this plan was newly created (vs. updated) |
Error event
If something goes wrong, you'll receive:
{"step":"error","error":"human-readable error message"}
Content-Type
Streaming responses use Content-Type: application/x-ndjson. The server flushes after each event, so clients can display progress in real time.