TimeHive
Get started
Docs API Reference

API Reference

Updated 2026-09-15

Ingestion API Reference

The Ingestion API is a fast, edge-optimized endpoint designed purely for appending events to your ledger.

Authentication (Ingestion)

All requests must include your integration-specific Ingest Token in the Authorization header using the Bearer schema.

POST https://api.timehive.io/ingest

Parameters (JSON Body):

  • task_id (string, optional): The full Task ID (UUID) of the task to log this event against. Required if the Integration does not have a Default Task. The task must belong to the integration's project.
  • event_type (string, optional): Defaults to run. Can also be output.
  • status (string, optional): Defaults to processed, which counts towards time saved. Pass failed if your automation errors out (logged, but no time saved). success and fail are accepted as aliases.
  • count (number, optional): Defaults to 1. Maps to run_count in the ledger, allowing you to batch multiple processing events (e.g., 50 records processed in one run) into a single API call.
  • idempotency_key (string, optional): A unique ID for this execution. See Idempotency for details.

Use the full Task ID. Open the task and click Copy task ID (or copy it from the integration page). It is a UUID such as 271a869c-316f-4568-9f1c-96fa01b297d8. The short tsk_271a86 label shown in the app is only a display tag and will be rejected.

Any additional keys passed in the JSON body are safely stored in the raw payload column for debugging purposes (subject to retention policies).

Client Stats API Reference

The Client Stats API allows you to programmatically fetch your organization's total metrics.

Authentication (Stats)

All requests must include your account-level Client Stats API Key in the Authorization header using the Bearer schema.

GET https://api.timehive.io/stats

Response Structure:

Returns a JSON object containing your account's high-level totals dynamically aggregated from the ledger, including breakdowns by time periods (today, yesterday, this week, last week, this month, last month):

{
  "success": true,
  "data": {
    "account_id": "your-account-uuid",
    "total_minutes_saved": 1250,
    "total_runs": 500,
    "total_events": 500,
    "total_outputs": 25,
    "today_minutes_saved": 60,
    "yesterday_minutes_saved": 120,
    "this_week_minutes_saved": 300,
    "last_week_minutes_saved": 500,
    "this_month_minutes_saved": 1250,
    "last_month_minutes_saved": 2000
  }
}

You can manage your API keys from the Settings > API keys page.