---
title: API overview
description: Authenticate with the Stormedo HTTP API, choose the right request endpoint, and understand its response and delivery model.
---

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

## Base URL

```text
https://api.stormedo.com
```

All public endpoints use HTTPS. JSON responses use the Stormedo response envelope, except when a request is 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](/docs/api-reference/send/) |
| Submit a structured JSON request with metadata or advanced retry settings | `POST /requests` | [Create an advanced request](/docs/api-reference/requests/) |
| Submit up to 100 structured requests together | `POST /requests/batch` | [Create a request batch](/docs/api-reference/batches/) |
| Inspect request state and completed attempts | `GET /requests` and `GET /requests/{request_id}` | [Read requests and attempts](/docs/api-reference/request-history/) |
| Stop active work or repeat completed work | Request `cancel` and `replay` endpoints | [Cancel and replay requests](/docs/api-reference/request-actions/) |
| Create and manage recurring delivery schedules | `/schedules` endpoints | [Recurring schedules API](/docs/api-reference/schedules/) |

For application code, the [JavaScript SDK](/docs/sdks/javascript/) and [Python SDK](/docs/sdks/python/) 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.

## 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](/docs/api-reference/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.