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
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

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.