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

Every endpoint requires 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 to poll the task endpoints below.

Status codes

Code	Meaning
200	Upload started
400	Invalid request. Missing fields or bad signature.
404	Action not found. Retry after a short delay.
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 full details for an upload task.

Path parameters

string

required

Task ID returned by the upload endpoint.

Example response

{
  "task_id": "uuid",
  "status": "processing",
  "progress": 45,
  "created_at": "2024-01-01T00:00:00Z"
}

Response fields

string

Upload task identifier.

string

Current task state, for example processing.

integer

Completion percentage from 0 to 100.

string

RFC 3339 timestamp of task creation.

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

Returns a simplified status body for the same task. Use it in tight polling loops where the full task detail is not needed.

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. The body is JSON.

Path parameters

string

required

The on-chain action ID of the stored file.

Request body

string

required

Base64 encoded ADR-036 signature of the action ID.

Example request

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

Example response

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

string

Download task identifier. Use it with the status and file endpoints 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.

Example stream

data: {"status": "processing", "progress": 0}

data: {"status": "processing", "progress": 50}

data: {"status": "completed", "progress": 100}

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 data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress}%`);
  if (data.status === "completed") {
    es.close();
  }
};

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

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

Path parameters

Request body

Example request

Example response

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

Example stream

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

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

​Path parameters

​Request body

​Example request

​Example response

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

​Example stream

​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

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

Path parameters

Request body

Example request

Example response

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

Example stream

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

Version fallback

Errors

Rate limits

Next steps