disclosures
Tamper-evident (hash-chained) AI-disclosure evidence and the served jurisdiction disclosure policy.
| Method | Path | Operation ID |
|---|---|---|
| GET | /v1/disclosures/events |
listDisclosureEvents |
| POST | /v1/disclosures/events |
createDisclosureEvent |
| GET | /v1/disclosures/policies |
getDisclosurePolicies |
GET /v1/disclosures/events
Section titled “GET /v1/disclosures/events”Operation ID: listDisclosureEvents
List the account’s disclosure events in sequence order with the chain head.
List (and export, by paging) the account’s disclosure events in sequence order, with the chain head so a reader can verify the hashes.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor |
query | string or null | no | |
limit |
query | integer | no | Minimum 1. Maximum 1000. Default 100. |
kind |
query | DisclosureEventKind or null | no | |
jurisdiction |
query | string or null | no | |
received_after |
query | string or null | no | |
received_before |
query | string or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json DisclosureEventPage |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
chain_head |
DisclosureChainHead or null | yes | The account’s latest event at the time of the read; null when empty. |
data |
array of DisclosureEventRecord | yes | Ascending sequence order. |
next_cursor |
string or null | yes |
POST /v1/disclosures/events
Section titled “POST /v1/disclosures/events”Operation ID: createDisclosureEvent
Append one AI-disclosure event to the account’s hash-chained log.
Append one disclosure event to the account’s hash-chained log and return its receipt. A replay with the same Idempotency-Key and body returns the original receipt; a different body under the same key is 422 DISCLOSURE_INVALID. Callable from a browser with a publishable key (scope disclosure:write only). A key with allowed_origins answers only to those sites (403 API_KEY_ORIGIN_NOT_ALLOWED otherwise), and the verified site is recorded on the event as origin. The log is tamper-evident, not externally anchored: keep the receipts you are given.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Request body
Section titled “Request body”application/json: DisclosureEventRequest (required)
| Field | Type | Required | Description |
|---|---|---|---|
client_time |
string | yes | When the client showed it. Recorded beside the server’s received_at. |
content_ref |
string or null | no | Your opaque reference for the content labelled, e.g. an ast_ asset id. |
jurisdiction |
enum | yes | The jurisdiction rule set the client applied (GET /v1/disclosures/policies). One of: EU, US-CA, US-ME, US-NH, US-NY, US-UT, IN, CN, KR. |
kind |
DisclosureEventKind | yes | ai_interaction_notice: an AI-interaction notice was shown; visible_label_offered: a visible AI label was offered; visible_label_applied: one was applied to the content; user_acknowledged: the person acknowledged a notice. One of: ai_interaction_notice, visible_label_offered, visible_label_applied, user_acknowledged. |
locale |
string or null | no | The BCP 47 language the disclosure was shown in. |
policy_version |
string | yes | The policy_version the client applied. Pattern: ^\d{4}-\d{2}-\d{2}\.\d{1,3}$. |
rule_id |
string or null | no | The rule the client applied. |
subject_ref |
string | yes | Your opaque reference for the person or session shown the disclosure. Never an email address or name: use a pseudonymous id you can map back yourself. Pattern: ^[A-Za-z0-9._:~-]{1,128}$. |
surface |
enum or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json DisclosureEventReceipt |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | DISCLOSURE_INVALID: unknown kind, jurisdiction, policy version or rule; a malformed reference or time; or an Idempotency-Key reused with a different body. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
201 response fields
Section titled “201 response fields”| Field | Type | Required | Description |
|---|---|---|---|
event_id |
string | yes | Pattern: ^dse_[a-z2-7]{16}$. |
hash |
string | yes | sha256 over the canonical JSON of the stored record (see the docs). Pattern: ^sha256:[0-9a-f]{64}$. |
prev_hash |
string | yes | Pattern: ^sha256:[0-9a-f]{64}$. |
received_at |
string | yes | |
sequence |
integer | yes | This event’s position in the account’s chain. Minimum 1. |
GET /v1/disclosures/policies
Section titled “GET /v1/disclosures/policies”Operation ID: getDisclosurePolicies
Read the versioned jurisdiction disclosure rules (draft, needs legal review).
Unauthenticated. The jurisdiction disclosure rules (op.disclosure-policy.2026-10.v1), current version unless version names an earlier one. Draft text flagged needs_legal_review. Accepts any origin; publicly cacheable.
Authentication: none (anonymous).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
version |
query | string or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json DisclosurePolicyDocument |
| 404 | DISCLOSURE_POLICY_NOT_FOUND: no policy has this version. | application/json ErrorResponse |
| 422 | DISCLOSURE_INVALID: the version is malformed. | application/json ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
badge_sets |
array of DisclosureBadgeSet | yes | |
disclaimer |
string | yes | |
jurisdictions |
array of DisclosureJurisdictionPolicy | yes | |
needs_legal_review |
boolean | yes | |
policy_version |
string | yes | |
published_at |
string | yes | |
schema_version |
const “op.disclosure-policy.2026-10.v1” | yes |