{
  "components": {
    "schemas": {
      "AuditResult": {
        "description": "One audit: status plus scored result when done.",
        "properties": {
          "business": {
            "type": "object"
          },
          "cached": {
            "type": "boolean"
          },
          "domain": {
            "type": "string"
          },
          "overall_ai_readiness": {
            "type": "integer"
          },
          "scores": {
            "description": "Per-metric {value, tier, source}; tier is measured | ai_estimate | estimated.",
            "type": "object"
          },
          "status": {
            "enum": [
              "done",
              "pending",
              "failed",
              "invalid",
              "quota_exceeded"
            ],
            "type": "string"
          },
          "summary": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Quota": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "window": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKey": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      },
      "bearer": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Audit any website for SEO and AI-search readiness (GEO / AEO / GSO). Authenticate with an API key in the X-API-Key header. AI agents can also connect over MCP at https://tadaaah.io/mcp (same keys). Docs: https://tadaaah.io/api-docs",
    "title": "Tadaaah Website Audit API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/audits": {
      "post": {
        "operationId": "createAudits",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "lang": {
                    "enum": [
                      "en",
                      "fr"
                    ],
                    "type": "string"
                  },
                  "url": {
                    "description": "A single website to audit.",
                    "type": "string"
                  },
                  "urls": {
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 50,
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "audits": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "batch_id": {
                      "type": "string"
                    },
                    "quota": {
                      "$ref": "#/components/schemas/Quota"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Batch accepted. Cached URLs are already done."
          }
        },
        "summary": "Audit one URL or a batch of up to 50"
      }
    },
    "/v1/audits/{audit_id}": {
      "get": {
        "operationId": "getAudit",
        "parameters": [
          {
            "in": "path",
            "name": "audit_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResult"
                }
              }
            },
            "description": "The audit."
          }
        },
        "summary": "One audit's status + result"
      }
    },
    "/v1/batches/{batch_id}": {
      "get": {
        "operationId": "getBatch",
        "parameters": [
          {
            "in": "path",
            "name": "batch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The batch."
          }
        },
        "summary": "Whole batch: statuses + finished results"
      }
    },
    "/v1/batches/{batch_id}.csv": {
      "get": {
        "operationId": "getBatchCsv",
        "parameters": [
          {
            "in": "path",
            "name": "batch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/csv": {}
            },
            "description": "CSV, one row per URL."
          }
        },
        "summary": "The batch as a report-ready CSV"
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "getAccount",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "plan": {
                      "type": "string"
                    },
                    "quota": {
                      "$ref": "#/components/schemas/Quota"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Plan + quota."
          }
        },
        "summary": "The calling key's plan and remaining quota"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    },
    {
      "bearer": []
    }
  ],
  "servers": [
    {
      "url": "https://tadaaah.io"
    }
  ]
}