Introduction
Send data into Yarmill from an external system over a JSON HTTPS API.
The Yarmill Ingest API accepts data from a system outside Yarmill — a laboratory, a testing device, a federation database — and writes it into your instance. You send JSON over HTTPS with a token, and the service answers every request.
Base URL
https://ingest.ms.yarmill.comWe keep endpoint paths stable so a working integration doesn't break when the service changes. Even so, treat the base URL as configuration in your client rather than a hard-coded constant, so it can be pointed elsewhere without a new release.
The full interactive reference — every endpoint, schema, and the current error list — is published as OpenAPI at ingest.ms.yarmill.com/swagger. That spec is generated from the service itself, so it is the authority when it disagrees with this page.
What the service does
- Accepts create, update, and delete for any record you can identify uniquely from your side. See Upload data.
- Accepts historical data. There is no cut-off date; you can backfill as far back as your records go.
- Confirms every request. You always get a response telling you whether the data was accepted or rejected.
- Checks your token on every endpoint, which is how the service knows where the data came from.
What the service doesn't do
It doesn't judge data quality. A 200 OK means the payload was received and accepted for processing — not that the numbers in it are sensible. Validating that a measurement is plausible stays your responsibility.
What Yarmill does with the data once it lands — which module it appears in, how it's
labelled, which roles can see it — depends on how your instance is configured. Agree the
originType values and their downstream mapping with Yarmill before you start sending.
Content type
All request and response bodies are JSON. Set the Content-Type header on every request:
Content-Type: application/jsonResponses and error handling
The status code is the whole response. The service returns no body — no created record id, no echo of what you sent, no structured error object. Read the status code and nothing else.
| Code | Meaning |
|---|---|
200 OK | The request was accepted. |
400 Bad Request | The request was invalid. |
401 Unauthorized | The token is missing or invalid. |
403 Forbidden | The token is valid, but not permitted for this operation. |
500 Internal Server Error | The service hit a problem that stopped it completing an otherwise valid request. |
Two consequences worth designing around:
- Don't parse response bodies. Branch on the status code. Where a body does appear it's plain text, not JSON —
/api/pinganswers a bad token withInvalid token— and it isn't a contract to rely on. - Yarmill won't hand you an id. Because a successful upload returns nothing, your own
originIdis the only link between a record in your system and the same record in Yarmill. Send one, and keep it stable. See Upload data.
Treat 500 as retryable and 400/403 as a bug in your client — see Send data reliably.
