{"openapi":"3.0.0","info":{"title":"AccessioAI Public API v1","version":"1.0.0","description":"Programmatic access to accessibility scans, alt-text, embed scripts, and usage quotas. Authenticate with the `X-API-Key` header (service-account key issued from the dashboard). Every response includes a `disclaimer` and `scanSchemaVersion`; agent clients that cache results MUST revalidate when `scanSchemaVersion` changes."},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/ai-act/evidence":{"get":{"summary":"List evidence ledger entries for the organization.","description":"Returns the append-only evidence ledger entries with SHA-256 chain verification status. Requires the `ai-act:read` scope.","tags":["AiAct"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Evidence ledger entries."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:read or AI Act access is denied."},"429":{"description":"Rate limit exceeded."}}}},"/v1/ai-act/reports":{"get":{"summary":"Export a regulator-ready AI Act transparency report.","description":"Returns JSON (default) or PDF with AI content items, labels, exemptions, an evidence ledger snapshot, and chain verification status. Request PDF via `?format=pdf` or `Accept: application/pdf`. Requires the `ai-act:read` scope.","tags":["AiAct"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Regulator-ready report."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:read or AI Act access is denied."},"429":{"description":"Rate limit exceeded."}}}},"/v1/ai-content/{id}":{"get":{"summary":"Get a single AI content item.","description":"Returns the item with its label, provenance record, and editorial review if present. Requires the `ai-act:read` scope.","tags":["AiContent"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"AI content item."},"400":{"description":"Malformed id."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:read or AI Act access is denied."},"404":{"description":"Not found or not owned by the authenticated org."},"429":{"description":"Rate limit exceeded."}}},"patch":{"summary":"Update AI content status.","description":"Confirm (CONFIRMED), dismiss (DISMISSED with rationale), or exempt (EXEMPT with editorial review payload) an AI content item. Each state change appends an EvidenceLedgerEntry. Requires the `ai-act:write` scope.","tags":["AiContent"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["confirm"]}}},{"type":"object","additionalProperties":false,"required":["action","rationale"],"properties":{"action":{"type":"string","enum":["dismiss"]},"rationale":{"type":"string","maxLength":5000}}},{"type":"object","additionalProperties":false,"required":["action","editorialReview"],"properties":{"action":{"type":"string","enum":["exempt"]},"editorialReview":{"type":"object","additionalProperties":false,"required":["responsiblePersonName"],"properties":{"responsiblePersonName":{"type":"string","maxLength":255},"responsiblePersonRole":{"type":"string","maxLength":255},"reviewedAt":{"type":"string","format":"date-time"},"note":{"type":"string","maxLength":5000},"reviewEvidenceUrl":{"type":"string","format":"uri","maxLength":2048}}}}}]}}}},"responses":{"200":{"description":"Updated AI content item."},"400":{"description":"Invalid id or body."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:write or AI Act access is denied."},"404":{"description":"Not found."},"409":{"description":"Item is not in a state that allows this action."},"422":{"description":"Exemption review is invalid."},"429":{"description":"Rate limit exceeded."}}}},"/v1/ai-content/detect":{"post":{"summary":"Ingest AI-content detection candidates from the Java widget.","description":"Accepts an array of candidate items with basis=DETECTED. Items are stored as PENDING/DETECTED advisory records; no labels are rendered. Requires a widget JWT for the embed script (add-on not required for ingest; labels/config remain add-on gated).","tags":["AiContent"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["embedScriptId","items"],"properties":{"embedScriptId":{"type":"string","format":"uuid"},"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"required":["contentRef","contentType"],"properties":{"contentRef":{"type":"string","maxLength":512},"contentType":{"type":"string","enum":["CHATBOT","IMAGE","AUDIO","VIDEO","TEXT"]},"obligation":{"type":"string","enum":["INTERACTION_50_1","DEEPFAKE_50_3","PUBLIC_TEXT_50_4","PROVIDER_MARK_50_2"]},"detectionConfidence":{"type":"number","minimum":0,"maximum":1},"detectionReason":{"type":"string","maxLength":2000},"detectionMethod":{"type":"string","maxLength":100},"detectionModel":{"type":"string","maxLength":100},"contentLocale":{"type":"string","maxLength":10},"sourceUrl":{"type":"string","maxLength":2048},"pageUrl":{"type":"string","maxLength":2048},"previewText":{"type":"string","maxLength":500}}}}}}}}},"responses":{"200":{"description":"Ingestion summary."},"400":{"description":"Invalid body."},"401":{"description":"Missing or invalid widget token."},"429":{"description":"Rate limit exceeded."}}}},"/v1/ai-content":{"get":{"summary":"List AI content items for the organization.","description":"Newest-first, cursor paginated. Optional filters by status, obligation, basis, and embedScriptId. Requires the `ai-act:read` scope.","tags":["AiContent"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","CONFIRMED","LABELED","EXEMPT","DISMISSED"]}},{"name":"obligation","in":"query","schema":{"type":"string","enum":["INTERACTION_50_1","DEEPFAKE_50_3","PUBLIC_TEXT_50_4","PROVIDER_MARK_50_2"]}},{"name":"basis","in":"query","schema":{"type":"string","enum":["DECLARED","PROVENANCE","DETECTED"]}},{"name":"embedScriptId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"AI content list."},"400":{"description":"Invalid query."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:read or AI Act access is denied."},"429":{"description":"Rate limit exceeded."}}},"post":{"summary":"Declare new AI content.","description":"Creates an AiContentItem with basis DECLARED by default. For DECLARED or PROVENANCE basis a compliance-grade AiLabel is created; DETECTED basis is advisory and does not create a label. A ProvenanceRecord is created when `provenance` is supplied. Requires the `ai-act:write` scope.","tags":["AiContent"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["embedScriptId","contentRef","contentType","obligation"],"properties":{"embedScriptId":{"type":"string","format":"uuid"},"contentRef":{"type":"string","maxLength":512},"contentType":{"type":"string","enum":["CHATBOT","IMAGE","AUDIO","VIDEO","TEXT"]},"obligation":{"type":"string","enum":["INTERACTION_50_1","DEEPFAKE_50_3","PUBLIC_TEXT_50_4","PROVIDER_MARK_50_2"]},"basis":{"type":"string","enum":["DECLARED","PROVENANCE","DETECTED"],"default":"DECLARED"},"contentLocale":{"type":"string","maxLength":10},"provenance":{"type":"object","additionalProperties":false,"properties":{"standard":{"type":"string","maxLength":50},"digitalSourceType":{"type":"string","maxLength":50},"manifestHash":{"type":"string","maxLength":255},"claimGenerator":{"type":"string","maxLength":255},"rawManifest":{"type":"object"},"signatureValid":{"type":"boolean"}}}}}}}},"responses":{"201":{"description":"AI content created."},"400":{"description":"Invalid body."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant ai-act:write or AI Act access is denied."},"404":{"description":"Embed script not found."},"429":{"description":"Rate limit exceeded."}}}},"/v1/alt-text/{id}/approve":{"post":{"summary":"Approve a pending alt-text suggestion.","description":"Transitions the record to APPROVED (or EDITED when `approvedText` differs from the generated text). Only PENDING records can be approved; non-PENDING records return 409. The state change and audit row commit atomically in a single transaction. Requires the `alt-text:approve` scope.","tags":["AltText"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"approvedText":{"type":"string","minLength":1,"maxLength":2000},"longDescription":{"type":"string","minLength":1,"maxLength":10000}}}}}},"responses":{"200":{"description":"Approved record."},"400":{"description":"Invalid id","body":null,"or JSON.":null},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant alt-text:approve."},"404":{"description":"Not found or not owned by the authenticated org."},"409":{"description":"Record is not in PENDING state."},"413":{"description":"Payload too large."},"415":{"description":"Unsupported media type."},"429":{"description":"Rate limit exceeded."}}}},"/v1/alt-text/{id}/reject":{"post":{"summary":"Reject a pending alt-text suggestion.","description":"Transitions the record to REJECTED with a reason. Only PENDING records can be rejected; non-PENDING records return 409. The state change and audit row commit atomically in a single transaction. Requires the `alt-text:approve` scope.","tags":["AltText"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","enum":["DECORATIVE","ALREADY_MEANINGFUL","NEEDS_LONG_DESC","BRAND_SPECIFIC","OTHER"]}}}}}},"responses":{"200":{"description":"Rejected record."},"400":{"description":"Invalid id","body":null,"or JSON.":null},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant alt-text:approve."},"404":{"description":"Not found or not owned by the authenticated org."},"409":{"description":"Record is not in PENDING state."},"413":{"description":"Payload too large."},"415":{"description":"Unsupported media type."},"429":{"description":"Rate limit exceeded."}}}},"/v1/alt-text/{id}":{"get":{"summary":"Get a single alt-text suggestion by id.","description":"Returns the alt-text record if it belongs to the authenticated organization, otherwise 404. Requires the `alt-text:read` scope.","tags":["AltText"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Alt-text record."},"400":{"description":"Malformed id."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant alt-text:read."},"404":{"description":"Not found or not owned by the authenticated org."},"429":{"description":"Rate limit exceeded."}}}},"/v1/alt-text":{"get":{"summary":"List generated alt-text suggestions for the organization.","description":"Newest-first, cursor paginated. Optional filters by status and embedScriptId. Requires the `alt-text:read` scope.","tags":["AltText"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","EDITED","REJECTED"]}},{"name":"embedScriptId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Alt-text suggestions list."},"400":{"description":"Invalid query."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant alt-text:read."},"429":{"description":"Rate limit exceeded."}}}},"/v1/embed-scripts":{"get":{"summary":"List embed scripts for the authenticated organization.","description":"Returns embed-script metadata — website URL, status, whitelabel labels, trial/expiry timestamps. Does NOT return the script token or its hash. Requires the `embed:read` scope.","tags":["EmbedScripts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","maxLength":20}}],"responses":{"200":{"description":"Embed script list."},"400":{"description":"Invalid query or cursor."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant embed:read."},"429":{"description":"Rate limit exceeded."}}}},"/v1/organization":{"get":{"summary":"Get organization details for the authenticated API key.","description":"Returns name + public contact fields for the organization the API key belongs to. Replaces the legacy `/organization` endpoint, which predates the scope model and silently allowed any valid key to read these fields. Requires the `org:read` scope.","tags":["Organization"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Organization details."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant org:read."},"404":{"description":"Organization not found."},"429":{"description":"Rate limit exceeded."}}}},"/v1/quota":{"get":{"summary":"Current-month usage and plan limits for the organization.","description":"Returns the cached quota snapshot (currentUsage / quotaLimit / tier / isOverQuota) for the authenticated organization. BigInt counters are serialized as strings to avoid JS precision loss. Requires the `quota:read` scope.","tags":["Quota"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Quota snapshot."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant quota:read."},"429":{"description":"Rate limit exceeded."}}}},"/v1/scans/{id}/issues":{"get":{"summary":"List WCAG issues for a scan session.","description":"Returns issues ordered by priority (highest first), then newest. Optional severity / status filters. Raw HTML is never returned in this endpoint. Requires the `scans:read` scope.","tags":["Scans"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"severity","in":"query","schema":{"type":"string","enum":["CRITICAL","SERIOUS","MODERATE","MINOR"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","CONFIRMED","FIXED","WONT_FIX","FALSE_POSITIVE","SUPPRESSED"]}}],"responses":{"200":{"description":"Issues list."},"400":{"description":"Invalid id or query parameters."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant scans:read."},"404":{"description":"Scan session not found in this organization."},"429":{"description":"Rate limit exceeded."}}}},"/v1/scans/{id}":{"get":{"summary":"Get a single scan session by id.","description":"Returns the scan session if it belongs to the authenticated organization, otherwise 404. Requires the `scans:read` scope.","tags":["Scans"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Scan session."},"400":{"description":"Malformed id."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant scans:read."},"404":{"description":"Not found or not owned by the authenticated org."},"429":{"description":"Rate limit exceeded."}}}},"/v1/scans/{id}/run":{"post":{"summary":"Queue a re-run of an existing scan session.","description":"Records the intent to re-scan on both sides of the Node/JVM boundary (single shared requestId) and returns 202. Supply an `Idempotency-Key` header to make retries safe; the cached response replays on duplicate keys within 24h. Requires the `scans:write` scope.","tags":["Scans"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}],"responses":{"202":{"description":"Run accepted."},"400":{"description":"Malformed id or idempotency key."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant scans:write."},"404":{"description":"Scan session not found in this organization."},"429":{"description":"Rate limit exceeded."},"502":{"description":"Upstream accessio-service rejected or was unreachable."}}}},"/v1/scans":{"get":{"summary":"List accessibility scan sessions for the authenticated organization.","description":"Returns scan sessions newest-first. Paginate with cursor (last id from previous page). Rate limited to 60 requests / minute per API key. Requires the `scans:read` scope.","tags":["Scans"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Scan sessions list."},"400":{"description":"Invalid query parameters or cursor."},"401":{"description":"Missing or invalid API key."},"403":{"description":"API key does not grant scans:read."},"429":{"description":"Rate limit exceeded."}}}}},"tags":[]}