Skip to content
cross.stream

Store API

The supervisor exposes a HTTP API for interacting with the store. See Topics for naming rules and wildcards. By default, it listens on a Unix domain socket at ./store/sock.

Endpoints

GET /

Cat the stream

Terminal window
# Cat all frames
curl --unix-socket ./store/sock http://localhost/


# Long poll for new frames
curl --unix-socket ./store/sock -H "Accept: text/event-stream" \
    "http://localhost/?follow=true"

Query parameters are the read options: follow, new, after, from, limit, last, topic, and with-timestamp. A follow value may be true or a heartbeat interval in milliseconds.

Response: newline-delimited JSON frames or SSE stream, based on Accept header. Use "Accept: text/event-stream" for SSE.

POST /append/{topic}

Append frame to topic

Terminal window
curl --unix-socket ./store/sock \
    -H "xs-meta: $(echo -n '{\"key\":\"value\"}' | base64)" \
    -X POST --data "content" \
    "http://localhost/append/topic?ttl=forever"

Query Parameters:

  • ttl - Time-to-live for frame:
    • forever - Never expire
    • ephemeral - Not stored; only active subscribers receive it
    • time:<ms> - Expire after duration
    • last:<n> - Keep only N most recent frames
  • with-timestamp - Include RFC3339 timestamp extracted from frame ID

Headers:

  • xs-meta - Optional Base64-encoded JSON metadata. Must be encoded using standard Base64 to support Unicode characters.

Response: Frame JSON

GET /{id}

Get frame by id

Terminal window
curl --unix-socket ./store/sock http://localhost/03BCPN2DNQ529QRQKBQCZ4JV4

Query Parameters:

  • with-timestamp - Include RFC3339 timestamp extracted from frame ID

Response: Frame JSON or 404 if not found

DELETE /{id}

Remove frame

Terminal window
curl --unix-socket ./store/sock -X DELETE \
    http://localhost/03BCPN2DNQ529QRQKBQCZ4JV4

Response: 204 on success

GET /last[/{topic}]

Get most recent frame(s), optionally filtered by topic.

Terminal window
curl --unix-socket ./store/sock http://localhost/last/topic
curl --unix-socket ./store/sock http://localhost/last
curl --unix-socket ./store/sock "http://localhost/last/topic?last=5"

Query parameters are the read options last (default: 1; returns NDJSON when > 1), follow, and with-timestamp.

Response: Most recent frame(s) as JSON (single) or NDJSON (multiple/follow), or 404 if not found

POST /cas

Store content in CAS

Terminal window
curl --unix-socket ./store/sock \
    -X POST --data "content" http://localhost/cas

Response: Content hash

GET /cas/{hash}

Get content from CAS

Terminal window
curl --unix-socket ./store/sock http://localhost/cas/sha256-hash

Response: Raw content or 404 if not found

POST /import

Import frame as-is

Terminal window
curl --unix-socket ./store/sock \
    -H "Content-Type: application/json" \
    -X POST --data '{"topic":"test","id":"03BCPN2DNQ529QRQKBQCZ4JV4"}' \
    http://localhost/import

Response: Imported frame JSON

POST /eval

Evaluate a Nushell script against the store. The request body is the script (UTF-8). The script runs with the store commands available (.cat, .last, .append, plus the core commands), so it can read from and write to the stream.

Terminal window
curl --unix-socket ./store/sock \
    -X POST --data '.cat | where topic == "notes" | length' \
    http://localhost/eval

Response: depends on the type the pipeline returns:

  • single string/int/float/bool - text/plain
  • any other single value (record, etc.) - application/json
  • a list stream - application/x-ndjson (one JSON value per line, streamed)
  • a byte stream - application/octet-stream (streamed)
  • nothing - 204 No Content

A script that fails to evaluate returns 500 with the error text.

GET /version

Get version info

Terminal window
curl --unix-socket ./store/sock http://localhost/version

Response: Version information JSON

Status Codes

  • 200 - Success
  • 204 - Success (no content)
  • 400 - Bad request
  • 404 - Not found
  • 500 - Internal server error