# Send data to Mestra

Push JSON or CSV from your own system to a Topos connector with a key. The address, headers, body, answers, errors and keys.

A **Receive** connector takes data your system sends. Your till, your stock system or a script of your own sends a payload when something changes. Mestra keeps what arrived, reads rows out of it, checks each row and writes it into a table. You can send the same data again safely.

## Set up a receive connector

An owner does this on the **Ingest** page. See [Add a connector](https://withmestra.com/docs/topos/connectors/#add-a-connector).

1. Select **Add a connector**, then **Receive**, then **Custom** (or **Point of sale**, see [Templates](https://withmestra.com/docs/topos/templates/)).
2. Paste a sample of what your system sends, as JSON or CSV. Mestra reads it as a table you can shape.
3. Test it, name it and select **Save connector**.
4. Mestra makes a first key and shows it once on the connector's page: "Copy this key now. It won't be shown again."

The connector's page then shows **Send to**, the address to send to.

## The request

```http
POST https://app.withmestra.com/ingest/{connector}
Authorization: Bearer mpk_...
Content-Type: application/json
X-Mestra-Batch: till-2026-11-14-0930
X-Mestra-As-Of: 2026-11-14T09:30:00+13:00
```

- **Address.** `{connector}` is the connector's key. Use the address shown under **Send to**. The address is on the app host, `app.withmestra.com`, not on the Topos host. It is not under `/api/v1`.
- **Credential.** Send the key as `Authorization: Bearer <key>`. A key begins `mpk_`. A key works for one connector only. A key of another connector is answered as an unknown connector. A revoked key and a key that never existed get the same answer. There is no request signing. The key is the whole credential, so keep it secret, send over HTTPS only, and make a separate key for each sender so you can revoke one without touching the others.
- **Content type.** A connector that reads JSON takes `application/json`, or any type that ends in `+json`. A connector that reads CSV takes `text/csv` or `application/csv`. A charset after the type is fine. Any other type, or none, is refused with `415`.
- **Body.** Your own shape, not a Mestra one. The connector's routes say where the records are. A CSV body is read as records keyed by its header row. A body is at most 100 MiB.

Two headers are optional.

| Header           | What it is                                                                                                                 | If you leave it out                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `X-Mestra-Batch` | A name for this send, 1 to 128 bytes. Letters, digits and punctuation are one byte each.                                   | Mestra uses the SHA-256 of the body. An identical resend is then the same batch. |
| `X-Mestra-As-Of` | When the data was true, as an RFC 3339 time with an offset, such as `2026-11-14T09:30:00+13:00` or `2026-11-14T09:30:00Z`. | The time Mestra received the payload.                                            |

### An example

```bash
curl -sS -X POST "https://app.withmestra.com/ingest/pos" \
  -H "Authorization: Bearer $MESTRA_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Mestra-Batch: till-2026-11-14-0930" \
  -d '{"items":[{"location":"queen-st","item_id":"1001","name":"Flat white","price":450,"currency":"NZD","available":true,"stock":40}]}'
```

The answer:

```json
{
  "landed": "5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365",
  "routes": {
    "items": {"applied": 1, "unchanged": 0, "stale": 0, "gone": 0},
    "sales": {"applied": 0, "unchanged": 0, "stale": 0, "gone": 0, "no_records": true}
  }
}
```

The `sales` route found no `sales` list in this payload, so it did nothing.

## Sending the same data again

If you send a batch name that has landed before for this connector, Mestra does nothing and answers the first result again with `"replay": true`. Batch names belong to one connector.

If the first send failed (`unreadable` or `routing_failed`), sending it again under the same batch name gets the same failure. Fix the problem and send a corrected payload under a new batch name. Without the header, a changed body is a new batch.

## Older data

For a keyed table, a row changes only if your data is as new as the row. If the stored row has a newer `X-Mestra-As-Of` than your batch, that row is counted as `stale` and left alone. A payload that arrives late can't undo newer data. A full snapshot, a **Replace everything** route, marks a row gone only if the row isn't newer than the snapshot. A log table doesn't compare times. It keeps each event once, by its key.

## What comes back

A successful send is `200`. Every error has the body `{"error": "...", "code": "..."}`. `error` is a sentence you can show a person.

| Status | Code                     | When                                                                                                                                                                                                                                                                                       |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200`  |                          | The payload landed and was routed. `replay` is `true` when the batch had landed before.                                                                                                                                                                                                    |
| `400`  | `unreadable`             | The body doesn't read as the connector's format, for example "The body is not valid JSON (byte 12)." The payload is kept all the same, and the body holds `landed`. No row reaches a table.                                                                                                |
| `400`  | `bad_batch`              | `X-Mestra-Batch` is longer than 128 bytes or holds a NUL.                                                                                                                                                                                                                                  |
| `400`  | `bad_as_of`              | `X-Mestra-As-Of` isn't an RFC 3339 time.                                                                                                                                                                                                                                                   |
| `400`  | `bad_body`               | The body couldn't be read from the connection.                                                                                                                                                                                                                                             |
| `401`  | `bad_key`                | The key is unknown or revoked.                                                                                                                                                                                                                                                             |
| `403`  | `org_unavailable`        | The organisation can't take data right now.                                                                                                                                                                                                                                                |
| `403`  | `topos_off`              | Mestra Topos is off for the organisation. Nothing is kept.                                                                                                                                                                                                                                 |
| `404`  | `unknown_ingestor`       | No such connector, a key of another connector, or a connector that doesn't take pushes.                                                                                                                                                                                                    |
| `413`  | `too_large`              | The payload is over 100 MiB. Send it in smaller payloads.                                                                                                                                                                                                                                  |
| `415`  | `unsupported_media_type` | The `Content-Type` isn't one the connector takes, such as "This connector takes application/json."                                                                                                                                                                                         |
| `422`  | `routing_failed`         | A route couldn't write its table. The message names the route and never a value from your data. The payload is kept, no row of it reached a table, and the body holds `landed`. You can [replay](https://withmestra.com/docs/topos/runs-and-replay/#replay) it after fixing the connector. |
| `429`  |                          | Mestra can't take another large payload at this moment, or the table is being written by another send. Nothing was kept. Wait the seconds in the `Retry-After` header and send it again.                                                                                                   |
| `429`  | `rate_limited`           | Too many requests with unknown keys came from your address. Wait the seconds in `Retry-After`. A good key isn't held back by this.                                                                                                                                                         |
| `500`  |                          | Mestra couldn't store the payload. Nothing was recorded. Send it again.                                                                                                                                                                                                                    |

Errors from the other `/topos` calls are in [Errors and refusals](https://withmestra.com/docs/topos/troubleshooting/).

### The `routes` object

`routes` has one entry for each route, by the route's name.

| Field            | Meaning                                                                                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applied`        | Rows that were new or changed. For a log table, events added.                                                                                                                            |
| `unchanged`      | Rows already stored the same. For a log table, events already stored.                                                                                                                    |
| `stale`          | Rows left alone because the stored row is newer than your `X-Mestra-As-Of`.                                                                                                              |
| `gone`           | Rows a **Replace everything** route marked gone.                                                                                                                                         |
| `refused`        | The first 10 refused rows, each with `index` (counting from 0 in the route's records), `field` and `reason`. Only present when some were refused. A refused row doesn't stop the others. |
| `refused_total`  | How many rows were refused, when `refused` lists only the first 10.                                                                                                                      |
| `dropped`        | Names of fields in your records that no column reads, sorted. At most 1,000 names, each cut at 200 bytes. These fields are not kept in the table.                                        |
| `dropped_more`   | There were more than 1,000 such names.                                                                                                                                                   |
| `changed`        | The keys of rows that changed or went, in order. The first 1,000. Keyed tables only.                                                                                                     |
| `changed_total`  | How many keys changed or went, when `changed` lists only the first 1,000.                                                                                                                |
| `gone_skipped`   | A **Replace everything** route had a refused row whose key couldn't be read, so it marked nothing gone.                                                                                  |
| `empty_snapshot` | A **Replace everything** route found no records, so it took nothing and marked nothing gone. This is `200`, not an error, so an empty send can't wipe a table.                           |
| `no_records`     | The route's records path isn't in the payload at all. An empty list at the path is not this.                                                                                             |

The reasons a row is refused are in [Errors and refusals](https://withmestra.com/docs/topos/troubleshooting/#why-a-row-is-refused).

## Money

Send money as whole minor units. `2400` means $24.00. `24.00`, `24.5`, `2400.0` and `"24.00"` are refused with `not_minor_units`. Only that row is refused. A negative whole number, such as `-500` for a refund, is fine. Send the currency in its own field, three upper-case letters.

## Keys

An owner manages keys on a receive connector's page, under **Keys**. Nobody else sees them.

- **Make a key.** Enter a **Key name** of 1 to 80 characters, such as "Back office till", and select **Make a key**. The key shows once with **Copy**. Mestra keeps only a hash of it and its last four characters, so it can't show it again. If you lose it, make another.
- **Read the list.** Each key shows its name, "Ends" and its last four characters, when it was made, and when it was last used, or "not used yet".
- **Revoke a key.** Select **Revoke**, then confirm "Revoke this key? Nothing more can be sent with it. The data already here is kept." The next send with that key is `401 bad_key`. Other keys on the connector keep working.

## What Mestra keeps

- **Every payload is kept as it arrived**, with who sent it, when, its size and what each route did. A payload is kept even when it can't be read or a route fails. The connector's page lists each one under **What has landed**, and an owner can select **Show body**. Because the original is kept, you can [replay](https://withmestra.com/docs/topos/runs-and-replay/#replay) it after changing the connector.
- **Card numbers are masked.** Card numbers are masked to their last four digits as they arrive, before the payload is kept. A run of 15, 16 or 19 digits that passes the card number check and starts like a card number keeps its last four digits, and every other digit becomes `*`. Nothing else is masked. A bare number in JSON that is masked becomes a string, so the payload stays valid JSON.
- **Only mapped fields reach a table.** A table keeps only the columns the connector maps. Other fields in your records are dropped from the table, and `dropped` names them.
- **You are responsible for what you send.** Mestra keeps your data as you send it, except for card numbers. Don't send what you have no right to send.

## Limits

| Limit                            | Value           |
| -------------------------------- | --------------- |
| A payload                        | 100 MiB         |
| A batch name                     | 1 to 128 bytes  |
| Refused rows listed in an answer | The first 10    |
| Changed keys listed in an answer | The first 1,000 |
| Text in one value                | 500 characters  |

See [Limits](https://withmestra.com/docs/topos/limits/) for all of them.
