Developer guide

Developer API & integration guide

Build Article 50 transparency workflows into customer websites, SaaS products, CMS integrations, and internal review systems.

Start with the quickstart View examples

Developer workflow

Use SUNURA APIs to classify an AI use case, generate a disclosure, install the notice, capture evidence, and export audit-ready records.

Classify the AI use case

Create a structured disclosure record for a customer-facing AI feature, chatbot, content tool, or automated workflow.

Generate the notice

Return approved disclosure copy and deployment metadata for the surface where the AI interaction appears.

Install the notice

Use server-side calls, a CMS snippet, or a controlled widget integration. Do not expose secret API keys in browser JavaScript.

Capture evidence

Record when the notice is rendered, which version was shown, and which public verification reference belongs to it.

Export records

Create evidence records, PDF exports, JSON exports, and verification references for review or internal governance.

Route guidance

Use /api/v1/* for customer websites, SaaS applications, widgets, CMS plugins, and server automations. Dashboard workflow routes such as /api/article50/* are reserved for SUNURA dashboard operations and reviewer workflows.

Agency note

API keys are workspace-wide access credentials. For Agency customer workflows, pass clientWorkspaceId only to endpoints that explicitly support customer-scoped evidence. Never display server-side API keys in browser code or on customer websites.

Code examples

Use these examples as implementation patterns. Production integrations should call SUNURA from a server you control.

Classify a disclosure

API key required

curl -X POST https://review.getsunura.com/api/v1/disclosures/classify \
  -H "x-sunura-api-key: $SUNURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI assistant","description":"Customer service chatbot","aiSystemType":"chatbot","jurisdiction":"EU"}'

Generate a notice

API key required

const response = await fetch("https://review.getsunura.com/api/v1/disclosures/generate", {
  method: "POST",
  headers: {
    "x-sunura-api-key": process.env.SUNURA_API_KEY ?? "",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    disclosureId: "disc_123",
    surface: "customer-website"
  })
});

Core data model

Disclosure: the approved AI notice and its legal/operational metadata.
Evidence record: a timestamped record showing when and where a notice was rendered.
Verification reference: a public reference that lets reviewers inspect the relevant disclosure state.
Export package: a PDF, JSON, CSV, or ZIP export for internal governance and external review.

Security and implementation rules

Keep secret API keys on the server side.
Use least-privilege keys for test and production workspaces.
Do not hard-code customer secrets in CMS templates.
Log deployment version, disclosure version, and runtime evidence identifiers.
Separate dashboard reviewer workflows from customer production integrations.