Developers

A small, scoped REST API.

Connect lab systems and scripts to Oqelvia with workspace API keys. Three endpoints are live today; anything not listed here does not exist yet.

Create an API key

Authentication

Owners and admins create keys in Settings → Developer access. Send the key as Authorization: Bearer cb_live_…. Keys are shown once and stored only as SHA-256 hashes; they can expire and be revoked instantly.

Permissions

Each key is tied to one workspace and carries explicit scopes: spec_check:run, datasets:read, analyses:read. The API is read-only for stored data.

Limits & logging

60 requests per minute per key, reported in X-RateLimit-* headers. Every request is logged with its status, and key creation and revocation appear in the workspace audit history.

POST/v1/spec-check

Evaluates measurements against the limits you send, using the same rule-based method as the workspace (calibra-spec-check). Nothing is stored.

Scope: spec_check:run

Request

curl -X POST https://<your-oqelvia-domain>/api/public/v1/spec-check \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Pan bread",
    "batch": "B-1042",
    "measurements": [
      { "parameter": "Moisture", "value": 40.6, "unit": "%", "spec_min": 38, "spec_max": 40 },
      { "parameter": "Protein",  "value": 12.1, "unit": "%", "spec_min": 11.5, "spec_max": 12.5 }
    ]
  }'

Response

{
  "product": "Pan bread",
  "batch": "B-1042",
  "method_version": "calibra-spec-check 1.0.0",
  "results": [ { "parameter": "Moisture", "mean": 40.6, "status": "review", … } ],
  "deviations": [ { "parameter": "Moisture", "limit": "≤ 40", "delta": 0.6, "severity": "review" } ],
  "recommendations": [ "Moisture: observed mean 40.6 % is outside the specification …" ],
  "disclaimer": "Rule-based specification check for decision support. …"
}

GET/v1/datasets

Lists up to 100 datasets imported into the key's workspace, newest first.

Scope: datasets:read

Request

curl https://<your-oqelvia-domain>/api/public/v1/datasets -H "Authorization: Bearer cb_live_…"

Response

{ "data": [ { "id": "…", "name": "…", "row_count": 120, "status": "imported", "created_at": "…" } ] }

GET/v1/analyses

Lists up to 50 stored analyses with results, deviations, recommendations and method version.

Scope: analyses:read

Request

curl https://<your-oqelvia-domain>/api/public/v1/analyses -H "Authorization: Bearer cb_live_…"

Response

{ "data": [ { "id": "…", "product": "…", "batch": "…", "status": "completed", "method_version": "calibra-spec-check 1.0.0", … } ] }

Errors

401missing_or_malformed_key · invalid_key · key_revoked · key_expired
403missing_scope — the key lacks the endpoint's permission
422validation_failed — body did not match the schema (issues listed)
429rate_limited — over 60 requests in the last minute; see Retry-After

Results are rule-based decision support, not a substitute for qualified laboratory review.