Integration flow

Audience

Integrators running a full pipeline: discover resources, upload evidence, run an assessment, fetch the report.

Prerequisites

• Domain-scoped API key from the AIR portal — see Getting started
• Scopes for your path — see Recommended presets
• domainPid and projectPid (discover in step 2, or use values from CI config)

Base URL: https://api.air.thalus.ai

For concepts, discovery limits, and report structure, see Concepts.

Overview

1. Verify authentication

curl -sS 'https://api.air.thalus.ai/' \
  -H 'Authorization: Bearer <rawKey>'

Expect 200 with "status": "ok".

2. Discover domain and project

Default: list by pid (no slugs required).

curl -sS 'https://api.air.thalus.ai/domains/' \
  -H 'Authorization: Bearer <rawKey>'

Save pid as <domainPid>, then:

curl -sS 'https://api.air.thalus.ai/domains/<domainPid>/projects' \
  -H 'Authorization: Bearer <rawKey>'

Save the target row's pid as <projectPid>. Pagination: ?page=1&pageSize=20&search=chatbot.

Optional: slug lookup when CI config already has portal slugs — see Concepts — Slugs vs pids.

3. Upload a document

Presigned flow (see Uploads for limits and failures).

Init:

curl -sS -X POST 'https://api.air.thalus.ai/projects/<projectPid>/documents/upload-init' \
  -H 'Authorization: Bearer <rawKey>' \
  -H 'Content-Type: application/json' \
  -d '{"filename":"system-overview.pdf","contentType":"application/pdf"}'

Save uploadUrl and the storage key from the response.

PUT file bytes to uploadUrl (no Authorization header; same Content-Type).

Complete:

curl -sS -X POST 'https://api.air.thalus.ai/projects/<projectPid>/documents/upload-complete' \
  -H 'Authorization: Bearer <rawKey>' \
  -H 'Content-Type: application/json' \
  -d '{
    "s3Key": "<storage key from init>",
    "filename": "system-overview.pdf",
    "contentType": "application/pdf"
  }'

Save sourcePid from the response for polling.

4. Poll extraction

curl -sS 'https://api.air.thalus.ai/projects/<projectPid>/documents' \
  -H 'Authorization: Bearer <rawKey>'

Find the row where pid matches sourcePid. Poll until status is connected (or error — check lastError). See Async jobs for intervals.

When ready, list artifacts:

curl -sS 'https://api.air.thalus.ai/projects/<projectPid>/artifacts' \
  -H 'Authorization: Bearer <rawKey>'

5. Start an assessment

Up to five artifactPids per run.

curl -sS -X POST 'https://api.air.thalus.ai/assessments/projects/<projectPid>' \
  -H 'Authorization: Bearer <rawKey>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CI assessment",
    "artifactPids": ["<artf_pid>"]
  }'

Expect 202. Save assessmentPid.

6. Poll and fetch report

curl -sS 'https://api.air.thalus.ai/assessments/<assessmentPid>' \
  -H 'Authorization: Bearer <rawKey>'

When status is completed (or reportAvailable is true):

curl -sS 'https://api.air.thalus.ai/assessments/<assessmentPid>/report' \
  -H 'Authorization: Bearer <rawKey>'

Report sections: see Concepts — Assessment report structure. On failure: GET /assessments/<assessmentPid>/stages.

Troubleshooting

Symptom	Likely cause	What to do
404 on project or assessment	Key is for a different domain	Mint a key in the correct domain
403 — missing scope	Key lacks required scope	New key with scopes from Authentication
402 on start assessment	Insufficient org credits	Contact your org admin
409 on upload-complete	Stale or duplicate storage key	Re-run init and PUT
Source stuck in processing	Large file or extraction error	Check lastError; see Uploads
Assessment failed	Pipeline error	GET /assessments/<assessmentPid>/stages

More status codes: Errors.

Related

• Concepts — hierarchy, pids, report shape, billing
• Uploads — presigned flow and file limits
• Async jobs — polling intervals
• API reference — every endpoint and schema