> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stora.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests

> Request formats, idempotency, and rate limiting for the Stora Public API.

## Request formats

The API supports only **JSON** requests. You must specify the format using the `Content-Type` header.

```bash theme={null}
curl -X POST "https://public-api.stora.co/2025-09/contacts" \
 -H 'accept: application/json' \
 -H 'content-type: application/json' \
 -H 'authorization: Bearer ACCESS_TOKEN' \
 -d '{"full_name": "John Doe"}'
```

## Idempotent requests

The API supports [idempotency](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent) for any `POST` request.

To make an idempotent `POST` request, provide an additional `Idempotency-Key: <key>` header. The key should be a unique value — a generated [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) is a good choice.

```bash theme={null}
curl -X POST "https://public-api.stora.co/2025-09/contacts" \
 -H 'accept: application/json' \
 -H 'content-type: application/json' \
 -H 'authorization: Bearer ACCESS_TOKEN' \
 -H 'idempotency-key: UNIQUE_KEY' \
 -d '{"full_name": "John Doe"}'
```

### How it works

When you make a request with a new idempotency key, the API stores the response status code and body, whether the request succeeds or fails, for 24 hours.

If you send additional requests with the same key within that period, the API will return the exact same response, including any `400` or `500` errors.

After 24 hours, the stored response is invalidated, and the next request with that key will be processed and stored as if it were new.

## Rate limiting

The API uses rate limiting to ensure fair usage and maintain performance.

The default rate limit is:

* **10 requests per second**
* **60 requests per minute**

These limits may vary based on your subscription plan or specific agreements with Stora.

### Handling rate limits

If you exceed the rate limit, the API responds with a `429 Too Many Requests` status code. The response includes headers with your current rate limit status:

| Header            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `RateLimit-Limit` | The maximum number of requests allowed in the current time window           |
| `RateLimit-Reset` | The time at which the current rate limit window resets in UTC epoch seconds |