REST API Reference

Base URL:

https://app.keito.ai/api/v2

API v2 is Harvest-compatible: request and response fields use snake_case, dates use YYYY-MM-DD, and paginated collections include entity-specific array keys such as time_entries, projects, tasks, and expenses.

Authentication

API key requests require both headers:

Authorization: Bearer kto_xxxxx
Keito-Account-Id: your_company_id

Find the Company ID in Keito under Settings -> API & Developers -> Company ID.

Credential type controls endpoint access. A personal read-only sync key has a fixed seven-request allowlist, intentionally returns a reduced /users/me response without company, cannot call /tasks, and cannot write data. Keito CLI and write integrations require a separate, Administrator-created full-access integration key. See Authentication.

WorkOS Connect JWT requests do not need Keito-Account-Id; the company is resolved from token claims.

Conventions

  • Dates: YYYY-MM-DD for dates. Report endpoints also accept Harvest-style YYYYMMDD.
  • Times of day: time-entry started_time and ended_time are HH:mm strings in the workspace timezone. They are not ISO timestamps. Running timers expose exact elapsed state through timer_started_at and calculated duration fields.
  • IDs: Keito returns database IDs such as cm...; do not assume IDs use short prefixes like prj_ or co_.
  • Pagination: collection endpoints use page and per_page. Responses include page, per_page, total_pages, total_entries, and links.
  • Time entry source: source can be web, cli, api, agent, calendar, or desktop.
  • Expense source: expense source can be web, cli, api, or agent.
  • Metadata: metadata must be a JSON object and is limited to 4KB.
  • Capabilities: API responses include X-Keito-Features. Clients can use this header to detect capabilities such as project-task-budgets, timer-stop, timer-restart, invoice-line-item-edit, and invoice-pdf.
  • Concurrency: client and project item reads return ETag. Send it as If-Match on later mutations; permanent deletion requires it.
  • Idempotency: client and project mutations accept Idempotency-Key for safe retries. Keys are authorization-bound and retained for 24 hours.
  • Caching: credential-dependent API responses are private, no-store and vary by authorization and account headers.

Endpoints

Method Endpoint Description
GET /api/v2/users/me Current identity; response shape depends on credential type
GET /api/v2/projects List projects
POST /api/v2/projects Create a project
GET /api/v2/projects/:id Get a visible project
PATCH /api/v2/projects/:id Update, archive, or restore a project
DELETE /api/v2/projects/:id Permanently delete an archived project (Owner/Administrator only)
GET /api/v2/tasks List task definitions or tasks assigned to project_id; unavailable to personal sync keys
GET /api/v2/time_entries List time entries
POST /api/v2/time_entries Create a time entry
PATCH /api/v2/time_entries/:id Update a time entry
PATCH /api/v2/time_entries/:id/stop Stop a running time entry
PATCH /api/v2/time_entries/:id/restart Restart a stopped time entry
DELETE /api/v2/time_entries/:id Delete a time entry
GET /api/v2/expenses List expenses
POST /api/v2/expenses Create an expense
GET /api/v2/clients List clients
POST /api/v2/clients Create a client
GET /api/v2/clients/:id Get a client
PATCH /api/v2/clients/:id Update, archive, or restore a client
DELETE /api/v2/clients/:id Permanently delete an archived client (Owner/Administrator only)
GET /api/v2/contacts List contacts
POST /api/v2/contacts Create a contact
GET /api/v2/invoices List invoices
POST /api/v2/invoices Create an invoice, optionally from tracked time and expenses
GET /api/v2/invoices/:id Get an invoice
PATCH /api/v2/invoices/:id Update a draft invoice and existing line items
DELETE /api/v2/invoices/:id Delete a draft invoice
GET /api/v2/invoices/:id/pdf Download the rendered invoice PDF
GET /api/v2/invoices/:id/messages List invoice send history
POST /api/v2/invoices/:id/messages Send an invoice, reminder, or thank-you
GET /api/v2/reports/time/team Team time report

See the Clients API, Projects API, and Invoices API for mutation contracts and safe examples.

Common Query Parameters

Parameter Type Description
page number Page number, starting at 1
per_page number Results per page, default 100, max 2000
source string Filter by source. Time entries support web, cli, api, agent, calendar, and desktop; expenses support web, cli, api, and agent.
project_id string Filter by project
task_id string Filter by task
user_id string Filter by user
client_id string Filter by client
from string Start date
to string End date
updated_since string ISO timestamp lower bound

Example

curl "https://app.keito.ai/api/v2/time_entries?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer kto_xxxxx" \
  -H "Keito-Account-Id: your_company_id"