Skip to content
cross.stream

Store API

The supervisor exposes a HTTP API for interacting with the store. See 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:

  • follow - Long poll for new frames. Can be true or a heartbeat interval in milliseconds
  • new - Skip existing, only show new frames
  • after - Start after a specific frame ID (exclusive)
  • from - Start from a specific frame ID (inclusive)
  • limit - Maximum number of frames to return
  • last - Return the last N frames (most recent)
  • topic - Filter frames by topic
  • with-timestamp - Include RFC3339 timestamp extracted from frame ID

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
    • head:<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:

  • last - Number of frames to return (default: 1). Returns NDJSON when > 1.
  • follow - Long poll for new frames
  • with-timestamp - Include RFC3339 timestamp extracted from frame ID

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

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