API overview

The Stormedo HTTP API accepts outbound delivery work, returns a durable request ID, and exposes the resulting lifecycle and attempt history.

Download the public OpenAPI schema for tools and generated clients. It describes project-key request and schedule operations and the public signing-key endpoint. Dashboard session APIs are outside this public contract.

Base URL

Plain text

https://api.stormedo.com

All public endpoints use HTTPS. JSON responses use the Stormedo response envelope, except for the public JWKS response and requests rejected before route handling. Successful deletion returns 204 No Content without a body.

Authentication

Send a project API key as a bearer token:

HTTP

Authorization: Bearer $STORMEDO_TOKEN

Keep the key in server-side configuration. The project API key authenticates with Stormedo and is never forwarded to the destination. To send an Authorization header through the quick-send endpoint, use X-Forward-Authorization.

Choose a request endpoint

Use case	Endpoint	Reference
Forward a raw body with a small set of delivery controls	POST /send	Send a request
Submit a structured JSON request with metadata or advanced retry settings	POST /requests	Create an advanced request
Submit up to 100 structured requests together	POST /requests/batch	Create a request batch
Inspect request state and completed attempts	GET /requests and GET /requests/{request_id}	Read requests and attempts
Stop active work or repeat completed work	Request cancel and replay endpoints	Cancel and replay requests
Create and manage recurring delivery schedules	/schedules endpoints	Recurring schedules API

For application code, the JavaScript SDK and Python SDK provide typed interfaces over these endpoints.

Basic request flow

1. Submit work with /send, /requests, or /requests/batch.
2. Store the data.id value from the 202 Accepted response.
3. Inspect the request in the dashboard or through GET /requests/{request_id}.
4. Use completed attempts to understand destination responses and retry decisions.

202 Accepted confirms that Stormedo accepted the request for delivery. It does not mean the destination has completed the request.

Compatibility

Public endpoints currently use unversioned paths. This reference follows the current backend contract; the downloadable OpenAPI is generated from backend package 0.1.0. The SDK examples identify their checked release candidates where relevant. Package versions and the API schema version are separate; do not add an undocumented /v1 prefix or infer a compatibility promise from the package number.

Responses and errors

Successful and failed JSON responses use a common envelope. Resource IDs, lifecycle fields, pagination, redaction behavior, and stable error codes are documented in API objects and errors.

The top-level request_id identifies the API call. Include it when contacting Stormedo support. A resource ID such as req_... or sch_... appears inside data.

Shared behavior

• Request and schedule resources are scoped to the project selected by the bearer API key.
• Each delivery body may contain up to 256 KiB. Endpoint-specific submission limits are documented on each endpoint page.
• Accepted work can take a short time to appear in read responses while its query projection catches up.
• Delivery is at least once. A receiver must safely handle the same request more than once.

Destination request contract

The destination must use HTTPS, resolve to public addresses, and contain no URL credentials or fragment. URLs are limited to 2048 bytes. Redirects are disabled: use the final destination URL. A private IP or hostname that resolves to a private network is rejected. GET, POST, PUT, PATCH, and DELETE are supported for requests; recurring schedules use POST.

Stormedo sets Stormedo-Request-Id and Stormedo-Signature on each attempt. The stable request ID is the same across retries; the short-lived signature is generated for each attempt. See Delivery verification.

The following destination header names are reserved, case-insensitively:

Plain text

connection, content-length, content-type, host, keep-alive,
proxy-authenticate, proxy-authorization, te, trailer,
transfer-encoding, upgrade, stormedo-request-id, stormedo-signature

Set content type through the quick-send Content-Type header or the raw SDK contentType / content_type option. Structured JSON bodies use application/json. Up to 64 destination headers and 32 KiB of combined names and values are allowed. Other publisher headers are not forwarded automatically.

Queue names label requests. They do not promise FIFO order, rate limiting, or constrained concurrency. Metadata is available for inspection and is never sent to the destination.

Unknown outcomes

A 202 confirms durable acceptance. A server error or interrupted connection can leave acceptance unknown. Follow submission recovery with the original key and unchanged input. Delivery retries and publisher retries are separate: retry settings cannot recover a missing API response.