{"openapi":"3.1.0","info":{"title":"AutoSEOSystem Public API","summary":"Public API surface for AutoSEOSystem plan discovery, lead capture, and widget audit creation.","description":"AutoSEOSystem exposes public endpoints for plan metadata, SEO workflow previews, lead submission, widget-powered audit creation, and public audit report access. Protected operations use API keys with named scopes.","version":"1.0.0","contact":{"name":"AutoSEOSystem Support","email":"support@autoseosystem.ai","url":"https://autoseosystem.ai/contact"}},"servers":[{"url":"https://autoseosystem.ai","description":"AutoSEOSystem production"},{"url":"https://autoseosystem.ai/api/v1","description":"AutoSEOSystem REST API v1"}],"externalDocs":{"description":"AutoSEOSystem developer resources","url":"https://autoseosystem.ai/developers"},"security":[],"paths":{"/api/v1/sandbox/health":{"get":{"tags":["Sandbox"],"operationId":"getSandboxHealthV1","summary":"Check the zero-auth API sandbox.","description":"Returns a simple public health payload and rate-limit headers so agents can verify connectivity without credentials.","responses":{"200":{"description":"Sandbox health returned.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/v1/plans":{"get":{"tags":["Plans"],"operationId":"listPublicPlansV1","summary":"List public AutoSEOSystem plans.","description":"Preferred v1 endpoint for active public plan metadata used in pricing and agent plan comparison.","responses":{"200":{"description":"Public plans returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanListResponse"}}}},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/v1/plans/{code}":{"get":{"tags":["Plans"],"operationId":"getPublicPlanV1","summary":"Read a public plan by code.","description":"Preferred v1 endpoint for reading one active public plan by code.","parameters":[{"name":"code","in":"path","required":true,"description":"Plan code such as starter or growth.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Plan returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanResponse"}}}},"404":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}}}},"/api/v1/plan/preview":{"post":{"tags":["Plans"],"operationId":"createPlanPreviewV1","summary":"Create a public SEO workflow preview.","description":"Preferred v1 endpoint for a lightweight SEO workflow preview.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanPreviewRequest"}}}},"responses":{"200":{"description":"Preview returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanPreviewResponse"}}}},"422":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/v1/plan/lead":{"post":{"tags":["Plans"],"operationId":"submitPlanLeadV1","summary":"Submit a public plan lead.","description":"Preferred v1 endpoint for submitting a plan lead request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLeadRequest"}}}},"responses":{"200":{"description":"Lead accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessMessageResponse"}}}},"422":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/v1/public/widget/audit":{"post":{"tags":["Widget Audits"],"operationId":"createWidgetAuditV1","summary":"Create a widget SEO audit.","description":"Preferred v1 endpoint for creating a queued SEO audit from an embedded widget. Requires an API key scoped for audit:create.","security":[{"ApiKeyAuth":[]},{"OAuth2ClientCredentials":["audit:create"]}],"x-required-scopes":["audit:create"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetAuditRequest"}}}},"responses":{"201":{"description":"Audit queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetAuditResponse"}}}},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/v1/public/audit/{token}/summary":{"get":{"tags":["Public Audit Reports"],"operationId":"getPublicAuditSummaryV1","summary":"Read a public audit summary.","description":"Preferred v1 endpoint for reading summary data by public audit report share token.","parameters":[{"name":"token","in":"path","required":true,"description":"Public report share token.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Audit summary returned."},"404":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}}}},"/api/plans":{"get":{"tags":["Plans"],"operationId":"listPublicPlans","summary":"List public AutoSEOSystem plans.","description":"Returns active public plan metadata for pricing and agent plan comparison.","responses":{"200":{"description":"Public plans returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanListResponse"}}}},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/plans/{code}":{"get":{"tags":["Plans"],"operationId":"getPublicPlan","summary":"Read a public plan by code.","description":"Returns one active public plan, or a structured JSON error if the code is unknown.","parameters":[{"name":"code","in":"path","required":true,"description":"Plan code such as starter or growth.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Plan returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanResponse"}}}},"404":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}}}},"/api/plan/preview":{"post":{"tags":["Plans"],"operationId":"createPlanPreview","summary":"Create a public SEO workflow preview.","description":"Accepts a website URL and optional industry to return a lightweight SEO workflow preview.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanPreviewRequest"}}}},"responses":{"200":{"description":"Preview returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanPreviewResponse"}}}},"422":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/plan/lead":{"post":{"tags":["Plans"],"operationId":"submitPlanLead","summary":"Submit a public plan lead.","description":"Creates a plan lead from an email, website URL, optional industry, and optional preview payload.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLeadRequest"}}}},"responses":{"200":{"description":"Lead accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessMessageResponse"}}}},"422":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/public/widget/audit":{"post":{"tags":["Widget Audits"],"operationId":"createWidgetAudit","summary":"Create a widget SEO audit.","description":"Creates a queued SEO audit from an embedded widget. Requires an API key scoped for audit:create.","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["audit:create"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetAuditRequest"}}}},"responses":{"201":{"description":"Audit queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetAuditResponse"}}}},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"404":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}},"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}]}},"/api/public/audit/{token}/summary":{"get":{"tags":["Public Audit Reports"],"operationId":"getPublicAuditSummary","summary":"Read a public audit summary.","description":"Returns summary data for a public audit report share token when available.","parameters":[{"name":"token","in":"path","required":true,"description":"Public report share token.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Audit summary returned."},"404":{"$ref":"#/components/responses/JsonError"},"400":{"$ref":"#/components/responses/JsonError"},"401":{"$ref":"#/components/responses/JsonError"},"403":{"$ref":"#/components/responses/JsonError"},"422":{"$ref":"#/components/responses/JsonError"},"429":{"$ref":"#/components/responses/JsonError"},"500":{"$ref":"#/components/responses/JsonError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Widget API key generated in an AutoSEOSystem organization. API keys are scoped; see x-scopes and RFC 9728 protected-resource metadata.","x-scopes":["plans:read","plan:preview","plan:lead","audit:create","audit:read","audit:unlock"]},"OAuth2ClientCredentials":{"type":"oauth2","description":"OAuth 2.0 client credentials discovery for scoped AutoSEOSystem API integrations. Client credential issuance is controlled from the AutoSEOSystem account workspace.","flows":{"clientCredentials":{"tokenUrl":"https://autoseosystem.ai/oauth/token","scopes":{"plans:read":"Read public plan and pricing metadata.","plan:preview":"Generate a public backlink and SEO workflow preview.","plan:lead":"Submit a public plan lead request.","audit:create":"Create a widget-powered SEO audit.","audit:read":"Read a public audit summary by share token.","audit:unlock":"Submit unlock data for a public audit report."}}}},"InternalApiToken":{"type":"apiKey","in":"header","name":"X-API-Token","description":"Internal worker token for first-party automation services. Not intended for public integrations."}},"parameters":{"ApiVersionHeader":{"name":"AutoSEOSystem-API-Version","in":"header","required":false,"description":"Optional explicit REST API version header. Current stable value is v1. URL path versioning under /api/v1 is preferred.","schema":{"type":"string","enum":["v1"]}}},"headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current rate-limit window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current rate-limit window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current rate-limit window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying a 429 response.","schema":{"type":"integer"}}},"responses":{"JsonError":{"description":"Structured JSON error response with an agent-readable code and resolution hint.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["success","message","error_code","error"],"properties":{"success":{"type":"boolean","const":false},"message":{"type":"string"},"error_code":{"type":"string"},"error":{"type":"object","required":["code","message","hint","status"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"status":{"type":"integer"}}},"errors":{"type":"object"}}},"PlanListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}},"PlanResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}},"PlanPreviewRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"industry":{"type":"string"}}},"PlanLeadRequest":{"type":"object","required":["email","url"],"properties":{"email":{"type":"string","format":"email"},"url":{"type":"string","format":"uri"},"industry":{"type":"string"},"previewJson":{"type":"object"}}},"PlanPreviewResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}},"SuccessMessageResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"WidgetAuditRequest":{"type":"object","required":["url","email"],"properties":{"url":{"type":"string","maxLength":2048},"email":{"type":"string","format":"email"},"name":{"type":"string"},"utm":{"type":"object"},"referrer":{"type":"string"}}},"WidgetAuditResponse":{"type":"object","required":["audit_id","report_url","status"],"properties":{"audit_id":{"type":"integer"},"report_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["queued"]}}}}},"tags":[{"name":"Plans","description":"Public plan and lead endpoints."},{"name":"Sandbox","description":"Zero-auth sandbox endpoints for validating connectivity and headers."},{"name":"Widget Audits","description":"Scoped API-key endpoints for creating audits from embedded widgets."},{"name":"Public Audit Reports","description":"Public share-token audit report endpoints."}],"x-scopes-supported":{"plans:read":"Read public plan and pricing metadata.","plan:preview":"Generate a public backlink and SEO workflow preview.","plan:lead":"Submit a public plan lead request.","audit:create":"Create a widget-powered SEO audit.","audit:read":"Read a public audit summary by share token.","audit:unlock":"Submit unlock data for a public audit report."},"x-versioning":{"current":"v1","preferred_url_prefix":"/api/v1","version_header":"AutoSEOSystem-API-Version","deprecation_policy":"Stable REST versions are supported for at least 12 months after a replacement version is published. Deprecated endpoints send Deprecation and Sunset headers before removal.","deprecation_headers":["Deprecation","Sunset","Link"]},"x-cli":{"name":"autoseosystem-cli","documentation":"https://autoseosystem.ai/cli","installer":"https://autoseosystem.ai/cli/autoseosystem"},"x-sandbox":{"health":"https://autoseosystem.ai/api/v1/sandbox/health","authentication":"none"}}