{"openapi":"3.1.0","info":{"title":"CiteSurge Public API","version":"1.0.0","description":"Programmatic access to your CiteSurge AI-visibility data: scores, citations, mentions, findings, reports, and audit triggers. Authenticate every request with an API key created by an account owner in Settings under API access."},"servers":[{"url":"https://citesurge.com"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key in the Authorization header: `Authorization: Bearer cs_live_...`. Keys are shown once at creation. Read-only keys can read every endpoint; read-and-trigger keys can also start audits and create projects."}}},"paths":{"/api/v1/projects":{"get":{"summary":"List projects","description":"Projects visible to the key (the whole account, or the key's project scope). Includes the latest completed audit summary per project. Rate limit: 60 reads/minute per key.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor field."}],"responses":{"200":{"description":"Projects page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"latestCompletedAudit":{"type":["object","null"],"properties":{"id":{"type":"string"},"runDate":{"type":"string","format":"date-time"},"overallScore":{"type":["integer","null"]}}}}}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}},"post":{"summary":"Create a project","description":"Programmatic client onboarding for agencies. Requires a read-and-trigger key without a project scope. The new project's plan follows your account's existing plan; it cannot be set through the API. Rate limit: 10 writes/minute per key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","domain"],"properties":{"name":{"type":"string"},"domain":{"type":"string"},"slug":{"type":"string","description":"Optional custom slug."},"workspaceSlug":{"type":"string","description":"Required when the account has more than one workspace."}}}}}},"responses":{"201":{"description":"Project created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"409":{"description":"Slug already in use.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"422":{"description":"Plan brand limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}":{"get":{"summary":"Get a project","description":"Project detail with the latest completed audit's scores and deltas.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."}],"responses":{"200":{"description":"Project detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"latestCompletedAudit":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","FAILED"]},"runDate":{"type":"string","format":"date-time"},"pagesAnalyzed":{"type":"integer"},"findingsCount":{"type":"integer"},"scores":{"type":"object","description":"Score set for one audit (0-100, null when not evaluated in this run).","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}},"deltas":{"type":"object","description":"Change in each score versus the previous audit.","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}}}},{"type":"null"}]}}}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/score-history":{"get":{"summary":"Score history","description":"Audit runs over time with scores and deltas, newest first.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Earliest timestamp to include."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Latest timestamp to include."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor field."}],"responses":{"200":{"description":"Audit runs page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","FAILED"]},"runDate":{"type":"string","format":"date-time"},"pagesAnalyzed":{"type":"integer"},"findingsCount":{"type":"integer"},"scores":{"type":"object","description":"Score set for one audit (0-100, null when not evaluated in this run).","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}},"deltas":{"type":"object","description":"Change in each score versus the previous audit.","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}}}}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/citations":{"get":{"summary":"Citations","description":"Where AI answers cited sources for your tracked questions: URL, host, title, position in the answer, and whether the cited domain is yours or a competitor's.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."},{"name":"engine","in":"query","schema":{"type":"string","enum":["CHATGPT","CLAUDE","PERPLEXITY","GEMINI","GOOGLE_AIO","BING_COPILOT","GROK"]},"description":"Filter to a single AI answer engine."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Earliest timestamp to include."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Latest timestamp to include."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor field."}],"responses":{"200":{"description":"Citations page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"engine":{"type":"string","enum":["CHATGPT","CLAUDE","PERPLEXITY","GEMINI","GOOGLE_AIO","BING_COPILOT","GROK"]},"observedAt":{"type":"string","format":"date-time"},"url":{"type":"string"},"normalizedUrl":{"type":"string"},"host":{"type":"string"},"title":{"type":["string","null"]},"position":{"type":"integer"},"isClientDomain":{"type":"boolean"},"isCompetitorDomain":{"type":"boolean"},"citationConfidence":{"type":"integer","description":"Confidence (0-100) that the citation refers to your brand."},"matchedEntity":{"type":["string","null"]}}}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/mentions":{"get":{"summary":"Mentions","description":"Brand and competitor mentions inside AI answers, with how the answer treated each one (recommended, listed, compared, criticized).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."},{"name":"engine","in":"query","schema":{"type":"string","enum":["CHATGPT","CLAUDE","PERPLEXITY","GEMINI","GOOGLE_AIO","BING_COPILOT","GROK"]},"description":"Filter to a single AI answer engine."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Earliest timestamp to include."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Latest timestamp to include."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor field."}],"responses":{"200":{"description":"Mentions page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"engine":{"type":"string","enum":["CHATGPT","CLAUDE","PERPLEXITY","GEMINI","GOOGLE_AIO","BING_COPILOT","GROK"]},"observedAt":{"type":"string","format":"date-time"},"name":{"type":"string"},"normalizedName":{"type":"string"},"kind":{"type":"string","enum":["CLIENT","COMPETITOR","THIRD_PARTY","CATEGORY"]},"role":{"type":"string","enum":["RECOMMENDED","LISTED","COMPARED","CRITICIZED","EXCLUDED","UNKNOWN"]},"sentiment":{"type":["string","null"]},"mentionConfidence":{"type":"integer","description":"Confidence (0-100) that the mention refers to your brand."},"context":{"type":["string","null"],"description":"Answer excerpt around the mention."}}}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/findings":{"get":{"summary":"Findings","description":"Prioritized recommendations from an audit. Defaults to the latest completed audit; pass auditRunId for an earlier one.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."},{"name":"auditRunId","in":"query","schema":{"type":"string"},"description":"Specific audit run; must belong to the project."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor field."}],"responses":{"200":{"description":"Findings page (also returns auditRunId).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"severity":{"type":"string","enum":["CRITICAL","HIGH","MEDIUM","LOW"]},"category":{"type":"string","enum":["CITABILITY","TECHNICAL","SCHEMA","EEAT","BRAND","PLATFORM"]},"status":{"type":"string","enum":["OPEN","IN_PROGRESS","RESOLVED","DISMISSED"]},"title":{"type":"string"},"description":{"type":"string"},"recommendation":{"type":["string","null"]},"affectedUrl":{"type":["string","null"]},"timeline":{"type":["string","null"]},"expectedImpact":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]}}}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/report":{"get":{"summary":"Audit report (Markdown)","description":"The latest completed audit as a Markdown document — the same client report available in the dashboard.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."}],"responses":{"200":{"description":"Markdown report.","content":{"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/report.pdf":{"get":{"summary":"Audit report (PDF)","description":"The client audit report as a PDF. Defaults to the latest completed audit; pass auditRunId for an earlier one.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."},{"name":"auditRunId","in":"query","schema":{"type":"string"},"description":"Specific completed audit run."}],"responses":{"200":{"description":"PDF report.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"503":{"description":"PDF rendering temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/projects/{slug}/audits":{"post":{"summary":"Trigger an audit","description":"Starts an audit for the project. Requires a read-and-trigger key. Returns 202 with the run id to poll. A run can be requested at most once per hour per project, and requests are refused while the project is at its usage cap. Rate limit: 10 writes/minute per key.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Project slug."}],"responses":{"202":{"description":"Audit accepted (created may be false when a run is already in progress).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"auditRunId":{"type":"string"},"created":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"502":{"description":"The audit could not be queued; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}},"/api/v1/audit-runs/{id}":{"get":{"summary":"Get an audit run","description":"Poll a run's status and scores by id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Audit run id."}],"responses":{"200":{"description":"Audit run detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","FAILED"]},"runDate":{"type":"string","format":"date-time"},"pagesAnalyzed":{"type":"integer"},"findingsCount":{"type":"integer"},"scores":{"type":"object","description":"Score set for one audit (0-100, null when not evaluated in this run).","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}},"deltas":{"type":"object","description":"Change in each score versus the previous audit.","properties":{"overall":{"type":["integer","null"]},"citability":{"type":["integer","null"]},"brand":{"type":["integer","null"]},"eeat":{"type":["integer","null"]},"technical":{"type":["integer","null"]},"schema":{"type":["integer","null"]},"platform":{"type":["integer","null"]}}}}},{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"projectSlug":{"type":"string"}}}]}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"403":{"description":"Key role or scope does not allow this operation, or API access is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"404":{"description":"Resource not found or outside the key's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}},"429":{"description":"Rate limit reached (see Retry-After), audit requested too recently, or the project is at its usage cap.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."}},"required":["error"]}}}}}}}},"webhooks":{"audit_run.completed":{"post":{"summary":"Audit completed","description":"Sent to your configured webhook endpoints when an audit finishes. The payload carries ids and the overall score; fetch detail through the API. Verify the X-CiteSurge-Signature header (t=<unix>,v1=<HMAC-SHA256 of \"<t>.<raw body>\" using your endpoint's signing secret).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["audit_run.completed","audit_run.failed"]},"auditRunId":{"type":"string"},"projectId":{"type":"string"},"projectSlug":{"type":"string"},"status":{"type":"string"},"overallScore":{"type":["integer","null"]},"runDate":{"type":"string","format":"date-time"},"occurredAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx status."}}}}}}