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.

Download the OpenAPI v2 specification for the machine-readable API contract.

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.

A personal read-only sync key permits eight requests, including the Business-only own-schedule endpoint when authorized, returns /users/me without company, and cannot call /tasks or write data. For CLI or writes, eligible Members and Managers can create a new key under Personal API keys, choosing All permitted operations. Administrators issue keys for other members or Agents. Keys follow current permissions and record access; existing read-only keys and rotations remain read-only. 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, project-assignments-v1, time-approvals-v1, financial-reports-v1, timer-stop, timer-restart, invoice-line-item-edit, invoice-payments, 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 and invoice payment creation 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 POST PATCH DELETE	/api/v2/projects/:id/user_assignments	Manage a project’s team (details)
GET POST PATCH DELETE	/api/v2/projects/:id/task_assignments	Manage a project’s tasks, task budgets, and rates (details)
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
DELETE	/api/v2/time_entries/:id/external_reference	Remove a time entry’s external reference
POST	/api/v2/approvals/submit	Submit your own time for approval
POST	/api/v2/approvals/approve	Approve a person’s submitted time and expenses
POST	/api/v2/approvals/reject	Reject a person’s submitted time and expenses
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
POST	/api/v2/invoices/:id/payments	Record a partial or full invoice payment
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, resend, or mark an invoice as sent; send reminders and thank-yous
GET	/api/v2/reports/project_budget	Harvest-compatible project budget report
GET	/api/v2/reports/uninvoiced	Harvest-compatible date-filtered uninvoiced report
GET	/api/v2/reports/time/team	Team time report
GET	/api/v2/reports/time/clients	Harvest-compatible time report by client
GET	/api/v2/reports/time/projects	Harvest-compatible time report by project
GET	/api/v2/reports/time/tasks	Harvest-compatible time report by task
GET	/api/v2/backup/retainers	Owner/administrator export of raw retainers and activity; see Workspace Backups

See the Clients API, Projects API, Timesheet Approvals API, Invoices API, and Reports API for endpoint contracts and safe examples.

Common Query Parameters

Supported parameters vary by endpoint. In particular, workspace backup resources accept only page and per_page; the filters below are not a shared contract for every route. Project budget and uninvoiced reports default to 2000 projects per page, time reports default to 100 rows per page, while backup pages default to 100 parent records and are capped at 500.

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
invoice_id	string	Filter time entries or expenses linked to a Keito invoice; unavailable to personal sync keys. See Time Entries and Expenses.
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"

Planning

Planning API covers private own-schedule reads, revision-checked assignment writes and signed change events. All planning endpoints require Business; personal access is controlled separately from team Plan visibility.