API Overview & Authentication

DevClocked exposes an HTTP API for tracking and reporting — the same API used by the DevClocked CLI, editor extensions, desktop app, and the MCP server. Anything those clients can do, you can do directly over HTTPS with an API key.

Base URL

https://api.devclocked.com/functions/v1

Every endpoint in this reference lives under that base path. For example, the tick-ingest endpoint is https://api.devclocked.com/functions/v1/track-tick.

Authentication

Requests are authenticated with a DevClocked API key sent in the x-devclocked-key header:

curl -X POST https://api.devclocked.com/functions/v1/get-time-breakdown \
  -H "x-devclocked-key: dck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-08-01", "to": "2026-08-07", "group_by": "day"}'

API keys start with dck_ and are generated in Settings > API Keys — see Managing API Keys. A key authenticates as the account that created it; revoking a key takes effect on the next request. There is no OAuth flow and nothing to refresh.

You can check a key with the verify-api-key endpoint (documented in Tracking Endpoints) before storing it in a client.

Request format

Endpoints accept JSON. Reporting endpoints are POST with a JSON body (an empty body means "use defaults"); a small number of read endpoints take query-string parameters instead — each endpoint page states which. Always send Content-Type: application/json when posting a body.

Error format

Errors return an appropriate HTTP status code and a JSON body with a single error message:

{ "error": "invalid group_by: month (expected day | hour | weekday)" }

Status	Meaning
400	Invalid parameters — the error message says which field and why
401	Missing, malformed, unknown, or revoked API key
403	The key is valid but lacks the scope the endpoint requires
404	A referenced resource (for example a named project) was not found
405	Wrong HTTP method for the endpoint
413	Request body too large
429	Rate limit exceeded — back off and retry
500	Something failed on our side

One exception: verify-api-key responses always include an ok boolean alongside error, so clients can branch on a single field.

Rate limiting

Write endpoints are rate limited per account. When you exceed a limit the API returns 429 with an error message; wait briefly and retry with backoff. Trackers that batch ticks (as the official clients do) stay comfortably within the limits.

OpenAPI specification

A machine-readable OpenAPI 3.1 description of every endpoint in this reference is served at:

https://devclocked.com/openapi.json

Point a generator or an API client (Postman, Insomnia, Bruno, an LLM tool) at that URL to get typed request and response models.

Endpoints

• Tracking endpoints — start and end sessions, send activity ticks, link commits, read the active session, verify a key.
• Reporting endpoints — today's activity, time breakdowns, delivery reports, issue analytics, weekly insights, and your project list. These back the DevClocked MCP tools.