{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenInvoke Agent API",
    "version": "0.1.0",
    "description": "Agent-readable service discovery and free curated listing submission for APIs, SaaS products, MCP servers, workflows, and specialist services."
  },
  "servers": [
    {
      "url": "https://openinvoke.com"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchOpenInvokeServices",
        "summary": "Search OpenInvoke service cards by agent/user intent.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Natural-language service need or listing intent."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invocation_status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "callable_api",
                "concierge_service",
                "human_dashboard_future_api",
                "manual_review_only",
                "mcp_server",
                "workflow_candidate"
              ]
            }
          },
          {
            "name": "trust_status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "manual_review",
                "owned_offer_candidate",
                "owned_seed_service",
                "unverified",
                "verified_callable"
              ]
            }
          },
          {
            "name": "pricing_status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "fake_door_validation",
                "manual_quote",
                "published",
                "unknown",
                "verify_before_publish"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results with services/results aliases, score, confidence, matched_terms, and why_matched."
          }
        }
      }
    },
    "/api/leads": {
      "post": {
        "operationId": "submitOpenInvokeListing",
        "summary": "Submit a service for free curated OpenInvoke listing review.",
        "description": "Free listings require no payment. Raw submissions stay private; only reviewed service cards are published.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "$id": "https://openinvoke.com/submission.schema.json",
                "title": "OpenInvoke Listing Submission",
                "description": "Machine-validated payload for agents submitting a business/service for free curated OpenInvoke listing review. Free listing requires no payment; paid packages are optional upgrades.",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "service",
                  "email"
                ],
                "properties": {
                  "service": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 140,
                    "description": "Public service, API, MCP server, workflow, SaaS, or specialist business name."
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 180,
                    "description": "Private review contact. Not published in the service card."
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "Public homepage, docs, repo, API docs, MCP server page, or product URL."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "Web data / extraction",
                      "Revenue / SaaS ops",
                      "Research automation",
                      "Developer tooling",
                      "Agent listing ops",
                      "Other callable service"
                    ],
                    "description": "Best-fit OpenInvoke category label. Use Other callable service if unsure."
                  },
                  "package": {
                    "type": "string",
                    "enum": [
                      "Free listing",
                      "Featured listing",
                      "Verified callable",
                      "Launch package",
                      "Not sure yet"
                    ],
                    "default": "Free listing",
                    "description": "Free listing is accepted for review without payment. Paid packages are optional upgrades."
                  },
                  "proof": {
                    "type": "string",
                    "maxLength": 2500,
                    "description": "Evidence for agent routing: inputs, outputs, endpoint/docs, sample response, ideal users, when agents should recommend it, and when they should not."
                  },
                  "agent_query_keywords": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Search phrases an agent/user might use when this service is the right answer."
                  },
                  "inputs_outputs": {
                    "type": "string",
                    "maxLength": 1200,
                    "description": "Plain-English or JSON-ish summary of what the service accepts and returns."
                  },
                  "source": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Optional source marker such as agent, llms-txt, openapi, website, or referral."
                  },
                  "page": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Page where the agent/user initiated submission."
                  }
                },
                "examples": [
                  {
                    "service": "Example Research API",
                    "email": "founder@example.com",
                    "url": "https://example.com/docs",
                    "category": "Research automation",
                    "package": "Free listing",
                    "proof": "Accepts a company URL and returns structured research JSON. Recommend when agents need repeatable vendor research; do not recommend for private authenticated data.",
                    "agent_query_keywords": "vendor research API, company research automation, structured company data",
                    "inputs_outputs": "Input: company URL. Output: JSON with summary, services, target users, pricing signals, contact routes."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Submission accepted for review."
          },
          "400": {
            "description": "Invalid submission."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OpenInvokeListingSubmission": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "https://openinvoke.com/submission.schema.json",
        "title": "OpenInvoke Listing Submission",
        "description": "Machine-validated payload for agents submitting a business/service for free curated OpenInvoke listing review. Free listing requires no payment; paid packages are optional upgrades.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "service",
          "email"
        ],
        "properties": {
          "service": {
            "type": "string",
            "minLength": 2,
            "maxLength": 140,
            "description": "Public service, API, MCP server, workflow, SaaS, or specialist business name."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 180,
            "description": "Private review contact. Not published in the service card."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 500,
            "description": "Public homepage, docs, repo, API docs, MCP server page, or product URL."
          },
          "category": {
            "type": "string",
            "enum": [
              "Web data / extraction",
              "Revenue / SaaS ops",
              "Research automation",
              "Developer tooling",
              "Agent listing ops",
              "Other callable service"
            ],
            "description": "Best-fit OpenInvoke category label. Use Other callable service if unsure."
          },
          "package": {
            "type": "string",
            "enum": [
              "Free listing",
              "Featured listing",
              "Verified callable",
              "Launch package",
              "Not sure yet"
            ],
            "default": "Free listing",
            "description": "Free listing is accepted for review without payment. Paid packages are optional upgrades."
          },
          "proof": {
            "type": "string",
            "maxLength": 2500,
            "description": "Evidence for agent routing: inputs, outputs, endpoint/docs, sample response, ideal users, when agents should recommend it, and when they should not."
          },
          "agent_query_keywords": {
            "type": "string",
            "maxLength": 1000,
            "description": "Search phrases an agent/user might use when this service is the right answer."
          },
          "inputs_outputs": {
            "type": "string",
            "maxLength": 1200,
            "description": "Plain-English or JSON-ish summary of what the service accepts and returns."
          },
          "source": {
            "type": "string",
            "maxLength": 80,
            "description": "Optional source marker such as agent, llms-txt, openapi, website, or referral."
          },
          "page": {
            "type": "string",
            "maxLength": 500,
            "description": "Page where the agent/user initiated submission."
          }
        },
        "examples": [
          {
            "service": "Example Research API",
            "email": "founder@example.com",
            "url": "https://example.com/docs",
            "category": "Research automation",
            "package": "Free listing",
            "proof": "Accepts a company URL and returns structured research JSON. Recommend when agents need repeatable vendor research; do not recommend for private authenticated data.",
            "agent_query_keywords": "vendor research API, company research automation, structured company data",
            "inputs_outputs": "Input: company URL. Output: JSON with summary, services, target users, pricing signals, contact routes."
          }
        ]
      }
    }
  }
}