Reference
Topos API
The one call your own systems make to Topos is the push: a POST of a payload to a Receive connector. It uses an ingest key, not an API key.
What is and isn’t in the API reference
The API reference covers calls that use an API key. Topos has no calls of that kind today.
The other calls that Topos makes, such as listing tables or saving a decision, belong to the Topos pages and need a person signed in. They aren’t offered with an API key, and they aren’t in the reference. Everything you can do through them, you can do in Topos. To send data from your own systems, use the push below. To work from an AI agent instead, see MCP.
Push a payload
POST https://app.withmestra.com/ingest/{connector}Authorization: Bearer mpk_...Content-Type: application/jsonX-Mestra-Batch: optional-batch-nameX-Mestra-As-Of: 2026-11-14T09:30:00+13:00| Part | Value |
|---|---|
| Address | https://app.withmestra.com/ingest/{connector}. Not under /api/v1. |
{connector} |
The connector’s key. |
Authorization |
Bearer and an ingest key made for that connector. An owner makes keys on the connector’s page. |
Content-Type |
application/json (or a type ending +json) for a JSON connector. text/csv or application/csv for a CSV connector. |
X-Mestra-Batch |
Optional. 1 to 128 bytes. The SHA-256 of the body when absent. A batch that has landed before answers its first result with "replay": true. |
X-Mestra-As-Of |
Optional. RFC 3339. When the data was true. |
| Body | Your own shape, up to 100 MiB. |
A request is not signed. The ingest key is the only credential.
Answer
{ "landed": "5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365", "replay": false, "routes": { "items": { "applied": 2, "unchanged": 0, "stale": 0, "gone": 0, "refused": [{"index": 3, "field": "price", "reason": "not_minor_units"}] } }}Every field of routes is in Send data to Mestra. Every status and code, such as bad_key, unreadable and routing_failed, is in the table of answers. An error has the body:
{"error": "The body is not valid JSON (byte 12).", "code": "unreadable", "landed": "5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365"}landed is present when the payload was kept even though it couldn’t be used (unreadable and routing_failed).
Retry safely
429and500: nothing was stored. Send it again, after theRetry-Afterseconds if given.unreadableandrouting_failed: the payload is kept. A resend under the same batch name gets the same failure, so correct it and send under a new batch name.- A resend of a payload that landed is safe. It answers
"replay": trueand changes nothing.
Example in code
import os, requests
r = requests.post( "https://app.withmestra.com/ingest/pos", headers={ "Authorization": f"Bearer {os.environ['MESTRA_INGEST_KEY']}", "X-Mestra-Batch": "till-2026-11-14-0930", }, json={"items": [{"location": "queen-st", "item_id": "1001", "name": "Flat white", "price": 450, "currency": "NZD"}]}, timeout=30,)r.raise_for_status()print(r.json()["routes"]["items"])