{
  "openapi": "3.1.0",
  "info": {
    "title": "I Am Your Human API",
    "version": "1.1.0",
    "summary": "Send real-world task requests from AI agents to a global community of real humans.",
    "description": "iamyourhuman.com is the email gateway between AI agents and a global community of real humans who help them in the physical world: in-person verification, errands, purchases and deliveries, phone calls, attending events, making physical things, expert judgment and human-in-the-loop sign-off. Contact: hello@iamyourhuman.com.\n\nEvery request is read by a human, who replies by email to `reply_to`. Not real-time. Rules of engagement: https://iamyourhuman.com/#rules",
    "contact": {
      "name": "I Am Your Human",
      "email": "hello@iamyourhuman.com",
      "url": "https://iamyourhuman.com/"
    }
  },
  "servers": [
    {
      "url": "https://iamyourhuman.com"
    }
  ],
  "externalDocs": {
    "description": "Full guide for agents",
    "url": "https://iamyourhuman.com/llms-full.txt"
  },
  "tags": [
    {
      "name": "requests"
    },
    {
      "name": "profile"
    }
  ],
  "paths": {
    "/api/v1/requests": {
      "post": {
        "operationId": "sendRequestToHuman",
        "tags": [
          "requests"
        ],
        "summary": "Send a task request to a human",
        "description": "Delivers the request to the community inbox and returns a request_id. A real person matches it with a human who can do it; that human replies by email. Nothing is agreed until confirmed in writing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanRequest"
              },
              "example": {
                "agent_name": "procurement-agent-7",
                "agent_platform": "example-agent-framework",
                "principal": "Acme Robotics (operations team)",
                "principal_contact": "ops@acme-robotics.example",
                "reply_to": "agent-inbox@acme-robotics.example",
                "category": "in_person_verification",
                "task": "Visit the electronics shop at the address in location, confirm it has at least 5 units of part XYZ-100 in stock and photograph the shelf label with the price.",
                "location": "12 Example Street, Example City",
                "deadline": "2026-11-20",
                "budget": "60 USD",
                "success_criteria": "Stock and price confirmed in person on or before the deadline.",
                "evidence_required": "Two timestamped photos and a 3-line written summary.",
                "language": "en"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Received and delivered (or queued) for human review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestReceipt"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body too large.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type must be application/json.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed; see errors.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; see Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; email hello@iamyourhuman.com directly.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/compose": {
      "post": {
        "operationId": "composeRequestEmail",
        "tags": [
          "requests"
        ],
        "summary": "Format a request as an email without sending it",
        "description": "Returns the subject, body and a mailto URL, for agents that send email with their own tools.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Formatted email.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComposedEmail"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/profile": {
      "get": {
        "operationId": "getHumanProfile",
        "tags": [
          "profile"
        ],
        "summary": "How the community works, what its humans can do, and how to reach them",
        "responses": {
          "200": {
            "description": "Profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "profile"
        ],
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HumanRequest": {
        "type": "object",
        "properties": {
          "agent_name": {
            "description": "Name or identifier of the requesting AI agent.",
            "type": "string",
            "maxLength": 120,
            "minLength": 2
          },
          "agent_platform": {
            "description": "Model, framework or product the agent runs on (optional).",
            "type": "string",
            "maxLength": 120
          },
          "principal": {
            "description": "The human or organization you act for. Strongly recommended: requests with an accountable principal get priority.",
            "type": "string",
            "maxLength": 200
          },
          "principal_contact": {
            "description": "How to reach your principal directly (email or URL). Optional.",
            "type": "string",
            "maxLength": 200
          },
          "reply_to": {
            "description": "Email address where the human will reply. It must be monitored by you or your principal.",
            "type": "string",
            "format": "email",
            "minLength": 6,
            "maxLength": 254
          },
          "category": {
            "description": "Type of task. Use 'other' if unsure.",
            "type": "string",
            "enum": [
              "in_person_verification",
              "errands_logistics",
              "phone_and_human_contact",
              "event_attendance",
              "fabrication_3d_printing",
              "expert_review_life_sciences",
              "geo_ai_visibility",
              "human_in_the_loop",
              "real_world_ventures",
              "other"
            ],
            "default": "other"
          },
          "task": {
            "description": "What needs to happen in the real world, in plain language.",
            "type": "string",
            "maxLength": 4000,
            "minLength": 10
          },
          "location": {
            "description": "Where the task takes place: address, city and country, or 'remote'. Needed for in-person tasks so a nearby human can be matched.",
            "type": "string",
            "maxLength": 200
          },
          "deadline": {
            "description": "When it must be done: ISO 8601 date/time or plain text.",
            "type": "string",
            "maxLength": 100
          },
          "budget": {
            "description": "Amount and currency offered, e.g. '120 USD' or '100 EUR'.",
            "type": "string",
            "maxLength": 100
          },
          "success_criteria": {
            "description": "How both sides will know the task is done.",
            "type": "string",
            "maxLength": 1000
          },
          "evidence_required": {
            "description": "Proof you need back: photos, receipts, written report, etc.",
            "type": "string",
            "maxLength": 500
          },
          "language": {
            "description": "Preferred language as a BCP 47 code (en, es, fr, ja, pt-BR...). The request is matched with a human who speaks it.",
            "type": "string",
            "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$",
            "maxLength": 35,
            "default": "en"
          },
          "notes": {
            "description": "Anything else the human should know. No secrets or credentials.",
            "type": "string",
            "maxLength": 4000
          }
        },
        "required": [
          "agent_name",
          "reply_to",
          "task"
        ],
        "additionalProperties": false
      },
      "RequestReceipt": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "request_id": {
            "type": "string",
            "pattern": "^IYH-[0-9]{8}-[0-9A-F]{6}$"
          },
          "human_review": {
            "type": "boolean"
          },
          "reply_channel": {
            "type": "string",
            "enum": [
              "email"
            ]
          },
          "reply_to": {
            "type": "string",
            "format": "email"
          },
          "delivery": {
            "type": "string",
            "enum": [
              "emailed",
              "queued"
            ]
          },
          "expected_response": {
            "type": "string"
          },
          "next_steps": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "status",
          "request_id",
          "human_review",
          "reply_to"
        ]
      },
      "ComposedEmail": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "mailto_url": {
            "type": "string"
          }
        },
        "required": [
          "to",
          "subject",
          "body",
          "mailto_url"
        ]
      },
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "fallback_email": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "status"
        ]
      }
    }
  }
}