SN-API REST gateway reference

SN-API is the REST gateway in front of SuperNodes. It handles Cascade file uploads and downloads over plain HTTPS. The JavaScript SDK and the Rust SDK route all file transfers through it. The Go SDK skips the gateway and talks gRPC directly to SuperNodes on port 4444. Call SN-API directly when you build in a language without an official SDK or need full control over the HTTP layer. Register the action on chain first. The gateway only moves bytes for actions that already exist.

Base URLs

Network	Base URL
Mainnet	`https://snapi.lumera.io`
Testnet	`https://snapi.testnet.lumera.io`

The JavaScript SDK picks the endpoint from its preset configuration. The Rust SDK reads it from the SNAPI_BASE environment variable.

Authentication

Uploads and private downloads require an ADR-036 signature. ADR-036 is the Cosmos standard for signing arbitrary data off chain. The SDKs produce these signatures for you. When calling the API directly, follow two steps.

Sign the relevant data with ADR-036 signArbitrary. Uploads sign the data hash. Downloads sign the action ID.
Include the Base64 encoded signature in the request body.

POST /api/v1/actions/cascade

Starts a Cascade upload. Send the file as multipart/form-data after the on-chain registration.

Form fields

string

required

Action ID returned by the on-chain registration transaction.

string

required

Base64 encoded ADR-036 auth signature.

binary

required

The file data.

Example response

{
  "task_id": "uuid-task-id"
}

string

Upload task identifier. Use it with the task endpoints below.

Status codes

Code	Meaning
202	Accepted. The upload task was created and the response carries the `task_id`.
400	Invalid request. Missing fields or bad signature.
401	Unauthorized
403	Forbidden
404	Action not found. Retry after a short delay.
409	Conflict
500	Server error

SuperNodes need a moment to index a freshly registered action. The SDKs retry this endpoint up to 5 times with 3 second delays. Apply the same retry policy when you call it directly.

GET /api/v1/actions/cascade/tasks/{task_id}

Returns the stored request metadata for an upload task. This endpoint describes what was requested, not how far it has progressed. For task state use the status stream or the history endpoint below.

Path parameters

string

required

Task ID returned by the upload endpoint.

Example response

{
  "task_id": "uuid",
  "action_id": "232794",
  "file_name": "example.png",
  "file_path": "/data/uploads/example.png",
  "file_size_kbs": 11,
  "signature": "base64-encoded ADR-036 signature",
  "created_at": "2026-01-01T00:00:00Z"
}

Response fields

string

Upload task identifier.

string

The on-chain action this upload belongs to.

string

Name of the uploaded file.

string

Path the SuperNode stored the incoming file at.

integer

File size in kilobytes.

string

The ADR-036 signature submitted with the upload.

string

RFC 3339 timestamp of task creation.

GET /api/v1/actions/cascade/tasks/{task_id}/status

Streams progress updates for an upload task as Server-Sent Events (SSE), a one-way HTTP stream of messages. Send Accept: text/event-stream.

string

required

Task ID returned by the upload endpoint.

Each event carries a JSON payload on a data: line with the fields id, task_id, status, data, and created_at.

GET /api/v1/actions/cascade/tasks/{task_id}/history

Returns the status history for an upload task as JSON. Use this when you want to poll rather than hold a stream open.

string

required

Task ID returned by the upload endpoint.

POST /api/v1/actions/cascade/{action_id}/downloads

Requests a download task for a stored file. Private files need an ADR-036 signature. Files stored with isPublic: true can be requested without one.

Path parameters

string

required

The on-chain action ID of the stored file.

Query parameters

boolean

Set to true for a file that was stored with isPublic: true. The signature then becomes optional.

Request body

string

Base64 encoded ADR-036 signature of the action ID. Required unless you pass public=true.

Example request for a private file

{
  "signature": "base64-encoded ADR-036 signature of the action_id"
}

Example request for a public file

curl -X POST "https://snapi.lumera.io/api/v1/actions/cascade/{action_id}/downloads?public=true"

Requesting a private file without a signature returns 400 with the message signature is required.

Example response

{
  "task_id": "uuid-download-task-id"
}

string

Download task identifier. Use it with the status and file endpoints below.

Status codes

Code	Meaning
202	Accepted. The download task was created and the response carries the `task_id`.
400	Invalid request
404	Action not found
500	Server error

As with the upload endpoint, this creates a task and returns 202 Accepted. The file itself comes from the file endpoint below.

GET /api/v1/downloads/cascade/{task_id}/status

Streams progress updates as Server-Sent Events (SSE), a one-way HTTP stream of messages. Send Accept: text/event-stream.

string

required

Download task ID returned by the download request endpoint.

Each event carries the same fields as a history entry, so id, task_id, status, data, and created_at. There is no percentage field. Progress is expressed as a sequence of named states, and data carries any detail that state has.

Example stream

data: {"id":1,"task_id":"7ca7b6c9","status":"sdk:started","data":{},"created_at":"2026-01-01T00:00:00Z"}

data: {"id":2,"task_id":"7ca7b6c9","status":"sdk:supernodes_found","data":{"count":7,"total":10},"created_at":"2026-01-01T00:00:03Z"}

data: {"id":3,"task_id":"7ca7b6c9","status":"sdk:completed","data":{},"created_at":"2026-01-01T00:00:41Z"}

States are namespaced by who reported them. sdk: states come from the gateway’s client, and supernode: states come from the SuperNode serving the request. The terminal states are sdk:completed and sdk:failed. In browsers, consume the stream with EventSource.

const es = new EventSource(
  `https://snapi.testnet.lumera.io/api/v1/downloads/cascade/${taskId}/status`
);

es.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(update.status, update.data);

  if (update.status === "sdk:completed" || update.status === "sdk:failed") {
    es.close();
  }
};

To poll for status as JSON instead of holding this stream open, use the history endpoint below.

GET /api/v1/downloads/cascade/{task_id}/history

Returns the status history for a download task as JSON. This is the polling counterpart to the stream above.

string

required

Download task ID returned by the download request endpoint.

GET /api/v1/downloads/cascade/{task_id}/file

Streams the file bytes once the download task completes. The response arrives with Content-Type: application/octet-stream.

string

required

Download task ID returned by the download request endpoint.

Consume the response as a ReadableStream to keep memory use flat on large files.

Version fallback

The SDKs try versioned paths first (/api/v1/...) and fall back to legacy paths (/api/...) on a 404. This keeps them compatible across SN-API versions. Prefer the /api/v1/ prefix when calling the API directly.

Errors

Error bodies carry a message and a machine readable code.

{
  "error": "action not found",
  "code": "NOT_FOUND"
}

Code	Cause
`NOT_FOUND`	The action does not exist or is not indexed yet
`UNAUTHORIZED`	The ADR-036 signature is invalid
`SERVICE_UNAVAILABLE`	No SuperNode is available to serve the request

Rate limits

The public SN-API endpoints may rate limit during high traffic. For high throughput production workloads, run your own SuperNode. The SuperNode overview explains the requirements.

Next steps

Upload lifecycle

What happens between registration and DONE.

Download lifecycle

How SuperNodes reassemble your file from symbols.

Error handling

Retry strategies for uploads and downloads.

REST API

RPC

gRPC API

Libraries and tools

SN-API REST gateway reference

Base URLs

Authentication

POST /api/v1/actions/cascade

Form fields

Example response

Status codes

GET /api/v1/actions/cascade/tasks/{task_id}

Path parameters

Example response

Response fields

GET /api/v1/actions/cascade/tasks/{task_id}/status

GET /api/v1/actions/cascade/tasks/{task_id}/history

POST /api/v1/actions/cascade/{action_id}/downloads

Path parameters

Query parameters

Request body

Example request for a private file

Example request for a public file

Example response

Status codes

GET /api/v1/downloads/cascade/{task_id}/status

Example stream

GET /api/v1/downloads/cascade/{task_id}/history

GET /api/v1/downloads/cascade/{task_id}/file

Version fallback

Errors

Rate limits

Next steps

Upload lifecycle

Download lifecycle

Error handling

​Base URLs

​Authentication

​POST /api/v1/actions/cascade

​Form fields

​Example response

​Status codes

​GET /api/v1/actions/cascade/tasks/{task_id}

​Path parameters

​Example response

​Response fields

​GET /api/v1/actions/cascade/tasks/{task_id}/status

​GET /api/v1/actions/cascade/tasks/{task_id}/history

​POST /api/v1/actions/cascade/{action_id}/downloads

​Path parameters

​Query parameters

​Request body

​Example request for a private file

​Example request for a public file

​Example response

​Status codes

​GET /api/v1/downloads/cascade/{task_id}/status

​Example stream

​GET /api/v1/downloads/cascade/{task_id}/history

​GET /api/v1/downloads/cascade/{task_id}/file

​Version fallback

​Errors

​Rate limits

​Next steps

Upload lifecycle

Download lifecycle

Error handling

Base URLs

Authentication

POST /api/v1/actions/cascade

Form fields

Example response

Status codes

GET /api/v1/actions/cascade/tasks/{task_id}

Path parameters

Example response

Response fields

GET /api/v1/actions/cascade/tasks/{task_id}/status

GET /api/v1/actions/cascade/tasks/{task_id}/history

POST /api/v1/actions/cascade/{action_id}/downloads

Path parameters

Query parameters

Request body

Example request for a private file

Example request for a public file

Example response

Status codes

GET /api/v1/downloads/cascade/{task_id}/status

Example stream

GET /api/v1/downloads/cascade/{task_id}/history

GET /api/v1/downloads/cascade/{task_id}/file

Version fallback

Errors

Rate limits

Next steps