needhuman-ai API

openapi: 3.1.0
info:
  title: needhuman-ai API
  version: '2026-10-30'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-30: 6 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; needhuman-ai has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 4
    documentation: 2
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-30'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://needhuman.ai/llms-full.txt
paths:
  /api/v1/health:
    get:
      operationId: get_api_v1_health
      tags:
      - Api
      summary: Health check. No auth required.
      x-source: https://needhuman.ai/llms-full.txt
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1HealthResponse'
      x-evidence:
        kind: documentation
  /api/v1/keys/register:
    post:
      operationId: post_api_v1_keys_register
      tags:
      - Api
      summary: POST /api/v1/keys/register
      x-source: https://needhuman.ai/llms-full.txt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1KeysRegisterRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1KeysRegisterResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://needhuman.ai/api/v1/keys/register  -H "Content-Type: application/json"  -d ''{"name": "my-agent"}''

          ```'
  /api/v1/setup:
    get:
      operationId: get_api_v1_setup
      tags:
      - Api
      summary: GET /api/v1/setup
      x-source: https://needhuman.ai/llms-full.txt
      parameters:
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -sf "https://needhuman.ai/api/v1/setup?key=YOUR_KEY" | bash

          ```'
  /api/v1/tasks:
    get:
      operationId: get_api_v1_tasks
      tags:
      - Api
      summary: List all tasks for your API key, newest first.
      x-source: https://needhuman.ai/llms-full.txt
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1TasksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_tasks
      tags:
      - Api
      summary: POST /api/v1/tasks
      x-source: https://needhuman.ai/llms-full.txt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1TasksRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1TasksResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://needhuman.ai/api/v1/tasks  -H "Authorization: Bearer nh_YOUR_KEY"  -H "Content-Type: application/json"  -d
          ''{"description": "Accept TOS at https://example.com/tos\n\nSTEPS:\n1. Go to the URL above\n2. Click Accept\n\nREPLY WITH:\n- Confirmation
          screenshot URL"}''

          ```'
  /api/v1/tasks/{taskId}:
    patch:
      operationId: patch_api_v1_tasks_taskId
      tags:
      - Api
      summary: Update a task (admin only). Used to record results and change status.
      x-source: https://needhuman.ai/llms-full.txt
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchApiV1TasksTaskidRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchApiV1TasksTaskidResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1HealthResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Health status
        timestamp:
          type: string
          description: ISO‑8601 timestamp
    PostApiV1KeysRegisterRequest:
      type: object
      properties:
        name:
          type: string
    PostApiV1KeysRegisterResponse:
      type: object
      properties:
        api_key:
          type: string
        credits_remaining:
          type: integer
        message:
          type: string
    GetApiV1TasksResponse:
      type: object
      properties:
        tasks:
          type: array
          description: Array of task objects (see Task object definition).
    PostApiV1TasksRequest:
      type: object
      properties:
        description:
          type: string
    PostApiV1TasksResponse:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
        action_type:
          type:
          - string
          - 'null'
        urgency:
          type: string
        status:
          type: string
        result:
          type:
          - string
          - 'null'
        proof_text:
          type:
          - string
          - 'null'
        proof_url:
          type:
          - string
          - 'null'
        api_key_id:
          type: string
        source:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
    PatchApiV1TasksTaskidRequest:
      type: object
      properties:
        status:
          type: string
          description: 'One of: pending, in_progress, completed, failed, expired'
        result:
          type: string
          description: Max 10000 chars. What the human did.
        proof_text:
          type: string
          description: Max 5000 chars. Worker's description of evidence.
        proof_url:
          type: string
          description: Max 2048 chars. Must start with http:// or https://.
        proof:
          type: object
          description: Max 4KB JSON object. Structured proof data.
      required:
      - status
    PatchApiV1TasksTaskidResponse:
      type: object
      properties:
        id:
          type: string
          description: UUID
        description:
          type: string
          description: What the human should do
        action_type:
          type: string
          description: Category (free‑text)
        urgency:
          type: string
          description: '"immediate" or "normal"'
        status:
          type: string
          description: '"pending", "in_progress", "completed", "failed", or "expired"'
        result:
          type: string
          description: What the human did
        proof_text:
          type: string
          description: Worker's description of evidence
        proof_url:
          type: string
          description: Link to screenshot or proof
        proof:
          type: object
          description: Structured proof data
        api_key_id:
          type: string
          description: ID of the API key that created this task
        source:
          type: string
          description: '"mcp" if created via NeedHuman MCP server, "api" otherwise'
        idempotency_key:
          type: string
          description: The Idempotency‑Key header value used when creating this task
        created_at:
          type: string
          description: '"YYYY-MM-DD HH:MM:SS"'
        completed_at:
          type: string
          description: Set when status reaches completed or failed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api