Bayline documentation

The API at a glance

• Base URL: your own Bayline. All routes are under /api, JSON in and out.
• Schema: the full OpenAPI 3.1 schema is served by your own installation to signed-in people and agent keys; the API reference lists every operation.
• Reference: every endpoint, generated from that schema.
• Errors are always {"code", "message"}, for example 404 not_found or 409 version_conflict.

Authentication

• Agent key: Authorization: Bearer bk_<id>.<secret>. Also send X-Agent-Name: <harness>/<version>; it is stored on the audit trail.
• Browser session: the bayline_session cookie; writes also need the X-CSRF-Token header.

Create a key

Signed in as the person the agent works for: Menu → Agent keys → New key.

• Scopes: what the key may write, never more than the person’s role allows (for example stock_move, items_write, service_run, gages_write, files_upload). No scopes means read-only.
• Propose only (on by default): every change waits on the Pending page for a person.
• Expiry: 180 days by default. The token is shown once.

Roles

Every role except viewer may also put a gauge on hold with a comment.

Writing safely

• Idempotency: send a new Idempotency-Key (a UUID) per intended change. With an agent key, a write without one is refused (428). The same key and body replays the first answer (Idempotent-Replayed: true); the same key with another body is refused (422). Keys are remembered for 48 hours.
• Answers: 201 applied, 202 {"status": "pending", "proposal": …} waits for a person, 403 propose_required for a propose-only key (send POST /api/proposals instead).
• What applies at once (default shop policy, keys that are not propose-only): small takes (up to 10 units or 20 % of what is on hand), returns, meter readings and gauge uses. Bigger takes, stock counts, calibrations, edits and deletes wait for a person, and so does anything sent with confidence below 0.9. Fault reports and evidence photos are new records and apply at once for every key.
• Concurrency: If-Match (or expected_version) on a PATCH; a stale version answers 409 version_conflict.
• Batches: POST /api/batch, up to 50 operations, all or nothing, with dry_run to preview.

Look up, then act; undo

• GET /api/lookup?q=… finds items, serials, tools, gauges, machines, locations and people from loose text, typos, æøå, sizes like Ø10 and scanned QR or barcodes. Use the top hit only when needs_confirm is false; never invent ids.
• Every change has a history entry with before and after values. POST /api/events/{id}/revert undoes it if nothing later conflicts; from an agent key an undo is a proposal a person confirms.
• GET /api/digest: low stock, calibration and service due, pending proposals, open faults and yesterday’s changes.

Limits and network

• 600 requests per minute per key by default; over that, 429 with Retry-After.
• Plain HTTP is fine for an agent inside the shop network. An agent in the cloud or anywhere off-site must reach Bayline over HTTPS or a VPN.
• Harnesses that speak MCP can use the optional MCP server instead of raw HTTP.