HumanHours API

HumanHours API as documented publicly: 13 operations. Contract generated from the documentation by API Evangelist (2026-11-11); not the provider's own document.

GitHub OpenAPI

Operations 13

GET /api/v1/reports/cost-saved GET /api/v1/reports/cost-saved #
POST /api/v1/track POST /api/v1/track #
GET /v1/reports/cost-saved GET /v1/reports/cost-saved #
GET /v1/reports/export Same shape as time-saved but always emits CSV with a Content-Disposition: attachment header. #
GET /v1/reports/leaderboard GET /v1/reports/leaderboard #
GET /v1/reports/time-saved GET /v1/reports/time-saved #
GET /v1/reports/usage Open to all plans. Returns the org's current period state. #
GET /v1/task-types GET /v1/task-types #
POST /v1/task-types POST /v1/task-types #
DELETE /v1/task-types/{key} Archives a custom task type (soft delete). #
POST /v1/task-types/{key}/override Override a built-in baseline for your workspace. #
POST /v1/track Record a single agent task. #
POST /v1/webhooks POST /v1/webhooks #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/humanhours-dev:humanhours-dev-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

humanhours-dev-openapi-generated.yml Raw ↑
openapi: 3.1.0
info:
  title: HumanHours API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 13 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; HumanHours has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 9
    documentation: 4
    pages-with-code: 6
    pages-read: 8
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://humanhours.dev/docs/api/track
  - https://humanhours.dev/docs/api/reports
  - https://humanhours.dev/docs/api/webhooks
  - https://humanhours.dev/docs/api/task-types
  - https://humanhours.dev/api/docs-raw/api/track
  - https://humanhours.dev/api/docs-raw/model-cost
  - https://humanhours.dev/api/docs-raw/quickstart
  - https://humanhours.dev/api/docs-raw/api/reports
paths:
  /api/v1/reports/cost-saved:
    get:
      operationId: get_api_v1_reports_cost_saved
      tags:
      - Api
      summary: GET /api/v1/reports/cost-saved
      x-source: https://humanhours.dev/api/docs-raw/model-cost
      parameters:
      - name: group_by
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl "https://humanhours.dev/api/v1/reports/cost-saved?group_by=model"  -H "Authorization: Bearer $HUMANHOURS_API_KEY"

          ```'
  /api/v1/track:
    post:
      operationId: post_api_v1_track
      tags:
      - Api
      summary: POST /api/v1/track
      x-source: https://humanhours.dev/api/docs-raw/model-cost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1TrackRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1TrackResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://humanhours.dev/api/v1/track  -H \"Authorization: Bearer $HUMANHOURS_API_KEY\"  -H \"Content-Type: application/json\"\
          \  -d '{\n    \"agent_id\": \"support-classifier\",\n    \"task_type\": \"email_classification\",\n    \"outcome\": \"success\",\n \
          \   \"agent_duration_seconds\": 4,\n    \"model\": \"anthropic/claude-opus-4.8\",\n    \"tokens_in\": 1800,\n    \"tokens_out\": 120\n\
          \  }'\n```"
  /v1/reports/cost-saved:
    get:
      operationId: get_v1_reports_cost_saved
      tags:
      - Reports
      summary: GET /v1/reports/cost-saved
      x-source: https://humanhours.dev/docs/api/reports
      parameters:
      - name: group_by
        in: query
        required: false
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReportsCostSavedResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://humanhours.dev/v1/reports/cost-saved?period=30d&group_by=client\"  -H \"Authorization: Bearer $HUMANHOURS_API_KEY\
          \ \" \n net_saved = cost_saved - agent_cost . Useful for finance views: \"we saved €18k of human time but spent €1.2k on inference,\
          \ net €16.8k\". \n GET /v1/reports/leaderboard \n Rank agents by a single metric. \n Param \n Default \n Values \n metric \n hours_saved\
          \ \n hours_saved , cost"
  /v1/reports/export:
    get:
      operationId: get_v1_reports_export
      tags:
      - Reports
      summary: 'Same shape as time-saved but always emits CSV with a Content-Disposition: attachment header.'
      description: Exports the time‑saved report as a downloadable CSV file.
      x-source: https://humanhours.dev/docs/api/reports
      parameters:
      - name: period
        in: query
        required: false
        schema:
          type: string
        description: Time period for the export (default 30d).
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
        description: Filter to one agent.
      - name: task_type
        in: query
        required: false
        schema:
          type: string
        description: Filter to one task type.
      - name: group_by
        in: query
        required: false
        schema:
          type: string
        description: Comma‑list of dimensions (agent, task_type, client, day, week, month).
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: Metric to sort by (hours_saved, cost_saved, events).
      - name: top
        in: query
        required: false
        schema:
          type: string
        description: Limit to top N rows.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReportsExportResponse'
      x-evidence:
        kind: documentation
  /v1/reports/leaderboard:
    get:
      operationId: get_v1_reports_leaderboard
      tags:
      - Reports
      summary: GET /v1/reports/leaderboard
      x-source: https://humanhours.dev/docs/api/reports
      parameters:
      - name: metric
        in: query
        required: false
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReportsLeaderboardResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://humanhours.dev/v1/reports/leaderboard?metric=cost_saved&period=90d\"  -H \"Authorization: Bearer $HUMANHOURS_API_KEY\
          \ \" \n GET /v1/reports/export \n Same shape as time-saved but always emits CSV with a Content-Disposition: attachment header so a browser\
          \ downloads instead of rendering. Convenient for \"send the CFO the spreadsheet\" flows. \n GET /v1/reports/usage \n Open to all plans.\
          \ Returns"
  /v1/reports/time-saved:
    get:
      operationId: get_v1_reports_time_saved
      tags:
      - Reports
      summary: GET /v1/reports/time-saved
      x-source: https://humanhours.dev/docs/api/reports
      parameters:
      - name: group_by
        in: query
        required: false
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
      - name: sort
        in: query
        required: false
        schema:
          type: string
      - name: top
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReportsTimeSavedResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://humanhours.dev/v1/reports/time-saved?period=30d&group_by=agent,task_type&sort=hours_saved&top=20\"  -H \"Authorization:\
          \ Bearer $HUMANHOURS_API_KEY \" \n GET /v1/reports/cost-saved \n Cost saved + agent cost + net saved. Same dimensions as /time-saved\
          \ ; default sort is cost_saved . "
  /v1/reports/usage:
    get:
      operationId: get_v1_reports_usage
      tags:
      - Reports
      summary: Open to all plans. Returns the org's current period state.
      description: Provides usage statistics for the organization.
      x-source: https://humanhours.dev/docs/api/reports
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReportsUsageResponse'
      x-evidence:
        kind: documentation
  /v1/task-types:
    get:
      operationId: get_v1_task_types
      tags:
      - Task Types
      summary: GET /v1/task-types
      x-source: https://humanhours.dev/docs/api/task-types
      parameters:
      - name: category
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://humanhours.dev/v1/task-types?category=support  -H \"Authorization: Bearer $HUMANHOURS_API_KEY \" \n Open to all\
          \ plans (read). \n POST /v1/task-types \n Create a custom task type. The key is a lowercase snake_case identifier you'll send in /v1/track\
          \ calls. "
    post:
      operationId: post_v1_task_types
      tags:
      - Task Types
      summary: POST /v1/task-types
      x-source: https://humanhours.dev/docs/api/task-types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TaskTypesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://humanhours.dev/v1/task-types  -H \"Authorization: Bearer $HUMANHOURS_API_KEY \"  -H \"Content-Type: application/json\"\
          \  -d '{ \n \"key\": \"saas_lead_qualification\", \n \"display_name\": \"SaaS lead qualification\", \n \"category\": \"sales\", \n \"\
          default_baseline_minutes\": 12, \n \"baseline_source\": \"Internal SDR benchmark, 2026-Q1\" \n }' \n The key must not collide with a\
          \ built-in or another custo"
  /v1/task-types/{key}:
    delete:
      operationId: delete_v1_task_types_key
      tags:
      - Task Types
      summary: Archives a custom task type (soft delete).
      x-source: https://humanhours.dev/docs/api/task-types
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/task-types/{key}/override:
    post:
      operationId: post_v1_task_types_key_override
      tags:
      - Task Types
      summary: Override a built-in baseline for your workspace.
      x-source: https://humanhours.dev/docs/api/task-types
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TaskTypesKeyOverrideRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/track:
    post:
      operationId: post_v1_track
      tags:
      - Track
      summary: Record a single agent task.
      description: Record a single agent task. Returns the stored event with computed hours_saved, cost_saved, and net_saved.
      x-source: https://humanhours.dev/docs/api/track
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TrackRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1TrackResponse'
      x-evidence:
        kind: documentation
  /v1/webhooks:
    post:
      operationId: post_v1_webhooks
      tags:
      - Webhooks
      summary: POST /v1/webhooks
      x-source: https://humanhours.dev/docs/api/webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1WebhooksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://humanhours.dev/v1/webhooks  -H \"Authorization: Bearer $HUMANHOURS_API_KEY \"  -H \"Content-Type: application/json\"\
          \  -d '{ \n \"url\": \"https://your-stack.example/webhooks/humanhours\", \n \"event_types\": [\"event.created\", \"weekly.digest\"],\
          \ \n \"description\": \"Production hook\" \n }' \n The response includes the webhook secret . It's shown once. Store it; you'll use\
          \ it to verify signatures."
components:
  schemas:
    PostApiV1TrackRequest:
      type: object
      properties:
        agent_id:
          type: string
        task_type:
          type: string
        outcome:
          type: string
        agent_duration_seconds:
          type: integer
        model:
          type: string
        tokens_in:
          type: integer
        tokens_out:
          type: integer
    PostApiV1TrackResponse:
      type: object
      properties:
        cost_saved:
          type: number
        agent_cost:
          type: number
        resolved_cost_source:
          type: string
        net_saved:
          type: number
        currency:
          type: string
    GetV1ReportsCostSavedResponse:
      type: object
      properties:
        plan:
          type: string
        currency:
          type: string
        events_this_month:
          type: integer
        events_included_in_plan:
          type: integer
        overage_events:
          type: integer
        lifetime_events:
          type: integer
        projected_overage_eur:
          type:
          - string
          - 'null'
    GetV1ReportsExportResponse:
      type: object
      properties:
        CSV content:
          type: string
          description: UTF‑8 CSV payload with header row.
    GetV1ReportsLeaderboardResponse:
      type: object
      properties:
        plan:
          type: string
        currency:
          type: string
        events_this_month:
          type: integer
        events_included_in_plan:
          type: integer
        overage_events:
          type: integer
        lifetime_events:
          type: integer
        projected_overage_eur:
          type:
          - string
          - 'null'
    GetV1ReportsTimeSavedResponse:
      type: object
      properties:
        plan:
          type: string
        currency:
          type: string
        events_this_month:
          type: integer
        events_included_in_plan:
          type: integer
        overage_events:
          type: integer
        lifetime_events:
          type: integer
        projected_overage_eur:
          type:
          - string
          - 'null'
    GetV1ReportsUsageResponse:
      type: object
      properties:
        plan:
          type: string
        currency:
          type: string
        events_this_month:
          type: integer
        events_included_in_plan:
          type: integer
        overage_events:
          type: integer
        lifetime_events:
          type: integer
        projected_overage_eur:
          type: number
          description: Null when no overage is forecast.
    PostV1TaskTypesRequest:
      type: object
      properties:
        key:
          type: string
        display_name:
          type: string
        category:
          type: string
        default_baseline_minutes:
          type: integer
        baseline_source:
          type: string
    PostV1TaskTypesKeyOverrideRequest:
      type: object
      properties:
        baseline_minutes_override:
          type: number
          description: New baseline in minutes.
        reason:
          type: string
          description: Reason for the override.
      required:
      - baseline_minutes_override
      - reason
    PostV1TrackRequest:
      type: object
      properties:
        agent_id:
          type: string
          description: your stable id
        task_type:
          type: string
          description: see /docs/api/task-types
        outcome:
          type: string
          description: '"success" | "failure" | "needs_review"'
        agent_duration_seconds:
          type: number
          description: wall-clock seconds the agent took
        agent_cost:
          type: number
          description: cost of the agent run, in org currency
        model:
          type: string
          description: model id; ideally the OpenRouter id, e.g. "anthropic/claude-opus-4.8"
        tokens_in:
          type: number
          description: input/prompt tokens for this run
        tokens_out:
          type: number
          description: output/completion tokens for this run
        human_baseline_minutes:
          type: number
          description: overrides task_type default for this event only
        metadata:
          type: object
          description: free-form, indexed for /v1/reports
        audit_sample:
          type: object
        audit_sample.input_excerpt:
          type: string
          description: up to 2000 chars
        audit_sample.output_excerpt:
          type: string
          description: up to 2000 chars
        audit_sample.model:
          type: string
        audit_sample.tokens_in:
          type: number
        audit_sample.tokens_out:
          type: number
        occurred_at:
          type: string
          description: ISO 8601, defaults to receipt time
      required:
      - agent_id
      - task_type
    PostV1TrackResponse:
      type: object
      properties:
        event_id:
          type: string
        agent_id:
          type: string
        task_type:
          type: string
        outcome:
          type: string
        resolved_baseline_minutes:
          type: number
        resolved_baseline_source:
          type: string
        resolved_hourly_rate:
          type: number
        currency:
          type: string
        agent_duration_seconds:
          type: number
        hours_saved:
          type: number
        cost_saved:
          type: number
        agent_cost:
          type: string
        resolved_cost_source:
          type: string
        net_saved:
          type: number
        occurred_at:
          type: string
    PostV1WebhooksRequest:
      type: object
      properties:
        url:
          type: string
        event_types:
          type: array
          items:
            type: string
        description:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Reports
- name: Task Types
- name: Track
- name: Webhooks