POST /v1/score One endpoint. One number.

Right-level your AI. Programmatically.

The CAI Score API turns the CAI Framework into a single HTTP call. Send five behavioural answers plus a role roster, and receive a score, a zone, and suggestions per role.

Try it live Read the reference

No SDK required Free tier: 60 requests/minute

What is the CAI score?

Cognitive Autonomy Index: a score for a position — it tells you the right level of AI autonomy, whether the skills required match the level the tools are cleared for. Five behavioural questions produce the three parameters it weighs:

L_c 1–4: How AI is used today — from basic ad-hoc prompting to a full agentic mesh.
S 2–5: The competency required to run and troubleshoot AI without IT.
L_t 1–4: The ceiling of AI tools that are safe and compliant to operate at. L_t is the strictest of three ceilings — regulation, reversibility, and detection — not their average. If you would not notice the error at all, detection forces L_t to 1 regardless of the other two.

stranded < 0.92: Stranded capability — the team has more tool than it uses.
right 0.92–1.08: Optimized alignment — usage, skill, and clearance in equilibrium.
risk > 1.08: Governance risk — the team has outrun what its tools are cleared for.

Quickstart

Your first score in 30 seconds

Send the five behavioural answers plus an industry, and read the score back.

curl https://api.caiscore.com/v1/score \
  -H "Authorization: Bearer $CAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "level": "integrated",
      "competence": "harness",
      "regulation": "mixed",
      "reversibility": "costly",
      "detection": "review"
    },
    "industry": "accounting-firm"
  }'

import os
import requests

r = requests.post(
    "https://api.caiscore.com/v1/score",
    headers={"Authorization": f"Bearer {os.environ['CAI_API_KEY']}"},
    json={
        "answers": {
            "level": "integrated",
            "competence": "harness",
            "regulation": "mixed",
            "reversibility": "costly",
            "detection": "review",
        },
        "industry": "accounting-firm",
    },
)

print(r.json()["aggregate"]["score"])

const response = await fetch("https://api.caiscore.com/v1/score", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    answers: {
      level: "integrated",
      competence: "harness",
      regulation: "mixed",
      reversibility: "costly",
      detection: "review",
    },
    industry: "accounting-firm",
  }),
});

const { aggregate } = await response.json();
console.log(aggregate.score);

Reference

The v1 surface, generated from the contract

Every parameter, request body, and response field below is read straight from the vendored OpenAPI document — nothing here is hand-written.

GET /v1/health

Liveness probe

Response fields (200)
Field	Type
`status`	string
`service`	string
`api_version`	string
`version`	string

GET /v1/questions

The five CAI questions and their option values

Response fields (200)
Field	Type
`meta`	object
`questions`	array

GET /v1/industries

Search the curated industry roster

Parameters
Name	In	Required	Type	Constraints	Description
`q`	query	Optional	string		Free-text match against label and curated synonyms.

Response fields (200)
Field	Type
`meta`	object
`industries`	array

GET /v1/industries/{id}

One industry, identifier and label only

Parameters
Name	In	Required	Type	Constraints	Description
`id`	path	Required	string

Response fields (200)
Field	Type
`industry`	object

GET /v1/occupations

Search-only occupation discovery

Parameters
Name	In	Required	Type	Constraints	Description
`q`	query	Required	string		At least two characters.
`limit`	query	Optional	integer	min 1; max 10; default 10

Response fields (200)
Field	Type
`meta`	object
`occupations`	array

GET /v1/occupations/{soc}

One occupation, identifier and label only

Parameters
Name	In	Required	Type	Constraints	Description
`soc`	path	Required	string

Response fields (200)
Field	Type
`occupation`	object

GET /v1/openapi.json

This document

POST /v1/score

Score a role roster against the five answers

Request body
Field	Type	Required
`answers`	object	Required
`occupations`	array	Optional
`industry`	string	Optional

Response fields (200)
Field	Type
`meta`	object
`params`	object
`posture`	array
`roles`	array
`aggregate`	object
`suggestions`	array

Errors

Every error code the v1 API returns

Every non-2xx response uses one envelope, { "error": { "code": "...", "message": "..." } }. Route error handling off code, read straight from the vendored reference below.

Code	Status	Where
`unauthorized`	401	A missing, malformed, or unknown key on any non-exempt route
`rate_limited`	429	An exhausted rate limit on any non-exempt route
`not_found`	404	Any request whose path matches no route
`method_not_allowed`	405	A matched path with the wrong HTTP method
`internal_error`	500	An unhandled failure, including a misconfigured key or rate-limit binding
`industry_not_found`	404	GET /v1/industries/:id — unknown id
`query_required`	400	GET /v1/occupations — missing or too-short q
`invalid_parameter`	400	GET /v1/occupations — out-of-range limit, or an offset parameter
`occupation_not_found`	404	GET /v1/occupations/:soc — unknown soc
`unsupported_media_type`	415	POST /v1/score — Content-Type is not application/json
`invalid_json`	400	POST /v1/score — body is not valid JSON
`invalid_body`	400	POST /v1/score — body is not a JSON object
`invalid_answers`	400	POST /v1/score — answers missing or malformed
`invalid_occupations`	400	POST /v1/score — occupations is not an array of strings
`invalid_industry`	400	POST /v1/score — industry is not a string
`industry_not_found`	404	POST /v1/score — unknown industry id
`missing_roster`	400	POST /v1/score — neither occupations nor industry given
`empty_roster`	400	POST /v1/score — resolved roster has zero entries
`roster_too_large`	400	POST /v1/score — resolved roster exceeds 25 entries
`occupation_not_found`	400	POST /v1/score — an occupations entry is an unknown SOC code