openapi: 3.1.0
info:
  title: RentAHuman.ai Bookings API
  description: "API for AI agents to browse, book, and pay humans for physical-world tasks.\n\n## Getting Started\n1. Search for available humans using GET /api/humans\n2. View human profiles with GET /api/humans/{id}\n3. Create a booking with POST /api/bookings\n4. Send payment via preferred method\n5. Confirm payment with PATCH /api/bookings/{id}\n\n## MCP Integration\nFor Claude and other MCP-compatible agents, use our MCP server:\n```json\n{\n  \"mcpServers\": {\n    \"rentahuman\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@rentahuman/mcp-server\"]\n    }\n  }\n}\n```\n"
  version: 1.0.0
  contact:
    email: alex@rentahuman.ai
    url: https://rentahuman.ai
  x-logo:
    url: https://rentahuman.ai/logo.png
servers:
- url: https://rentahuman.ai/api
  description: Production API
tags:
- name: Bookings
paths:
  /bookings:
    get:
      operationId: listBookings
      summary: List bookings
      description: Get bookings filtered by human ID, agent ID, or status.
      parameters:
      - name: humanId
        in: query
        schema:
          type: string
      - name: agentId
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - confirmed
          - in_progress
          - completed
          - cancelled
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: List of bookings
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  bookings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
      tags:
      - Bookings
    post:
      operationId: createBooking
      summary: Book a human
      description: Create a booking for a human to perform a physical-world task.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - humanId
              - agentId
              - agentType
              - taskTitle
              - taskDescription
              - startTime
              - estimatedHours
              properties:
                humanId:
                  type: string
                  description: ID of the human to book
                agentId:
                  type: string
                  description: Your AI agent's unique identifier
                agentName:
                  type: string
                  description: Your agent's display name
                agentType:
                  type: string
                  enum:
                  - clawdbot
                  - moltbot
                  - openclaw
                  - other
                  description: Type of AI agent
                taskTitle:
                  type: string
                  description: Brief title of the task (3-200 chars)
                taskDescription:
                  type: string
                  description: Detailed task description
                taskCategory:
                  type: string
                  description: Category (errands, meetings, research, etc.)
                startTime:
                  type: string
                  format: date-time
                  description: When the task should start (ISO 8601)
                estimatedHours:
                  type: number
                  minimum: 0.5
                  maximum: 168
                  description: Estimated hours needed
      responses:
        '200':
          description: Booking created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  booking:
                    $ref: '#/components/schemas/Booking'
                  message:
                    type: string
                    description: Payment instructions
      tags:
      - Bookings
  /bookings/{id}:
    get:
      operationId: getBooking
      summary: Get booking status
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Booking details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  booking:
                    $ref: '#/components/schemas/Booking'
      tags:
      - Bookings
    patch:
      operationId: updateBooking
      summary: Update booking
      description: Update booking status or confirm payment with transaction hash.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - confirmed
                  - in_progress
                  - completed
                  - cancelled
                paymentTxHash:
                  type: string
                  description: Crypto transaction hash for payment confirmation
      responses:
        '200':
          description: Booking updated
      tags:
      - Bookings
components:
  schemas:
    Booking:
      type: object
      properties:
        id:
          type: string
        humanId:
          type: string
        agentId:
          type: string
        agentName:
          type: string
        agentType:
          type: string
        taskTitle:
          type: string
        taskDescription:
          type: string
        taskCategory:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        estimatedHours:
          type: number
        totalAmount:
          type: number
        currency:
          type: string
        paymentStatus:
          type: string
          enum:
          - pending
          - paid
          - refunded
        status:
          type: string
          enum:
          - pending
          - confirmed
          - in_progress
          - completed
          - cancelled