Quick Start

Before you begin

You need an Exona API key. If you don't have one yet:

Sign in at platform.exonalab.com
Go to Developers → API Keys
Click Create key, give it a name (e.g. "Integration test"), and copy it immediately: it is only shown once.

For this guide, use a test key (exo_test_...). It behaves identically to a live key but returns synthetic data and does not consume credits.

Step 1: Create a scan

Send a POST request with the company name and website.

import requests
 
API_KEY = "exo_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://platform.exonalab.com/api/v1"
 
response = requests.post(
    f"{BASE_URL}/scans",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "company_name": "Acme AI Ltd",
        "company_website": "https://acme.ai",
    },
)
 
scan = response.json()
print(scan)
# {
#   "id": "scn_test_01hx...",
#   "status": "processing",
#   "created_at": "2026-04-03T09:00:00Z"
# }

The API returns immediately with a scan ID and "status": "processing". Save the id: you will use it to retrieve the result.

Step 2: Poll for the result

Scans typically complete in 30–120 seconds. Poll the GET /v1/scans/{id} endpoint until status is "completed" or "failed".

import time
 
scan_id = scan["id"]
 
while True:
    result = requests.get(
        f"{BASE_URL}/scans/{scan_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()
 
    if result["status"] == "completed":
        print("Done:", result["result"]["risk_assessment"]["overall_risk_level"])
        break
    elif result["status"] == "failed":
        print("Failed:", result["error"]["message"])
        break
 
    print(f"Status: {result['status']}: retrying in 10s")
    time.sleep(10)

Step 3: Read the result

When status is "completed", the response includes the full result object.

{
  "id": "scn_test_01hx...",
  "status": "completed",
  "created_at": "2026-04-03T09:00:00Z",
  "completed_at": "2026-04-03T09:01:12Z",
  "company": {
    "name": "Acme AI Ltd",
    "website": "https://acme.ai"
  },
  "result": {
    "enrichment": {
      "industry_sector": "Technology",
      "revenue": "$10M–$50M",
      "business_operations": "Acme AI provides automated claims processing software for P&C insurers, using machine learning to assess claim validity and recommend payouts.",
      "product_category": "Insurance Technology (Insurtech)",
      "ai_in_product": "Core product is AI-driven: a computer vision model assesses vehicle damage from photos and a large language model extracts relevant facts from claim documents."
    },
    "risk_assessment": {
      "overall_risk_level": "High",
      "ai_intensity": { "score": 4, "label": "Autonomous Core", "rationale": "AI models make final claim recommendations with minimal human review." },
      "autonomy": { "score": 3, "label": "Fully Autonomous", "rationale": "Payouts are triggered automatically once the model confidence exceeds threshold." },
      "domain_risk": { "score": 3, "label": "High", "rationale": "Claims decisions have direct financial impact on policyholders." },
      "blast_radius": { "score": 2, "label": "Medium", "rationale": "Platform processes ~50,000 claims per month across 12 insurer clients." },
      "data_content_ip_risk": { "score": 2, "label": "Medium", "rationale": "Processes sensitive PII including medical records and financial data." },
      "control_governance": { "score": 2, "label": "Partial Controls", "rationale": "Human review applies only to claims above $50,000." },
      "regulatory_exposure": "Subject to financial services AI regulations in the EU (AI Act, high-risk category) and state insurance regulations in the US."
    },
    "matched_incidents": [
      {
        "description": "Automated claims denial system flagged as discriminatory due to biased training data.",
        "year": 2023,
        "risk_domain": "Algorithmic Bias",
        "similarity_score": 0.91,
        "reference_urls": ["https://example.com/report/123"]
      }
    ],
    "data_freshness": {
      "sources_last_checked": "2026-04-03T09:01:00Z"
    }
  }
}

Complete example

Here is the full script combining steps 1–3.

import requests
import time
 
API_KEY = "exo_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://platform.exonalab.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
 
# 1. Create the scan
response = requests.post(
    f"{BASE_URL}/scans",
    headers=HEADERS,
    json={
        "company_name": "Acme AI Ltd",
        "company_website": "https://acme.ai",
    },
)
response.raise_for_status()
scan_id = response.json()["id"]
print(f"Scan created: {scan_id}")
 
# 2. Poll until complete
while True:
    r = requests.get(f"{BASE_URL}/scans/{scan_id}", headers=HEADERS)
    r.raise_for_status()
    data = r.json()
 
    if data["status"] == "completed":
        print("Risk level:", data["result"]["risk_assessment"]["overall_risk_level"])
        break
    elif data["status"] == "failed":
        raise RuntimeError(data["error"]["message"])
 
    time.sleep(10)