Quickstart

Create your first time entry with Keito API v2.

Prerequisites

  • A Keito company.
  • A full-access integration key from Settings -> API & Developers. A workspace Administrator must create this separate key and bind it to the human or Agent identity that will make the requests.
  • The Company ID shown in Settings -> API & Developers -> Company ID.
  • A project ID and a task assigned to that project. Use /api/v2/projects, then /api/v2/tasks?project_id=<project_id>, to discover them.

The Personal read-only sync key cannot be used for this quickstart. Its fixed seven-endpoint allowlist does not include /api/v2/tasks or any write operation, and its /api/v2/users/me response intentionally omits company. There is no setting that upgrades that key; ask a workspace Administrator to create a separate full-access integration key. See Personal Read-Only Sync Keys for its supported operations.

Step 1: Export Credentials

export KEITO_API_KEY="kto_xxxxx"
export KEITO_ACCOUNT_ID="your_company_id"

KEITO_ACCOUNT_ID is sent as the Keito-Account-Id header.

Step 2: Verify Authentication

curl "https://app.keito.ai/api/v2/users/me" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

With a full-access integration key, the response includes your user profile and the resolved company.

Step 3: Discover Projects and Tasks

curl "https://app.keito.ai/api/v2/projects?is_active=true&per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

export KEITO_PROJECT_ID="project_id_from_the_projects_response"

curl "https://app.keito.ai/api/v2/tasks?project_id=$KEITO_PROJECT_ID&is_active=true&per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

Task definitions can be reused across the workspace, but Keito validates that the selected task is assigned to the selected project. Always discover tasks with project context before creating a time entry.

Step 4: Create a Time Entry

curl -X POST "https://app.keito.ai/api/v2/time_entries" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "project_id_here",
    "task_id": "task_id_here",
    "spent_date": "2026-05-05",
    "hours": 1.5,
    "notes": "Implemented OAuth flow",
    "source": "api",
    "metadata": {
      "session_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

CLI Alternative

The Keito CLI handles the API calls for you:

keito auth login
keito projects list --json
keito projects tasks "Acme Website" --json
keito time log --project "Acme Website" --task "Development" \
  --duration 1:30 \
  --date 2026-05-05 \
  --notes "Implemented OAuth flow"

For non-interactive environments, set KEITO_API_KEY and KEITO_ACCOUNT_ID instead of running keito auth login.

Log an LLM Expense

The API supports expense creation through /api/v2/expenses. The current CLI tracks time only, so use the API or web app for LLM cost expenses.

curl -X POST "https://app.keito.ai/api/v2/expenses" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "project_id_here",
    "expense_category_id": "llm_usage_category_id",
    "spent_date": "2026-05-05",
    "total_cost": 0.135,
    "notes": "LLM usage for implementation session",
    "source": "agent",
    "metadata": {
      "model": "claude-opus-4-6",
      "input_tokens": 30000,
      "output_tokens": 15000
    }
  }'

What’s Next?