API reference

A versioned REST API for pulling lab data into other systems, and pushing it in from instruments and scripts. Requires a Professional licence or higher.

Authentication

Every request carries a scoped API key as a Bearer token, plus the target organization’s slug as a query parameter. An owner or admin creates keys at Settings → Integrations → API Keys — the plaintext key is shown exactly once at creation and only its hash is stored, so if it’s lost, revoke it and issue a new one rather than trying to recover it.

Every request

GET /api/v1/samples?orgSlug=my-lab HTTP/1.1
Authorization: Bearer ak_3f9c...

Keys are scoped at creation to exactly the resources they need — samples:read, samples:write, notebooks:read, protocols:read. A request whose key lacks the scope an endpoint requires gets 403, not a partial response.

Base URL

https://<your-archon-deployment>/api/v1

There is no shared Archon API host — every laboratory’s API lives at its own self-hosted deployment’s origin, same as the rest of the application.

Endpoints

Samples

Method	Path	Scope	Description
`GET`	`/api/v1/samples`	`samples:read`	List samples in the organization.
`POST`	`/api/v1/samples`	`samples:write`	Create a sample.

Notebooks

Method	Path	Scope	Description
`GET`	`/api/v1/notebooks`	`notebooks:read`	List non-archived notebook entries.

Notebook entries can only be created and finalized through the application itself, never the API — finalization captures an electronic signature from an authenticated person, which an API key cannot stand in for.

Protocols

Method	Path	Scope	Description
`GET`	`/api/v1/protocols`	`protocols:read`	List protocol templates, org-specific and global.

Every list endpoint returns the same envelope:

Response shape

{
  "data": [ /* array of records */ ],
  "meta": {
    "count": 42,
    "orgSlug": "my-lab"
  }
}

Example — list samples

curl "https://archon.yourlab.org/api/v1/samples?orgSlug=my-lab" \
  -H "Authorization: Bearer ak_3f9c..."

Rate limits

300 requests per minute, per key — the same limit for reads and writes, tracked per key rather than per organization. Over the limit, a request gets 429 with the number of seconds to wait named in the JSON error message.

Error codes

Status	Meaning
`400`	Missing or invalid parameters (e.g. no `orgSlug`).
`401`	Missing, invalid, revoked or expired Bearer token.
`402`	This organization’s licence doesn’t include API access — needs Professional or higher.
`403`	Key lacks the required scope, or the key belongs to a different organization than `orgSlug`.
`404`	Resource not found.
`429`	Rate limit exceeded.
`500`	Internal server error.

Sensor / device endpoints

Environmental monitoring devices (temperature, humidity probes, etc.) use a separate, simpler authentication scheme — a per-device token, not an org API key — because a sensor in the field can’t manage a scoped key the way an integration does.

Method	Path	Auth	Description
`GET`	`/api/v1/monitor/config`	Device token	Device polls for its sampling interval and alert thresholds.
`POST`	`/api/v1/monitor/ingest`	Device token	Submit readings — `{ readings: [{ parameter, value }], firmwareVersion?, signalStrength?, batteryPercent? }`. Rate-limited to 120/min per device.

A device token looks like ark_dev_... and is issued per sensor from Compliance → Environmental Monitoring — it is not the same credential as an API key and isn’t interchangeable with one.

Pulling data from another system (a LIMS, an SSO server) for compliance checking is a different, read-only mechanism — see Connected Systems in the lab workflow guide. The API described on this page is for pushing data into Archon or pulling it out programmatically; connected systems is Archon reaching out to interrogate something else.

Need events pushed to you instead?

Polling an endpoint isn’t the only option — see Webhooks for outbound, HMAC-signed notifications the moment something happens in Archon.