ZoikoDigital
Development Documentation

Build on governed time.

Everything you need to integrate ZoikoTime — a REST API for records, policies, evidence, and events, with deterministic classification and human authority built in.

/
GET /v1/records/rec_4821
{  "id": "rec_4821",
  "state": "needs_review",
  "source": "web_clock",
  "policy": { "id": "auto_clockout", "version": 4 },
  "classification": "deterministic",   // never an opaque score
  "evidence": { "provenance": true, "preserved": true },
  "decision": null              // a human decides
}
Quickstart

Your first call in three steps

1

Get a scoped API key

Create a least-privilege key in the developer console and set
ZOIKO_API_KEY.
2

Make a request

Call GET /v1/records with your key and a pinned Zoiko-Version header.
3

Read the evidence

Follow evidence on any record for its preserved, append-only trail.
authenticate.sh
# Every request is authenticated with a scoped API key
curl https://api.zoikotime.com/v1/records \
  -H "Authorization: Bearer $ZOIKO_API_KEY" \
  -H "Zoiko-Version: 2026-06-01"
API Reference

Explore the API

Six core resources — records, auth, policies, evidence, events, and reports.

Records API

Read time records, states, sources, and provenance.
Records →

Authentication

Scoped API keys, OAuth, and least-privilege access.
Auth →

Policies

Fetch versioned, deterministic policy definitions.
Policies →

Evidence Ledger

Retrieve preserved, append-only evidence trails.
Evidence →

Webhooks & Events

Subscribe to record, review, and evidence events.
Events →

Reports

Query aggregate, governed reporting data.
Reports →
Records

A record is explainable by design

Every record carries its source, the versioned policy that applied, a deterministic classification, and a preserved evidence trail — and a decision field only a human fills.

GET /v1/records/rec_4821
{  "id": "rec_4821",
  "state": "needs_review",
  "source": "web_clock",
  "policy": { "id": "auto_clockout", "version": 4 },
  "classification": "deterministic",   // never an opaque score
  "evidence": { "provenance": true, "preserved": true },
  "decision": null              // a human decides
}

Classification is deterministic, never an opaque AI score, and decision stays null until an authorized human acts.

Endpoints

Common endpoints

A quick map of the most-used routes.

GET/v1/records

List & filter time records with state and provenance

GET/v1/records/{id}

Retrieve a single record and its evidence

POST/v1/records/{id}/corrections

Submit a reasoned correction (append-only)

GET/v1/policies/{id}

Fetch a versioned, deterministic policy definition

GET/v1/evidence/{id}

Read a preserved evidence trail

POST/v1/webhooks

Subscribe to record, review & evidence events

DELETE/v1/webhooks/{id}

Remove a webhook subscription

Designed for clean, boring, reliable integration.

Idempotent writes, pinned versions, clear errors, and preserved evidence.

Core Concepts

Concepts worth knowing first

A few ideas that shape every endpoint.

Evidence Ledger

Append-only, preserved trails. You can read evidence, never silently rewrite it.

Deterministic classification

Rules are versioned and explainable — there is no black-box score in the API.

Human authority

Consequential decisions require a human. The API surfaces context; it never auto-decides.

Scopes & roles

Keys are least-privilege and scoped; access maps to governed roles.

Idempotency

Writes accept an idempotency key so retries never double-apply.

Versioning

Pin a dated API version header; changes are additive and announced in the changelog.

Core Concepts

Concepts worth knowing first

A few ideas that shape every endpoint.

Evidence Ledger

Append-only, preserved trails. You can read evidence, never silently rewrite it.

Deterministic classification

Rules are versioned and explainable — there is no black-box score in the API.

Human authority

Consequential decisions require a human. The API surfaces context; it never auto-decides.

Scopes & roles

Keys are least-privilege and scoped; access maps to governed roles.

Idempotency

Writes accept an idempotency key so retries never double-apply.

Versioning

Pin a dated API version header; changes are additive and announced in the changelog.

SDKs

Official libraries

Install a client for your stack and skip the boilerplate.

JavaScript / TS

npm i @zoikotime/sdk

Python

pip install zoikotime

Go

go get zoikotime.com/sdk

Ruby

gem install zoikotime

All examples use synthetic sandbox data. Availability of specific endpoints, SDKs, and versions is confirmed in the developer console for your account.

Guides

Guides & walkthroughs

Task-focused guides for the most common integrations.

Authentication & keys

Authentication & keys

Create scoped keys, rotate secrets, and apply least privilege.

Working with records

Working with records

Fetch, filter, correct, and read evidence on time records.

Webhooks & events

Webhooks & events

Subscribe to events and verify signed payloads reliably.

API Principles

An API that respects people

The same governance that shapes the product shapes the API: explainable rules, preserved evidence, and human authority — never surveillance.

Human authority remains controlling. The API exposes governed records, explainable policy, and preserved evidence; it does not make automatic employment, payroll, or legal decisions, and endpoints are provided as documented in the developer console.