# Topos API

The call your own systems make to send data to Topos, and how it relates to the rest of the Mestra API.

The one call your own systems make to Topos is the push: a `POST` of a payload to a [Receive connector](https://withmestra.com/docs/topos/send-data/). It uses an ingest key, not an API key.

## What is and isn't in the API reference

The [API reference](https://withmestra.com/docs/api/) 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](https://withmestra.com/docs/mcp/).

## Push a payload

```http
POST https://app.withmestra.com/ingest/{connector}
Authorization: Bearer mpk_...
Content-Type: application/json
X-Mestra-Batch: optional-batch-name
X-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

```json
{
  "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](https://withmestra.com/docs/topos/send-data/#the-routes-object). Every status and code, such as `bad_key`, `unreadable` and `routing_failed`, is in the [table of answers](https://withmestra.com/docs/topos/send-data/#what-comes-back). An error has the body:

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

- `429` and `500`: nothing was stored. Send it again, after the `Retry-After` seconds if given.
- `unreadable` and `routing_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": true` and changes nothing.

### Example in code

```python
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"])
```
