---
title: Create an advanced request
description: Create a durable request with structured destination headers, JSON body, metadata, timing, timeout, and retry configuration.
---

Use the advanced endpoint when the request definition is easier to express as structured JSON.

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

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `Authorization: Bearer <token>` | Yes | Project API key. It is never sent to the destination. |
| `Idempotency-Key` | No | Stable project-scoped key containing 1 to 255 bytes. Retained for 24 hours. |

## JSON body

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | string | Yes | None | Public HTTPS destination, up to 2048 bytes. |
| `method` | string | No | `POST` | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. |
| `headers` | object | No | `{}` | Destination headers sent directly without an `X-Forward-` prefix. |
| `body` | any JSON value | No | No body | Serialized as JSON and delivered with `Content-Type: application/json`. |
| `delay` | string | No | Immediate | Relative delay from `1s` through `30d`. Use an integer followed by `s`, `m`, `h`, or `d`. |
| `deliver_at` | RFC 3339 string | No | Immediate | Absolute time within 30 days of the current time. Cannot be combined with `delay`. |
| `timeout` | string | No | `50s` | Per-attempt timeout from `1s` through `5m`, using whole seconds or minutes. |
| `retry.max_attempts` | integer | No | `3` | Total attempts including the first, from `1` through `20`. |
| `retry.backoff` | string | No | `exponential` | Currently only `exponential` is accepted. |
| `queue` | string | No | `default` | Queue label containing 1 to 64 allowed characters. |
| `metadata` | object | No | `{}` | String values stored for inspection and never forwarded. |

Unknown fields are rejected.

A valid `deliver_at` timestamp that is already in the past starts delivery immediately.

## Example

```bash
curl --request POST \
  'https://api.stormedo.com/requests' \
  --header "Authorization: Bearer $STORMEDO_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-123-created' \
  --data '{
    "url": "https://your-app.example/webhooks/orders",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer destination-token"
    },
    "body": {
      "type": "order.created",
      "order_id": "ord_123"
    },
    "retry": {
      "max_attempts": 4,
      "backoff": "exponential"
    },
    "timeout": "45s",
    "metadata": {
      "order_id": "ord_123"
    }
  }'
```

## Limits

- The serialized destination body may contain up to 256 KiB.
- The complete structured API request may contain up to 512 KiB.
- Destination headers are limited to 64 entries and 32 KiB combined.
- Metadata is limited to 32 entries, 64-byte keys, 1024-byte values, and 16 KiB combined.
- Metadata keys and queue names accept letters, numbers, dots, hyphens, and underscores.

Destination header values are stored securely and returned as `[REDACTED]` by read APIs. Request bodies are never returned by the API.

## Response

The endpoint returns the same `202 Accepted` object as [quick send](/docs/api-reference/send/). `retry.max_attempts` counts total attempts, unlike the quick-send `retry` query parameter, which counts additional retries.

## Errors

| Status | When it occurs |
| --- | --- |
| `401` | The project API key is missing or invalid. |
| `409` | The idempotency key was reused with different input. |
| `413` | The complete structured API request exceeds 512 KiB. |
| `422` | A field, destination header, timing value, body, or metadata entry is invalid. |
| `429` | The workspace monthly request allowance has been reached. |
| `502` or `503` | Stormedo could not durably accept the request. |