Bringing data in
Send data to Mestra
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.
- Select Add a connector, then Receive, then Custom (or Point of sale, see Templates).
- Paste a sample of what your system sends, as JSON or CSV. Mestra reads it as a table you can shape.
- Test it, name it and select Save connector.
- 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
POST https://app.withmestra.com/ingest/{connector}Authorization: Bearer mpk_...Content-Type: application/jsonX-Mestra-Batch: till-2026-11-14-0930X-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 beginsmpk_. 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 takestext/csvorapplication/csv. A charset after the type is fine. Any other type, or none, is refused with415. - 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
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:
{ "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 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.
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.
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 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
droppednames 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 for all of them.