> ## 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 with a workspace API key: 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 Mercora workspace. Today it covers two areas:

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

This page covers what every call has in common. The endpoint pages in this section list every field and response.

> [!NOTE]
>
> **Before you start:** you need a workspace API key with the right scope. Ask a workspace admin to create one under **Settings → API**, one key per calling system. See [API keys](https://docs.mercora.io/admin/api-keys.md).

> [!NOTE]
>
> The API follows the same rule as the rest of Mercora: whatever a call creates lands in the Inbox for a person on your team to decide on. A hedge request sent through the API isn't sent to your broker until someone sends it from the Inbox, and anything an automation run would change waits for a person.

## Base URL

Each workspace has its own address. Your API base URL is:

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

Replace `{workspace}` with your workspace's subdomain. A workspace admin can see the exact base URL under **Settings → API**, in the **Connection** section.

All requests and responses use JSON.

## Authentication

Every request needs a workspace API key, sent as a Bearer token in the `Authorization` header:

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

Workspace admins create keys under **Settings → API**. A key is shown only once, when it's created. See [API keys](https://docs.mercora.io/admin/api-keys.md).

The key alone decides which workspace you're calling. You never send a workspace or tenant ID.

> [!WARNING]
>
> Keep keys secret, and call the API from your servers, not from a browser or mobile app. Anyone with a key can call Mercora as your workspace, within the key's scopes.

## Scopes

Each key carries one or more scopes, and each endpoint needs one of them. A key without the endpoint's scope 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` |

Some endpoints also need a workspace module. `POST /hedge-requests` 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).

## Request bodies

Request bodies are JSON objects with a fixed schema. Unknown fields are refused, so a misspelled field name fails with a `422` instead of being silently ignored.

## Errors

Errors always come back as JSON with an `error` message:

```json theme={"system"}
{
  "error": "Invalid or revoked API key."
}
```

When a body fails validation (`422`), the response 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. A missing required field reads `Required`.

### Status codes

| Status | Meaning |
| - | - |
| `200` | Success. On a create, the same `external_id` and body were sent before, and you get what was created the first time. |
| `201` | Created. |
| `202` | Accepted: 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 doesn't have the endpoint's scope, or the module the endpoint needs is turned off for your workspace. |
| `404` | No such object in your workspace. |
| `409` | Conflict. Usually an `external_id` reused with a different body. For automations, also an automation that isn't 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

Requests that create something carry your own `external_id`: any string up to 200 characters that identifies the request in your system, such as a purchase order number.

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

This applies to `POST /hedge-requests` and `POST /agents/{id}/run`.

## IDs

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

## OpenAPI

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

## Next steps

> **[API keys](https://docs.mercora.io/admin/api-keys.md)**
>
> Create a key for your system and choose its scopes.

> **[Hedging](https://docs.mercora.io/workflows/hedging.md)**
>
> What happens to a hedge request once it reaches the Inbox.

> **[Automations](https://docs.mercora.io/workflows/automations.md)**
>
> Set an automation to run when your system calls it.


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