Skip to main content

Concepts

Audience​

Integrators planning an AIR automation. Read this first to understand what AIR does, how resources relate, and how the assessment pipeline works.

What AIR does​

AIR (AI Responsibly) helps organizations profile AI systems against governance frameworks — mapping evidence to controls, surfacing risks, and producing structured assessment reports.

Integrators use the HTTP API to automate that workflow: upload system documentation, wait for extraction, run the risk pipeline, and pull reports into CI, GRC tools, or internal dashboards.

Value chain​

  1. Evidence — PDFs, Word docs, and similar files uploaded as project sources (kind: document).
  2. Extraction — Background processing parses documents into artifacts (text chunks the pipeline can cite).
  3. Assessment — The risk pipeline evaluates artifacts against the control catalog and produces findings.
  4. Report — A JSON report you fetch when the run completes (risk register, control matrix, regulatory lens views).

Prerequisites​

RequirementNotes
Domain-scoped API keyEach key is fixed to one domain; use a separate key per domain
Target projectCreated in the portal or via POST /domains/:domainPid/projects (domains:write)
Org creditsStarting an assessment consumes credits; insufficient credits return 402
Matching scopesSee Authentication

Typical automation loop​

  1. Discover domainPid and projectPid via GET /domains/ and GET /domains/:domainPid/projects.
  2. Upload documents (upload-init → PUT → upload-complete).
  3. Poll GET /projects/:projectPid/documents until extraction finishes.
  4. List GET /projects/:projectPid/artifacts and collect artifact pids for the assessment.
  5. POST /assessments/projects/:projectPid with name and artifactPids.
  6. Poll GET /assessments/:assessmentPid until status is completed.
  7. GET /assessments/:assessmentPid/report.

See Integration flow for copy-paste request examples.

Read-only path​

If you only pull completed reports (no uploads or new assessments):

  1. GET /domains/ → domainPid
  2. GET /domains/:domainPid/projects → projectPid
  3. GET /assessments/projects/:projectPid → pick assessmentPid with status: completed
  4. GET /assessments/:assessmentPid/report

Requires assessments:read, projects:read, and domains:read. See Authentication.

Resource hierarchy​

Organization (org)
  └── Domain (dom)
        └── Project (prj)
              ├── Sources (psrc) — uploaded documents and connectors
              ├── Artifacts (artf) — extracted text/chunks from sources
              └── Assessments (pasm) — risk pipeline runs

Service accounts and API keys live at the domain level. A key minted in one domain cannot access resources in another.

Public ids (pids)​

External APIs use pids, not internal database ids. Format: a prefix, underscore, then 16 Crockford base32 characters (for example, prj_1A2B3C4D5E6F7G8H). Treat pids as opaque strings.

Common prefixes: org_, dom_, prj_, psrc_, artf_, pasm_, svc_ (service account), ak_ (API key).

Slugs vs pids​

For API automation, use pids. They are returned by list and create endpoints (dom_…, prj_…). Store domainPid and projectPid in your secrets or CI variables after discovery.

Slugs are short names in portal URLs (for example, acme-corp, payments, chatbot-v2). They are not required for most integrations.

IdentifierHow integrators get it
domainPidGET /domains/ (one domain per API key)
projectPidGET /domains/:domainPid/projects
SlugsPortal address bar, team config, or POST /search — only for optional slug lookup routes

Optional slug lookups when you already know all three slugs: GET /orgs/:orgSlug, GET /domains/lookup/:orgSlug/:domainSlug, GET /projects/lookup/:orgSlug/:domainSlug/:projectSlug.

GET /domains/ does not return orgSlug. Slug lookup returns 404 when the project is outside the key's domain.

Discovery limits​

LimitationWorkaround
List all domains in an orgAPI keys see only their own domain; use one key per domain
Create or revoke API keys via APIUse the AIR portal
Org-wide portfolio dashboardsNot available with API keys; use domain portfolio or portal
Completion webhooksPoll documents and assessments — see Async jobs

Billing and credits​

Assessment runs consume organization credits. When credits are exhausted, POST /assessments/projects/:projectPid may return 402 Payment Required.

Integrators cannot purchase credits via the API. Contact your organization's AIR admin or billing owner to top up. Upload and read endpoints are not credit-gated; only starting (and some retry) assessment operations are.

Assessment report structure​

GET /assessments/:assessmentPid/report returns a large JSON document. Key sections integrators typically export:

SectionPurpose
overviewCounts: total risks, required/implemented/missing controls
riskRegisterIdentified risks with severity and evidence links
controlMatrixControl assignments and implementation status
lensViews.euAiActEU AI Act–oriented rows
lensViews.iso42001ISO 42001–oriented rows
lensViews.nistAiRmfNIST AI RMF–oriented rows
euAiActTierEU AI Act tier classification when available
evidenceAppendixCited text chunks from source artifacts
inputArtifactsArtifacts included in the assessment run

Use the API reference for every field. For stage-level debugging when status is failed, use GET /assessments/:assessmentPid/stages.

Archival vs delete​

  • Documents: Deleting a document archives derived artifacts that may be assessment evidence.
  • Artifacts: POST .../archive hides from default lists; hard delete returns 409 when cited by an assessment.
  • Domains / projects: Delete endpoints remove the container; see the API reference for cascade behavior.

Long-running work​

Document extraction and risk assessments run asynchronously. Poll document status and assessment status rather than blocking on a single request. See Async jobs.

Time fields​

API JSON uses ISO-8601 UTC strings for timestamps unless noted otherwise in the schema.