Skip to content

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.

  1. Select Add a connector, then Receive, then Custom (or Point of sale, see 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

Shell
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 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 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 for all of them.