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

```json
{
  "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.