ringahuman-com API

openapi: 3.1.0
info:
  title: ringahuman-com API
  version: '2026-10-31'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-31: 17 operation(s) read from 12 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; ringahuman-com has published no machine-readable contract
    that the pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 5
    documentation: 12
    pages-with-code: 6
    pages-read: 12
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-31'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://ringahuman.com/docs/sandbox
  - https://ringahuman.com/docs/webhooks
  - https://ringahuman.com/docs/quickstart
  - https://ringahuman.com/docs/create-call-task
  - https://ringahuman.com/integrations
  - https://ringahuman.com/llms.txt
  - https://ringahuman.com/docs/tasks
  - https://ringahuman.com/docs/do-not-call
  - https://ringahuman.com/docs/lead-intake
  - https://ringahuman.com/docs/recipes
  - https://ringahuman.com/how-it-works
  - https://ringahuman.com/skills/ringahuman/SKILL.md
servers:
- url: https://api.ringahuman.com
paths:
  /api/billing:
    get:
      operationId: get_api_billing
      tags:
      - Api
      summary: Get free calls remaining, whether a card is on file, pricing, and whether new tasks will dispatch.
      x-source: https://ringahuman.com/llms.txt
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiBillingResponse'
      x-evidence:
        kind: documentation
  /api/billing/checkout:
    post:
      operationId: post_api_billing_checkout
      tags:
      - Api
      summary: Create a checkout link for a billing plan.
      x-source: https://ringahuman.com/llms.txt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiBillingCheckoutRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiBillingCheckoutResponse'
      x-evidence:
        kind: documentation
  /api/dnc:
    post:
      operationId: post_api_dnc
      tags:
      - Api
      summary: Put a number on your account's do-not-call list.
      x-source: https://ringahuman.com/llms.txt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiDncRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiDncResponse'
      x-evidence:
        kind: documentation
  /api/hooks:
    get:
      operationId: get_api_hooks
      tags:
      - Api
      summary: List all account-wide webhook subscriptions.
      x-source: https://ringahuman.com/docs/webhooks
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiHooksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_hooks
      tags:
      - Api
      summary: Create an account-wide webhook subscription to receive outcomes for all tasks.
      x-source: https://ringahuman.com/docs/webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiHooksRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiHooksResponse'
      x-evidence:
        kind: documentation
  /api/hooks/{id}:
    delete:
      operationId: delete_api_hooks_id
      tags:
      - Api
      summary: Unsubscribe and remove a webhook subscription.
      x-source: https://ringahuman.com/docs/webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/intake/rah_in_…:
    post:
      operationId: post_api_intake_rah_in
      tags:
      - Api
      summary: POST /api/intake/rah_in_…
      x-source: https://ringahuman.com/docs/lead-intake
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiIntakeRahInRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiIntakeRahInResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://ringahuman.com/api/intake/rah_in_…  -H \"content-type: application/json\"  -d '{\"name\":\"Maria Lopez\"\
          ,\"phone\":\"(512) 555-0142\",\"company\":\"Bright Smile Dental\",\"state\":\"TX\",\"message\":\"Do you work with dental offices?\"\
          }'\n→ 201 { \"ok\": true, \"task_id\": \"task_…\", \"status\": \"open\" } \n Works with \n Source Where to paste the URL \n Google Ads\
          \ lead form Lead form asset → Lead delivery → W"
  /api/sandbox/tasks:
    get:
      operationId: get_api_sandbox_tasks
      tags:
      - Api
      summary: List sandbox call tasks.
      x-source: https://ringahuman.com/docs/sandbox
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiSandboxTasksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_sandbox_tasks
      tags:
      - Api
      summary: POST /api/sandbox/tasks
      x-source: https://ringahuman.com/docs/sandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSandboxTasksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://ringahuman.com/api/sandbox/tasks  -H \"Content-Type: application/json\"  -d '{\"phone\":\"(512) 555-0100\"\
          ,\"state\":\"TX\",\"consent\":\"inquiry\",\n \"business_name\":\"Bright Smile Dental\",\"goal\":\"Book a 15-minute call\",\n \"brief\"\
          :\"They ran our grader 6 minutes ago and scored 41/100…\"}'"
  /api/sandbox/tasks/{id}:
    get:
      operationId: get_api_sandbox_tasks_id
      tags:
      - Api
      summary: Get details of a specific sandbox call task by ID.
      x-source: https://ringahuman.com/docs/sandbox
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiSandboxTasksIdResponse'
      x-evidence:
        kind: documentation
  /api/sandbox/tasks/{id}/cancel:
    post:
      operationId: post_api_sandbox_tasks_id_cancel
      tags:
      - Api
      summary: Cancel a sandbox call task.
      x-source: https://ringahuman.com/docs/sandbox
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiSandboxTasksIdCancelResponse'
      x-evidence:
        kind: documentation
  /api/signup:
    post:
      operationId: post_api_signup
      tags:
      - Api
      summary: POST /api/signup
      x-source: https://ringahuman.com/docs/quickstart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSignupRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://ringahuman.com/api/signup  -H "Content-Type: application/json"  -d ''{"email":"you@company.com","company":"Acme"}'''
  /api/tasks:
    get:
      operationId: get_api_tasks
      tags:
      - Api
      summary: Get recent tasks.
      x-source: https://ringahuman.com/llms.txt
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiTasksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_tasks
      tags:
      - Api
      summary: POST /api/tasks
      x-source: https://ringahuman.com/docs/quickstart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiTasksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://ringahuman.com/api/tasks  -H \"Authorization: Bearer $RINGAHUMAN_API_KEY\"  -H \"Content-Type: application/json\"\
          \  -d '{\n \"phone\": \"512-555-0142\",\n \"state\": \"TX\",\n \"consent\": \"inquiry\",\n \"business_name\": \"Bright Smile Dental\"\
          ,\n \"goal\": \"Book a 15-minute call to walk through their site grade\",\n \"brief\": \"You are calling on behalf of Acme about the\
          \ website grade they ran at 10:02…\","
  /api/tasks/{id}:
    get:
      operationId: get_api_tasks_id
      tags:
      - Api
      summary: Retrieve a task to check its outcome and audit trail.
      x-source: https://ringahuman.com/docs/webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiTasksIdResponse'
      x-evidence:
        kind: documentation
  /api/tasks/{id}/cancel:
    post:
      operationId: post_api_tasks_id_cancel
      tags:
      - Api
      summary: Pull a call before anyone dials.
      x-source: https://ringahuman.com/llms.txt
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiTasksIdCancelResponse'
      x-evidence:
        kind: documentation
  /skills/ringahuman/SKILL.md:
    get:
      operationId: get_skills_ringahuman_SKILL_md
      tags:
      - Skills
      summary: Download agent skill instructions for teaching Claude Code when and how to use Ring a Human.
      x-source: https://ringahuman.com/integrations
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiBillingResponse:
      type: object
      properties:
        free_calls:
          type: integer
          description: Free calls remaining
        card_on_file:
          type: boolean
          description: Whether a card is on file
        pricing:
          type: object
          description: Pricing information
        dispatch_enabled:
          type: boolean
          description: Whether new tasks will dispatch
    PostApiBillingCheckoutRequest:
      type: object
      properties:
        plan:
          type: string
          description: 'One of: payg, starter, growth, scale'
      required:
      - plan
    PostApiBillingCheckoutResponse:
      type: object
      properties:
        checkout_url:
          type: string
          description: Stripe Checkout URL
    PostApiDncRequest:
      type: object
      properties:
        phone:
          type: string
      required:
      - phone
    PostApiDncResponse:
      type: object
      properties:
        success:
          type: boolean
    GetApiHooksResponse:
      type: object
      properties:
        id:
          type: string
        target_url:
          type: string
        event:
          type: string
    PostApiHooksRequest:
      type: object
      properties:
        target_url:
          type: string
          description: HTTPS URL where webhooks will be delivered
        event:
          type: string
          description: Event type to subscribe to (e.g., task.completed)
      required:
      - target_url
      - event
    PostApiHooksResponse:
      type: object
      properties:
        id:
          type: string
        target_url:
          type: string
        event:
          type: string
    PostApiIntakeRahInRequest:
      type: object
      properties:
        name:
          type: string
        phone:
          type: string
        company:
          type: string
        state:
          type: string
        message:
          type: string
    PostApiIntakeRahInResponse:
      type: object
      properties:
        ok:
          type: boolean
        task_id:
          type: string
        status:
          type: string
    GetApiSandboxTasksResponse:
      type: object
      properties:
        tasks:
          type: array
          description: List of sandbox tasks
    PostApiSandboxTasksRequest:
      type: object
      properties:
        phone:
          type: string
        state:
          type: string
        consent:
          type: string
        business_name:
          type: string
        goal:
          type: string
        brief:
          type: string
    GetApiSandboxTasksIdResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the task
        outcome:
          type: object
          description: Outcome of the call
        sandbox:
          type: boolean
          description: Indicates this is a sandbox task
        calling_window:
          type: object
          description: Calling window information if task is outside calling hours
    PostApiSandboxTasksIdCancelResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the cancelled task
    PostApiSignupRequest:
      type: object
      properties:
        email:
          type: string
        company:
          type: string
    GetApiTasksResponse:
      type: object
      properties:
        tasks:
          type: array
          description: List of recent call tasks
    PostApiTasksRequest:
      type: object
      properties:
        phone:
          type: string
        state:
          type: string
        consent:
          type: string
        business_name:
          type: string
        goal:
          type: string
        brief:
          type: string
        deadline_minutes:
          type: integer
        webhook_url:
          type: string
    GetApiTasksIdResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        external_ref:
          type: string
        outcome:
          type: object
    PostApiTasksIdCancelResponse:
      type: object
      properties:
        task:
          type: object
          description: The cancelled call task
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Skills