Concepts

Key concepts for working with the Keito API.

Time Entries

A time entry records work done by a human or agent. Key fields:

Field	Type	Description
`id`	string	Unique identifier
`project_id`	string	The project this work is for
`task_id`	string	The task within the project (optional)
`user_id`	string	The human or agent user
`spent_date`	string	Date the work was performed (YYYY-MM-DD)
`hours`	number	Duration in decimal hours
`notes`	string	Description of work done
`is_running`	boolean	Whether a timer is currently active
`is_billable`	boolean	Whether this entry is billable
`source`	string	Origin: `web`, `cli`, `api`, `agent`, `calendar`, `desktop`
`metadata`	object	Agent context (JSON, max 4KB)

Expenses

An expense records a cost against a project. For agent work, this is typically LLM token usage.

Field	Type	Description
`id`	string	Unique identifier
`project_id`	string	The project this cost is for
`expense_category_id`	string	Category (e.g., “LLM Usage”)
`spent_date`	string	Date of the expense (YYYY-MM-DD)
`units`	number	Quantity (e.g., tokens in thousands)
`unit_price`	number	Price per unit
`total_cost`	number	Calculated total
`notes`	string	Description
`source`	string	Origin: `web`, `cli`, `api`, `agent`
`metadata`	object	Agent context (JSON, max 4KB)

Users

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Display name
`email`	string	Email (agents may use placeholder)
`user_type`	string	`human` or `agent`
`is_active`	boolean	Whether the user is active

Source Values

Source	Created By	Badge Colour
`web`	Keito web app	None
`cli`	Keito CLI	Amber
`api`	Direct REST API call	None
`agent`	AI agent via API or SDK	Violet
`calendar`	Calendar import	Indigo
`desktop`	Keito desktop app	Emerald

Time entries support all source values above. Expenses currently support web, cli, api, and agent.

Metadata Schema

The metadata field is a freeform JSON object (max 4KB). Recommended fields for agent entries:

{
  "agent_id": "string — unique identifier for this agent",
  "agent_type": "string — platform: claude-code, codex, cursor, etc.",
  "session_id": "string — UUID grouping related entries",
  "model": "string — LLM model used",
  "input_tokens": "number — input tokens consumed (expenses only)",
  "output_tokens": "number — output tokens consumed (expenses only)"
}

Use session_id to correlate a time entry with its corresponding LLM expense.