POST /v1/score One endpoint. One number.

Right-level your AI. Programmatically.

Five questions about how your team uses AI. One HTTP call. A score per role, and what to do next.

No SDK required Free tier: 60 requests/minute

What is the CAI score?

Cognitive Autonomy Index — the right level of AI autonomy for a position, not a person. Does the skill the work needs match the level the tools are cleared for? Five behavioural questions produce the three parameters it weighs:

L_c 1–4: How the team uses AI today — ad-hoc prompting through to a full agentic mesh.
S 2–5: The skill needed to run and fix AI without IT.
L_t 1–4: How far the tools are cleared to go, safely and compliantly. L_t is the strictest of three ceilings — regulation, reversibility, and detection — not their average. An error you would never notice forces L_t to 1, whatever the other two say.

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

Quickstart

Your first score in 30 seconds

Five answers, one industry. The whole call:

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

Every endpoint, straight from the spec

Generated from the OpenAPI document. It can’t drift.

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, one shape

Same envelope every time — { "error": { "code": "…", "message": "…" } }. Switch on code; message is for humans.

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