---
title: Create a request batch
description: Durably accept up to 100 independent request definitions with batch-level and optional item-level idempotency.
---

The batch endpoint accepts multiple advanced request definitions in one API call. Every resulting request has its own ID, lifecycle, retries, and attempt history.

```http
POST https://api.stormedo.com/requests/batch
Content-Type: application/json
```

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `Authorization: Bearer <token>` | Yes | Project API key. |
| `Idempotency-Key` | Yes | Stable key for the complete batch, containing 1 to 255 bytes. |

## Example

```bash
curl --request POST \
  'https://api.stormedo.com/requests/batch' \
  --header "Authorization: Bearer $STORMEDO_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: daily-order-batch-2026-08-28' \
  --data '{
    "requests": [
      {
        "url": "https://your-app.example/webhooks/orders",
        "body": {
          "type": "order.created",
          "order_id": "ord_123"
        }
      },
      {
        "url": "https://your-app.example/webhooks/inventory",
        "body": {
          "type": "inventory.sync",
          "warehouse_id": "wh_7"
        },
        "delay": "1h"
      }
    ]
  }'
```

`requests` must contain between 1 and 100 items. Each item accepts the fields from [Create an advanced request](/docs/api-reference/requests/) plus an optional `idempotency_key`.

## Idempotency behavior

The header key protects the complete batch. Retrying the same batch with the same key for 24 hours returns the same ordered request IDs. Changing the batch while reusing the key returns `409 Conflict`.

Item keys are optional. They provide request-level deduplication across batch and single-request creation for the same project. Item keys must be unique within the batch.

## Acceptance behavior

Stormedo validates the entire batch before accepting any item. Invalid input returns `422` without accepting a partial batch.

The workspace must also have enough remaining monthly allowance for every new request in the batch. Otherwise, the complete call returns `429`.

## Response

Stormedo returns `202 Accepted` only after the complete batch is durably accepted:

```json
{
  "success": true,
  "data": {
    "requests": [
      {
        "id": "req_33uZSQsVaf8aZjDuzkuAq",
        "project_id": "prj_2Z5mQe7cB9kP4sV8xH1nD",
        "replayed_from_request_id": null,
        "status": "queued",
        "scheduled_at": null,
        "created_at": "2026-08-28T10:15:30Z"
      },
      {
        "id": "req_45vATRtWbg9bAkEv0lvBr",
        "project_id": "prj_2Z5mQe7cB9kP4sV8xH1nD",
        "replayed_from_request_id": null,
        "status": "scheduled",
        "scheduled_at": "2026-08-28T11:15:30Z",
        "created_at": "2026-08-28T10:15:30Z"
      }
    ]
  },
  "error": null,
  "meta": null,
  "request_id": "95c07a5c-3d44-4b89-84a6-c5a71313bff2"
}
```

The response order matches the submitted item order.

## Limits and errors

- Each serialized destination body may contain up to 256 KiB.
- The complete batch HTTP body may contain up to 32 MiB.
- `409` indicates a batch-level or item-level idempotency conflict.
- `413` indicates that the complete HTTP body exceeds 32 MiB.
- `422` indicates an invalid batch or request definition.
- `429` indicates insufficient monthly request allowance.
- `502` or `503` indicates that durable batch acceptance was unavailable.