{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Request Desk",
    "version": "0.4.0",
    "summary": "A free fallback for AI agents that are blocked or cannot find data.",
    "description": "Report a blocked fetch, missing data or an action you could not complete. The response lists up to three existing sources that already serve the need, or says plainly that none is known. The MCP server at https://agentrequest.dev/mcp offers the same three operations as tools. Never bypasses CAPTCHAs, bot checks or logins. Do not send personal data about private individuals.",
    "contact": {
      "email": "hello@agentrequest.dev",
      "url": "https://agentrequest.dev"
    }
  },
  "servers": [
    {
      "url": "https://agentrequest.dev"
    }
  ],
  "paths": {
    "/api/request": {
      "post": {
        "operationId": "submitRequest",
        "summary": "Report a need or failure and get pointers to working sources",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              },
              "example": {
                "kind": "failure",
                "target": "rightmove.co.uk",
                "failure_type": "403",
                "description": "sold prices for LS6"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Logged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or missing description"
          }
        }
      }
    },
    "/api/demand": {
      "get": {
        "operationId": "getDemand",
        "summary": "Public demand totals: counts by site and failure type, never report text",
        "responses": {
          "200": {
            "description": "Totals from beacon reports and public GitHub issues"
          }
        }
      }
    },
    "/api/key": {
      "get": {
        "operationId": "newReportKey",
        "summary": "Issue a new private report key (nothing is stored until reports arrive)",
        "responses": {
          "200": {
            "description": "A new key with ready-made MCP and report URLs"
          }
        }
      }
    },
    "/api/report": {
      "post": {
        "operationId": "getReport",
        "summary": "Your agent's private report: every dead end and where it was sent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "key"
                ],
                "properties": {
                  "key": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The report"
          },
          "400": {
            "description": "Not a valid key"
          }
        }
      },
      "get": {
        "operationId": "getDemoReport",
        "summary": "The public demo report (our own scout agents). Use ?demo=1",
        "parameters": [
          {
            "name": "demo",
            "in": "query",
            "schema": {
              "type": "string",
              "const": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The demo report"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Request": {
        "type": "object",
        "required": [
          "kind",
          "description"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "data",
              "action",
              "failure"
            ]
          },
          "description": {
            "type": "string",
            "minLength": 3,
            "description": "What you needed or were trying to do"
          },
          "target": {
            "type": "string",
            "description": "URL, domain or organisation involved"
          },
          "purpose": {
            "type": "string"
          },
          "failure_type": {
            "type": "string",
            "description": "e.g. 403, 429, captcha, cloudflare, login_wall, js_render, pdf, no_api"
          },
          "error_message": {
            "type": "string"
          },
          "max_price_usd": {
            "type": "number",
            "minimum": 0,
            "description": "Most you would pay per request if this existed"
          },
          "agent_name": {
            "type": "string"
          },
          "private": {
            "type": "boolean",
            "description": "Use the free text for matching but do not store it"
          },
          "report_key": {
            "type": "string",
            "pattern": "^ard_[A-Za-z0-9_-]{32}$",
            "description": "Private report key from /api/key. Files this report under your private report. Can also be sent as an X-Report-Key header."
          }
        }
      },
      "Match": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "covers": {
            "type": "string"
          },
          "access": {
            "type": "string"
          }
        }
      },
      "Response": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "const": "logged"
          },
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Match"
            },
            "maxItems": 3
          },
          "message": {
            "type": "string",
            "description": "The same reply MCP clients receive, as plain text"
          },
          "added_to_report": {
            "type": "boolean"
          }
        }
      }
    }
  }
}