Build on your calibration data.

The Axiospec Public API is a REST interface to your calibration program. Read and create instruments, log calibrations to the tamper-evident ledger, and read your workspace sites and the compliance standards you have selected.

It is a curated, stable contract, separate from the internal endpoints the web and mobile apps use, so your integration keeps working as the product evolves. Every response is JSON.

All endpoints live under a single base URL. Every path in the reference below is relative to it.

Authenticate every request with a per-workspace API key. A workspace admin creates one in the app under Settings then API Keys. Keys are shown once at creation and are prefixed ctk_. Store the key as a secret and never ship it in client-side code.

Send the key on every request as a bearer token:

A standard X-API-Key header is also accepted if you prefer it: X-API-Key: ctk_your_api_key. A request with no key returns 401.

The API is available on Professional plans and above. A key that belongs to a workspace on the Free or Starter plan receives a 403 with the code API_ACCESS_TIER_REQUIRED. Upgrade the workspace to enable it.

Each key is issued with a scope. A read key can list and fetch. A write key can also create instruments, update them, and log calibrations (write always implies read).

A read-only key that attempts a write receives a 403 with the code INSUFFICIENT_SCOPE, naming the required scope. Issue read-only keys for reporting integrations so they can never change a record.

Requests are limited to 120 per minute, counted per API key rather than per IP, so one integration cannot starve another and many keys behind one office network are not throttled together.

Every response under the API carries the current window as headers, so you can pace yourself without guessing. X-RateLimit-Limit is the ceiling (120), X-RateLimit-Remaining is how many requests are left in the current window, and X-RateLimit-Reset is the number of seconds until the window resets and Remaining returns to the full limit.

Exceeding the limit returns a 429 with the code RATE_LIMITED. On the 429 a Retry-After header (in seconds) tells you exactly how long to wait; honor it, then retry. Reading these headers rather than hard-coding a delay keeps you fast when there is headroom and polite when there is not.

To keep an external system in step without re-reading everything, pull only what changed since your last run. Each collection accepts an updated_since parameter (an ISO-8601 UTC timestamp) that returns only records modified at or after that instant, plus a sort parameter so you can walk them oldest-first and advance a watermark as you go.

The tenant-wide calibration feed, GET /calibrations, is built for exactly this: it returns every calibration across all your instruments in one paged stream, so you do not have to loop instrument by instrument. Sort ascending by updated_at, page through, and remember the created_at of the last record you saw. The ledger is append-only, so a calibration record never changes after it is written and its created_at is its last-modified time; sort=updated_at maps to that instant.

On the next run, pass that saved value as updated_since. Overlap the boundary by a second or two and de-duplicate on the record id to be safe against clock skew. Store the watermark only after you have durably processed the page.

Instruments support the same updated_since and sort parameters (GET /instruments), filtering on the instrument’s last-modified time. The list rows do not include a timestamp field, so for instruments use the wall-clock time you captured just before the request as your next updated_since; the single-instrument GET /instruments/{id} returns created_at and updated_at if you need them.

GET /instruments accepts filters so you can fetch a precise slice instead of paging the whole roster. asset_tag and serial_number match an exact value (handy for reconciling a single instrument against an ERP record). status filters by lifecycle state, for example active or retired. site_id scopes to one site.

Two filters are derived from calibration state. compliance_status filters by the computed token, one of COMPLIANT, WARNING, NON_COMPLIANT, or NOT_CALIBRATED. next_due_before takes a date (YYYY-MM-DD) and returns instruments whose next calibration is due before it, which is the query behind a due-soon or overdue worklist. Filters combine, so you can ask for active, non-compliant instruments at one site in a single call.

Logging a calibration is the one write that must never be duplicated: the ledger is append-only, so there is no way to undo a double-post. For that reason POST /instruments/{id}/calibrations requires an Idempotency-Key header (any unique string you generate, for example a UUID). It is required, not optional.

If a request is interrupted and you retry it with the same key, the API returns the record it already wrote instead of writing a second one. A missing key returns a 400 with the code IDEMPOTENCY_KEY_REQUIRED. Generate a fresh key per calibration you intend to record.

Creating an instrument (POST /instruments) also honors an Idempotency-Key, but here it is optional. Send one and a retry with the same key returns the instrument the first call created instead of a duplicate, exactly as the calibration log does; the only difference is that the key is not required. If you would rather not manage keys for creates, you can instead deduplicate on your side using the instrument’s asset_tag or serial_number, which are unique within a workspace, before you POST.

Every approved calibration has a branded PDF certificate. Fetch it with GET /calibrations/{calibration_id}/certificate. The response is the PDF itself (Content-Type application/pdf) as an attachment, byte-identical to the certificate the app produces, so you can archive it or attach it to a work order.

A certificate exists only for an approved, current calibration. If the record is voided, superseded by a later entry, or otherwise not certifiable, the request returns a 404 with the code CERTIFICATE_UNAVAILABLE. A calibration id that is not yours, or does not exist, returns a plain 404 that reveals nothing about it.

When an instrument leaves service, retire it with POST /instruments/{id}/retire (a write-scope call). This is a soft decommission: the instrument’s status becomes retired and it drops out of the default active list, but nothing is deleted and its calibration history on the ledger is left fully intact for audit. There is no hard delete in the API.

The call returns the updated instrument. It is idempotent: retiring an instrument that is already retired is a no-op that returns the same retired record, so a retry is always safe. Retiring requires a manager or admin key; a read-only or technician key receives a 403.

List endpoints return a consistent envelope. Page through results with the limit and offset query parameters; total is the full count and has_more tells you whether another page exists.

Every timestamp the API returns is ISO-8601 in UTC, ending in Z, for example 2026-07-09T15:30:00Z. Send timestamps the same way. There are no offset or local-time responses to normalize.

One field is a plain date, not a timestamp: an instrument’s calibration due date. Due dates are computed in your workspace’s configured time zone, so a due date is the calendar day it is due there, and the next_due_before filter takes a date (YYYY-MM-DD) rather than a timestamp. If your systems run in a different zone, compare on the date, not on a midnight-UTC instant.

Every error, on every endpoint, has the same JSON shape: a machine-readable code, a human-readable message, and, for some errors, a details object with the specifics. Branch on code, never on the message text, which may be reworded. The HTTP status still carries meaning (401 versus 403 versus 404), so use it too.

Logging a calibration also enforces the field requirements of the standards your workspace has selected. If a required field is blank, the request returns a 422 with the code FIELD_REQUIREMENTS_UNMET and a missing_fields array, where each entry names the field and which standard requires it, so you can prompt for exactly what is missing.

Instead of polling the API on a schedule to discover what changed, subscribe a webhook endpoint once and Axiospec delivers each event to your URL as it happens. You get lower latency and far less wasted traffic than re-reading collections you have already seen, and you never miss a change between two polls.

Subscribe with POST /webhooks, passing a url and an optional list of event types to receive. Omit the events field to receive every event (the full catalog is below). The response returns the endpoint’s signing secret exactly once and never again, so copy it straight into your secret store. Managing webhooks needs an admin or manager write-scope key, because the endpoint receives your workspace’s calibration and instrument data.

Each event is delivered as an HTTP POST whose JSON body is a fixed envelope: { "id", "type", "created_at", "data" }. The id is the stable event id, sent again as the Axiospec-Event-Id header alongside Axiospec-Event-Type, Axiospec-Webhook-Id, and Axiospec-Delivery-Attempt. Delivery is at-least-once, so the same event can arrive more than once (for example after a retry); dedupe on the envelope id.

A delivery counts as failed on any response that is not a 2xx, and that includes a 3xx redirect: a redirect could point at an internal address, so it is never followed. Transport errors and timeouts count as failures too. Failed deliveries are retried on an exponential backoff that spans roughly three days, after which the delivery is marked exhausted. An endpoint whose recent deliveries all exhaust is automatically disabled so a dead or hostile URL stops consuming capacity. Endpoints must be HTTPS, and a URL that resolves to a private or internal address is rejected when you subscribe.

Inspect what was sent with GET /webhooks/{id}/deliveries, which pages an endpoint’s delivery log and accepts a status filter (pending, failed, succeeded, exhausted). To replay one delivery, POST /webhooks/{id}/deliveries/{delivery_id}/retry: it resets that delivery to pending and due now so the next dispatch resends it, with a fresh retry horizon. Rotate an endpoint’s secret with POST /webhooks/{id}/rotate-secret (the old secret stops verifying immediately), and stop deliveries with DELETE /webhooks/{id}.

These are the event types a webhook can subscribe to. List the ones you want when you subscribe, or omit the events field to receive all of them. The same catalog is available at GET /webhooks/events for programmatic discovery.

Every delivery carries an Axiospec-Signature header of the form t=<unix-seconds>,v1=<hex>. Verify it before you trust a payload: a valid signature proves the request came from Axiospec and that the body was not altered in transit.

Read the Axiospec-Signature header and split it on the comma into its t= part (a Unix timestamp in seconds) and its v1= part (a lowercase hex HMAC). Recompute HMAC-SHA256, keyed by your endpoint’s signing secret, over the string formed by the timestamp, a literal dot, and the exact raw request body, that is f"{t}.{raw_body}". Compare your hex digest against the v1 value with a constant-time comparison, never an ordinary equality check.

Sign the raw bytes exactly as received, before any JSON parsing or re-serialization, so your input matches what was signed. Reject the delivery if the digests do not match, or if t is more than about five minutes old, which bounds how long a captured request could be replayed against you.