Developers

API Reference

BASEhttps://api.zoikotime.comVER2026-06-01AUTHBearer keyFORMATJSON

ZoikoTime REST API

Records, policies, evidence & events — governed, versioned, explainable.

Introduction

The ZoikoTime API is organized around REST. It has predictable, resource-oriented URLs, returns JSON, uses standard HTTP verbs and status codes, and is versioned by date. All classification is deterministic and every consequential decision is made by a human — the API never auto-decides.

Base URLhttps://api.zoikotime.com·Version headerZoiko-Version: 2026-06-01

Authentication

Authenticate with a scoped, least-privilege API key sent as a bearer token. Keys map to governed roles; never expose a secret key in client-side code. All requests must be made over HTTPS.

authenticate.sh

curl https://api.zoikotime.com/v1/records \
  -H "Authorization: Bearer $ZOIKO_API_KEY" \
  -H "Zoiko-Version: 2026-06-01"

Errors

ZoikoTime uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate a client error, and 5xx indicate a server error. Error bodies include a type, message, and where useful a param.

Status	Meaning
200	OK — request succeeded
201	Created — resource created (append-only)
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks the required scope/role
404	Not found — no such resource
409	Conflict — idempotency or state conflict
429	Too many requests — rate limited

Rate limits

Requests are rate limited per API key. Every response includes Zoiko-RateLimit-Remaining and Zoiko-RateLimit-Reset headers. On 429, back off using the reset value. Limits for your account are shown in the developer console.

Pagination

List endpoints are cursor-paginated. Pass limit (1–100) and starting_after with the last object id from the previous page. Responses include has_more and a data array.

Records

Time records carry their source, the versioned policy that applied, a deterministic classification, and a link to preserved evidence.

GET/v1/records

List and filter time records.

Query parameters

Name	Type	Description
state	stringoptional	Filter by record state, e.g. `needs_review`.
source	stringoptional	Filter by capture source, e.g. `web_clock`.
limit	integeroptional	Page size, 1–100 (default 20).
starting_after	stringoptional	Cursor: last object id from the previous page.

Response

200 OK

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "rec_4821",
      "state": "needs_review",
      "source": "web_clock",
      "policy": { "id": "auto_clockout", "version": 4 },
      "classification": "deterministic",
      "decision": null
    }
  ]
}

GET/v1/records/{id}

Retrieve a single record and a reference to its evidence.

Path parameters

Name	Type	Description
id	stringrequired	The record id, e.g. `rec_4821`.

Response

GET /v1/records/rec_4821

{
  "id": "rec_4821",
  "state": "needs_review",
  "source": "web_clock",
  "policy": { "id": "auto_clockout", "version": 4 },
  "evidence": "ev_9f2a",
  "decision": null   // a human decides
}

POST/v1/records/{id}/corrections

Submit a reasoned correction. Corrections are append-only and enter review — the original is never overwritten. Send an Idempotency-Key header to make retries safe.

Body parameters

Name	Type	Description
reason	stringrequired	Why the correction is requested.
fields	objectrequired	The field(s) to correct, e.g. `{ "clock_out": "17:14" }`.

Request

POST /v1/records/{id}/corrections

curl -X POST .../v1/records/rec_4821/corrections \
  -H "Authorization: Bearer $ZOIKO_API_KEY" \
  -H "Idempotency-Key: a1b2c3" \
  -d '{ "reason": "Missing clock-out", "fields": { "clock_out": "17:14" } }'

Response

201 Created

{
  "id": "cor_2211",
  "record": "rec_4821",
  "reason": "Missing clock-out",
  "state": "pending_review",
  "decision": null
}

Policies & Evidence

Policies are deterministic and versioned; evidence trails are preserved and append-only.

GET/v1/policies/{id}

Fetch a versioned policy definition, including its plain-language explanation and the rule that applied.

Path parameters

Name	Type	Description
id	stringrequired	The policy id, e.g. `auto_clockout`.
version	integeroptional	Pin a specific version (defaults to latest effective).

GET/v1/evidence/{id}

Read a preserved, append-only evidence trail for a record.

Path parameters

Name	Type	Description
id	stringrequired	The evidence id, e.g. `ev_9f2a`.

Response

GET /v1/evidence/ev_9f2a

{
  "id": "ev_9f2a",
  "record": "rec_4821",
  "trail": [
    { "event": "captured", "actor": "worker" },
    { "event": "flagged", "actor": "policy:auto_clockout" },
    { "event": "decided", "actor": "user:reviewer" }
  ],
  "preserved": true
}

Webhooks

Subscribe to events and receive signed payloads. Verify the Zoiko-Signature header on every delivery.

POST/v1/webhooks

Create a webhook subscription for one or more event types.

Body parameters

Name	Type	Description
url	stringrequired	HTTPS endpoint to receive events.
events	arrayrequired	Event types, e.g. `record.flagged` or `correction.created`.

Request

POST /v1/webhooks

curl -X POST .../v1/webhooks \
  -H "Authorization: Bearer $ZOIKO_API_KEY" \
  -d '{ "url": "https://your.example.com/hook", "events": ["record.flagged","correction.created"] }'

DELETE/v1/webhooks/{id}

Delete a webhook subscription.

Path parameters

Name	Type	Description
id	stringrequired	The webhook id.

Governance: the API exposes governed records, explainable policy, and preserved evidence. It makes no automatic employment, payroll, or legal decision. No screenshots, keystroke content, URL history, application-name monitoring, or clipboard collection under any tier or configuration.