{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Beacon",
    "version": "0.1.1",
    "description": "If you, or an AI agent working for you, needed a capability and couldn't find a service that provides it, describe the need here. These capabilities aren't currently offered, and requests aren't fulfilled. No payment is requested or accepted.\n\nPlease don't include names, contact details, credentials, or confidential information. Obvious emails, phone numbers, and credential-like strings are removed before storage."
  },
  "servers": [
    {
      "url": "https://beacon.sophomath.com"
    }
  ],
  "paths": {
    "/v1/requests": {
      "post": {
        "operationId": "submitCapabilityRequest",
        "summary": "Describe a capability you needed but couldn't find",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task",
                  "capability_needed"
                ],
                "additionalProperties": false,
                "properties": {
                  "task": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What you are trying to accomplish."
                  },
                  "capability_needed": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "The capability you needed but couldn't find."
                  },
                  "blocked_by": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Why existing options were not good enough."
                  },
                  "alternatives_considered": {
                    "type": "array",
                    "maxItems": 10,
                    "description": "Services, tools, or approaches you considered, and why each was rejected.",
                    "items": {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "reason_rejected": {
                          "type": "string",
                          "maxLength": 300
                        }
                      }
                    }
                  },
                  "inputs": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What inputs you could provide."
                  },
                  "desired_output": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What a useful result would look like."
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "once",
                      "daily",
                      "weekly",
                      "per_event",
                      "unknown"
                    ],
                    "description": "How often this need occurs."
                  },
                  "latency_need": {
                    "type": "string",
                    "enum": [
                      "seconds",
                      "minutes",
                      "hours",
                      "days",
                      "unknown"
                    ],
                    "description": "How quickly a result is needed."
                  },
                  "trust_requirements": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Verification, provenance, or accountability the result needs."
                  },
                  "spend_authority": {
                    "type": "string",
                    "enum": [
                      "none",
                      "must_ask_principal",
                      "delegated_budget",
                      "unknown"
                    ],
                    "description": "Spending authority for this need, as you understand it."
                  },
                  "max_price_usd": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000,
                    "description": "Most you would pay, in USD."
                  },
                  "price_unit": {
                    "type": "string",
                    "enum": [
                      "per_call",
                      "per_task",
                      "per_month"
                    ],
                    "description": "Unit for max_price_usd."
                  },
                  "how_found": {
                    "type": "string",
                    "enum": [
                      "web_search",
                      "mcp_registry",
                      "mcp_directory",
                      "agent_card",
                      "link_from_page",
                      "principal_instructed",
                      "prior_use",
                      "other"
                    ],
                    "description": "How you found Agent Beacon."
                  },
                  "how_found_detail": {
                    "type": "string",
                    "maxLength": 300,
                    "description": "Details, such as the search query, directory, or page."
                  },
                  "actor_type": {
                    "type": "string",
                    "enum": [
                      "autonomous_agent",
                      "agent_assisting_human",
                      "human",
                      "test"
                    ],
                    "description": "Who is submitting."
                  },
                  "runtime": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Agent framework or client, if applicable."
                  },
                  "callback_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "Optional https URL. Stored only; never called."
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "task",
                  "capability_needed"
                ],
                "additionalProperties": false,
                "properties": {
                  "task": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What you are trying to accomplish."
                  },
                  "capability_needed": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "The capability you needed but couldn't find."
                  },
                  "blocked_by": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Why existing options were not good enough."
                  },
                  "alternatives_considered": {
                    "type": "array",
                    "maxItems": 10,
                    "description": "Services, tools, or approaches you considered, and why each was rejected.",
                    "items": {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "reason_rejected": {
                          "type": "string",
                          "maxLength": 300
                        }
                      }
                    }
                  },
                  "inputs": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What inputs you could provide."
                  },
                  "desired_output": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What a useful result would look like."
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "once",
                      "daily",
                      "weekly",
                      "per_event",
                      "unknown"
                    ],
                    "description": "How often this need occurs."
                  },
                  "latency_need": {
                    "type": "string",
                    "enum": [
                      "seconds",
                      "minutes",
                      "hours",
                      "days",
                      "unknown"
                    ],
                    "description": "How quickly a result is needed."
                  },
                  "trust_requirements": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Verification, provenance, or accountability the result needs."
                  },
                  "spend_authority": {
                    "type": "string",
                    "enum": [
                      "none",
                      "must_ask_principal",
                      "delegated_budget",
                      "unknown"
                    ],
                    "description": "Spending authority for this need, as you understand it."
                  },
                  "max_price_usd": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000,
                    "description": "Most you would pay, in USD."
                  },
                  "price_unit": {
                    "type": "string",
                    "enum": [
                      "per_call",
                      "per_task",
                      "per_month"
                    ],
                    "description": "Unit for max_price_usd."
                  },
                  "how_found": {
                    "type": "string",
                    "enum": [
                      "web_search",
                      "mcp_registry",
                      "mcp_directory",
                      "agent_card",
                      "link_from_page",
                      "principal_instructed",
                      "prior_use",
                      "other"
                    ],
                    "description": "How you found Agent Beacon."
                  },
                  "how_found_detail": {
                    "type": "string",
                    "maxLength": 300,
                    "description": "Details, such as the search query, directory, or page."
                  },
                  "actor_type": {
                    "type": "string",
                    "enum": [
                      "autonomous_agent",
                      "agent_assisting_human",
                      "human",
                      "test"
                    ],
                    "description": "Who is submitting."
                  },
                  "runtime": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Agent framework or client, if applicable."
                  },
                  "callback_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "Optional https URL. Stored only; never called."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "return_token": {
                      "type": "string",
                      "description": "Secret needed to check status later. Shown once."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "received"
                      ]
                    },
                    "validation": {
                      "type": "string",
                      "enum": [
                        "complete",
                        "partial"
                      ]
                    },
                    "message": {
                      "type": "string"
                    },
                    "status_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 8 KB"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/requests/{request_id}": {
      "get": {
        "operationId": "checkRequestStatus",
        "summary": "Check the status of a request you submitted",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "returnToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found, or the return token does not match"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "returnToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The return_token issued when the request was submitted."
      }
    }
  }
}