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

# Introduction

> Call Mercora from your own systems: base URL, authentication, scopes, errors and idempotency.

The Mercora API lets your own systems, such as an ERP or an internal script, work with your workspace. It covers two areas:

* **Hedging**: read your hedge books and positions, send hedge requests, and check where they stand.
* **Automations**: start runs of automations set to run from the API, and hand a waiting run what it's waiting for.

Whatever a call creates lands in the Inbox for a person on your team to decide on. A hedge request isn't sent to your broker until someone sends it from the Inbox, and anything an automation run would change waits for a person. This page covers what every call has in common; the endpoint pages list every field and response.

> [!NOTE]
>
> You need a workspace API key with the right scope. A workspace admin creates one under **Settings → API**. See [API keys](https://docs.mercora.io/admin/api-keys.md).

## Base URL and authentication

```
https://{workspace}.mercora.io/api/v1
```

Replace `{workspace}` with your workspace's subdomain; the exact base URL is under **Settings → API → Connection**. Requests and responses use JSON.

Send the key as a Bearer token on every request:

```bash theme={"system"}
curl https://{workspace}.mercora.io/api/v1/hedge-books \
  -H "Authorization: Bearer mk_your_api_key"
```

The key alone decides which workspace you're calling; you never send a workspace ID.

> [!WARNING]
>
> Call the API from your servers, never from a browser or mobile app. Anyone with a key can call Mercora as your workspace, within its scopes.

## Scopes

Each endpoint needs one scope. A key without it gets a `403`.

| Scope | Endpoints |
| - | - |
| `hedge_requests` | `GET /hedge-books`, `POST /hedge-requests`, `GET /hedge-requests/{id}` |
| `automations` | `POST /agents/{id}/run`, `POST /agents/{id}/runs/{runId}/callback` |

`POST /hedge-requests` also needs the **Hedging** module, and both automation endpoints need the **Automations** module. While the module is off, those calls return `403`. See [Modules](https://docs.mercora.io/concepts/modules.md).

## Errors

Request bodies have a fixed schema: unknown fields are refused, so a misspelled field fails with a `422` instead of being ignored. Errors always come back as JSON with an `error` message; a `422` also lists each problem in `issues`:

```json theme={"system"}
{
  "error": "Invalid hedge request.",
  "issues": [
    { "field": "book", "message": "Required" }
  ]
}
```

`field` is the path to the field that failed, or `null` when the problem isn't tied to one field.

| Status | Meaning |
| - | - |
| `200` | Success, or a repeated create: see [Idempotency](#idempotency). |
| `201` | Created. |
| `202` | An automation run's callback was received and the run carries on. |
| `400` | The body isn't valid JSON. |
| `401` | The API key is missing, malformed, unknown or revoked. |
| `403` | The key lacks the endpoint's scope, or the module it needs is off. |
| `404` | No such object in your workspace. |
| `409` | Usually an `external_id` reused with a different body. For automations, also an automation not set to run from the API, or a run that isn't waiting for a callback. |
| `422` | The body failed validation. See `issues`. |
| `429` | Automations only: your workspace's daily automation-run budget is used up. It resets at midnight UTC. |
| `500` | Something went wrong on Mercora's side. It's safe to retry with the same `external_id`. |

## Idempotency

`POST /hedge-requests` and `POST /agents/{id}/run` take your own `external_id`: any string up to 200 characters that identifies the request in your system, such as a purchase order number.

* Same `external_id`, same body: Mercora returns what it created the first time, with `200` instead of `201`. If you lose a response, for example on a timeout, just send the request again.
* Same `external_id`, different body: `409`. Use a new `external_id` for a new request.

Mercora issues an `id` for every object it creates; read objects back by it, for example `GET /hedge-requests/{id}`. If you lose a hedge request's `id`, resend the original `POST` with the same `external_id` to get it back.

## OpenAPI

The endpoint pages are generated from Mercora's OpenAPI 3.1 document. A workspace admin can also open the interactive reference (**Swagger UI**) and download **openapi.json** from **Settings → API**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.