Introduction - Mercora

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.

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.

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:

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. The key alone decides which workspace you’re calling. You never send a workspace or tenant ID.

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.

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:

{
  "error": "Invalid or revoked API key."
}

When a body fails validation (422), the response also lists each problem in issues:

{
  "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

Create a key for your system and choose its scopes.

Hedging

What happens to a hedge request once it reaches the Inbox.

Automations

Set an automation to run when your system calls it.

​Base URL

​Authentication

​Scopes

​Request bodies

​Errors

​Status codes

​Idempotency

​IDs

​OpenAPI

​Next steps

API keys

Hedging

Automations

Base URL

Authentication

Scopes

Request bodies

Errors

Status codes

Idempotency

IDs

OpenAPI

Next steps