Getting started

Build your first authenticated call to the AIR API, then confirm you can reach your domain and projects.

Audience

Integrators wiring AIR into CI pipelines, GRC platforms, or internal automation. You will use a domain-scoped bearer API key, not a browser login for day-to-day API calls.

What you'll accomplish

1. Obtain an API key from the AIR portal (one-time setup).
2. Call the API with Authorization: Bearer.
3. Verify access to your domain and projects.

Base URL

Resource	URL
API	https://api.air.thalus.ai
Documentation	https://air.thalus.ai/docs
OpenAPI JSON	https://api.air.thalus.ai/openapi.json

Prerequisites

Requirement	Why
AIR organization	Your company must have an active AIR account
Domain owner or admin (for key setup)	Only domain owners and admins can create API keys in the portal
Target domain	Keys are scoped to a single domain
Active billing	Assessment runs consume org credits

If you lack portal access, ask your AIR admin to provision a key (see below).

Obtain an API key

API keys are domain-scoped bearer credentials tied to a service account.

Portal setup

1. Sign in at https://air.thalus.ai.
2. Select the organization that owns your integration.
3. Open the domain where your projects live (domain switcher in the sidebar).
4. Open API Keys for that domain.
5. Create a service account (for example, CI pipeline).
6. Create an API key — choose scopes (presets), copy the key, and store it in your secrets manager. Domain admins can copy active keys again later from the keys table in the portal.

::: tip Admin-provisioned keys Your admin can create keys for you. Share the domain name, use case, and required scopes. You only need the rawKey to call the API. :::

First authenticated request

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

Expect 200:

{
  "name": "AIR API",
  "status": "ok",
  "docs": "/docs",
  "openapi": "/openapi.json"
}

Confirm domain access

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

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

Requires domains:read. Save domainPid and projectPid from the responses — you do not need org or domain slugs for typical automation. See Concepts.

Success criteria

You are ready when:

1. GET / returns 200 with "status": "ok".
2. GET /domains/ returns your domain and GET /domains/<domainPid>/projects lists the target project.

Symptom	Likely cause
401	Invalid or revoked key
403 — missing scope	Key lacks scope for that route — see Authentication
404 on project routes	Key is for a different domain

Next steps

Goal	Start here
Use AIR from your IDE / agent	MCP server setup
Understand the pipeline	Concepts
Full upload → assess → report	Integration flow
Scopes and key rules	Authentication
Poll async work	Async jobs

Related

• Concepts — what AIR does and how resources relate
• Authentication — scopes and domain scoping
• API reference — interactive OpenAPI explorer