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 |
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 |
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.