{
  "openapi": "3.1.0",
  "info": {
    "title": "Poseidon DS public API",
    "version": "1.4.0",
    "description": "Read Poseidon DS service facts and submit an AI discovery audit request on behalf of a person who has agreed to be contacted. Submitting a request is not a booking or a purchase; a person replies by email. Rate limited. Pro benchmark endpoints require an API key and use only audit findings created after businesses give written opt-in; results are published only after enough distinct businesses opt in. A machine-readable offer profile is at /.well-known/ucp, and the request_quote tool on the MCP server returns indicative prices. Clients can also sign up for a free trial and build their dataset in the client portal.",
    "contact": {
      "url": "https://poseidondssolutions.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://poseidondssolutions.com"
    }
  ],
  "paths": {
    "/api/v1/service": {
      "get": {
        "operationId": "getService",
        "summary": "Service facts: what Poseidon DS does, starting prices, limits and how to start",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Service facts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/price-estimate": {
      "get": {
        "operationId": "estimatePrice",
        "summary": "Starting-price estimate for a number of business locations (not a quote)",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "locations",
            "in": "query",
            "required": true,
            "description": "Number of business locations",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/api/v1/glossary": {
      "get": {
        "operationId": "defineTerm",
        "summary": "Plain-language definition of a business AI search term (AIO, GEO, llms.txt, OAI-SearchBot…)",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "term",
            "in": "query",
            "required": true,
            "description": "Term to define",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/crawlers": {
      "get": {
        "operationId": "listCrawlers",
        "summary": "Search and AI crawlers: purpose, verification method and official documentation",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/readiness": {
      "get": {
        "operationId": "checkReadiness",
        "summary": "Free snapshot check of a public business website (crawler access, canonical, structured data, sitemap, contact details). Not a score; nothing stored; 10 per hour.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Website address, for example yourbusiness.com",
            "schema": {
              "type": "string",
              "maxLength": 300
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid address"
          },
          "429": {
            "description": "Too many checks"
          }
        }
      }
    },
    "/api/v1/benchmarks": {
      "get": {
        "operationId": "listBenchmarks",
        "summary": "Benchmark status index: whether opt-in data from at least 30 distinct businesses is available. No statistics or business identities are included.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/benchmarks/{industry}": {
      "get": {
        "operationId": "getBenchmark",
        "summary": "One industry benchmark dataset (Pro). Requires an API key and written opt-in from contributing businesses. Returns an aggregate only after the minimum number of distinct businesses opt in.",
        "parameters": [
          {
            "name": "industry",
            "in": "path",
            "required": true,
            "description": "Industry slug, for example law-firms",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "API key missing"
          },
          "403": {
            "description": "API key unknown or revoked"
          },
          "404": {
            "description": "Unknown industry"
          },
          "429": {
            "description": "Hourly key limit reached"
          },
          "503": {
            "description": "API keys or consent schema not available yet"
          }
        }
      }
    },
    "/api/v1/audit-requests": {
      "post": {
        "operationId": "createAuditRequest",
        "summary": "Submit an AI discovery audit request for a business or company",
        "description": "Only submit with the explicit agreement of the person named. The person will be contacted by email. Limited to 5 requests per hour per address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Request received (not a booking confirmation)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditRequestReceived"
                }
              }
            }
          },
          "422": {
            "description": "Validation errors keyed by field",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests"
          },
          "503": {
            "description": "Temporarily unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key issued by Poseidon DS (Authorization: Bearer <key> also works). Required for the Pro benchmark endpoint; optional on the read endpoints — sending a key authenticates the call and applies the per-key hourly limit, and an unknown or revoked key is refused. Keys are issued by hand — see /api-access."
      }
    },
    "schemas": {
      "AuditRequest": {
        "type": "object",
        "required": [
          "name",
          "email",
          "organization",
          "consent"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Full name of the person requesting the audit"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 200,
            "description": "Their work email; replies go here"
          },
          "organization": {
            "type": "string",
            "maxLength": 160,
            "description": "Business or company name"
          },
          "location_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5000
          },
          "website": {
            "type": "string",
            "maxLength": 300,
            "description": "Business website address"
          },
          "goals": {
            "type": "string",
            "maxLength": 2000,
            "description": "What they want to improve"
          },
          "consent": {
            "type": "boolean",
            "const": true,
            "description": "Must be true: the person agreed that Poseidon DS may store these details and contact them"
          },
          "agent_note": {
            "type": "string",
            "maxLength": 300,
            "description": "Optional: which assistant submitted this and on whose instruction"
          }
        }
      },
      "AuditRequestReceived": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "received"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}