Public API
Read your organization's Z8 data from your own systems
The Z8 Public API v1 lets your organization's own systems read its data. It is read-only and lives under /api/v1. The pages in this section are generated from the OpenAPI document the API itself serves.
Your installation's base URL
Use the base URL of your own Z8 installation for API requests. The hosted examples here use https://ui.z8-time.app; if you self-host Z8, replace that origin with your installation's public origin, for example https://workforce.example.org. The documentation site at https://docs.z8-time.app is not an API server.
In your installation, open Settings → Enterprise → Developer Access → API Keys and choose Download OpenAPI spec, or retrieve /api/v1/openapi.json directly from that installation. Both the reference and the spec are public: you do not need a Z8 session or an API key to read them. The download contains the deployed contract and an absolute server URL for that installation, so importing the JSON file into a client keeps API requests pointed there. It contains no credentials or organization records; configure your API key separately in the client.
Authentication
Create an API key under Settings → Enterprise → API Keys (see API Keys) and send it as a Bearer token:
curl "https://ui.z8-time.app/api/v1/work-periods?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer z8_org…"A key acts as its organization, limited to its key scopes. Each endpoint names the scope it requires; a key without it gets 403 scope_missing. Browser sessions are never accepted.
Lists and pagination
Every endpoint returns a page: { "data": [...], "nextCursor": "..." }. Pass nextCursor as cursor to read the next page; it is null on the last page. limit sets the page size (1 to 200, default 50). Walking the cursor returns every row exactly once.
Work periods and absences require a from/to range of at most 366 days.
Times and dates
- Work periods are UTC instants (
2026-10-01T06:00:00.000Z), each with the UTC offset where the clock event was recorded (+02:00). Show local times with that offset, not your own time zone. - Absences are local calendar dates (
2026-10-05) with a half day (am,pm) where one applies. They are never instants.
Errors
Errors are application/problem+json (RFC 9457) with a stable type: invalid_key, scope_missing, billing_required, rate_limited, validation_failed, not_found or server_error. A validation_failed problem lists each invalid parameter in errors.
Supported operations return 500 server_error when an unexpected error occurs while processing the request. Each operation documents this response with the shared problem schema.
An unknown route under /api/v1 returns 404 not_found with the detail No Public API v1 endpoint has this path. Check the request path against the operations in this reference. This response means the route does not exist; the supported list operations do not return a resource-not-found response when no records match.
Rate limits
Every response to a request with a known key, refusals included, carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the tighter of the key's own limit and your organization's limit. A 429 rate_limited response also carries Retry-After.
MCP server
AI assistants can read the same data as tools through the MCP server at /api/mcp, with the same API keys, scopes and rate limits.
Versioning
Within /api/v1, changes only add fields or endpoints. Ignore fields you don't know. Removing or renaming anything would require /api/v2.