call4me Requirements API

openapi: 3.2.0
info:
  title: call4me Requirements API
  version: 1.3.0
  description: 'Phone calls an AI agent places for its user: call a business, follow the call to its outcome, answer the caller''s questions mid-call, and patch the user in. Also the prepaid balance, the caller profile, scheduled calls, the account''s phone numbers and call recordings. The same operations as the MCP server at /mcp. Calls are billed per minute from pickup (phone menus and conversation; hold time at half price) from the prepaid balance; unanswered calls are free. Refusals name MCP tools (call4me_place_call is POST /api/calls, call4me_save_profile is PATCH /api/profile).'
  x-guidance: 'With a wallet and no account: POST /api/x402/calls with the call (to, business, goal, category, details, on_behalf_of, max_minutes) and pay the 402 in USDC on Base. A refusal (422 "Not calling yet") lists what to ask the user and takes no payment. The paid response returns the call id and an api_key; follow the call with GET /api/calls/{call_id}?wait_seconds=30 and Authorization: Bearer <api_key> until finished, answering open questions with POST /api/calls/{call_id}/answer. With an account: the bearer routes below, and GET /api to buy credits in USDC.'
  contact:
    name: call4me
    email: me@call4.me
    url: https://call4.me
servers:
- url: https://call4.me
tags:
- name: Requirements
paths:
  /api/requirements:
    get:
      operationId: listCallCategories
      description: The kinds of call (category slugs) call4me places. Each decides what must be known before dialing. Free.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The categories
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        slug:
                          type: string
                        name:
                          type: string
                        examples:
                          type: string
                      required:
                      - slug
                      - name
                      - examples
                      additionalProperties: {}
                required:
                - categories
                additionalProperties: {}
        '401':
          description: Request failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      tags:
      - Requirements
      summary: List call categories
      x-summary-source: derived
  /api/requirements/{category}:
    get:
      operationId: getCallRequirements
      description: The information a kind of call needs before dialing, and which of it the saved profile already has. Ask the user for every required field not known, in one message, then pass the answers in details when placing the call. Free.
      security:
      - bearerAuth: []
      parameters:
      - name: category
        in: path
        required: true
        description: a category slug from /api/requirements, e.g. "restaurant"
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          type: string
      responses:
        '200':
          description: What the call needs
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  category:
                    type: string
                  name:
                    type: string
                  fields:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                        required:
                          type: boolean
                        ask:
                          type: string
                        from_profile:
                          type:
                          - string
                          - 'null'
                        known:
                          type: boolean
                      required:
                      - key
                      - label
                      - required
                      - ask
                      - from_profile
                      - known
                      additionalProperties: {}
                required:
                - category
                - name
                - fields
                additionalProperties: {}
        '401':
          description: Request failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: Request failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      tags:
      - Requirements
      summary: Get call requirements
      x-summary-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A call4me API key or OAuth access token for the site or MCP resource.