Skip to content
cross.stream

Store API

The supervisor exposes a HTTP API for interacting with the store. 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
  • tail - Begin reading from end of stream
  • last-id - Start reading from specific frame ID
  • limit - Maximum number of frames to return
  • context-id - Filter frames by context ID
  • topic - Filter frames by topic

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

POST /{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/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
  • context - Context ID for the frame

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

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 /head/{topic}

Get most recent frame for topic

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

Query Parameters:

  • follow - Long poll for new frames on this topic
  • context - Context ID to filter by

Response: Most recent frame for topic 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