Skip to content

AOI API Documentation

America's Opportunity Index (AOI) provides intelligent access to U.S. employment and career data — occupations, companies, wages, hiring signals, career pathways, and AI-impact classifications.

Confidential · unstable beta

This documentation and the underlying data are SFF Confidential. Access is limited to authorized clients under your agreement; do not redistribute. The API is in beta — endpoints, commands, and response shapes are subject to change. Breaking changes are announced in the Changelog.

Start with DSL

DSL is the recommended interface. It is the full, forward-looking query surface — a superset of what REST offers — and it is where new capabilities land first. If you are integrating today, build on DSL.

- :material-code-braces: __DSL (recommended)__ The primary query language. Resolve titles, look up companies, wages, hiring, clusters, and pathways in one composable surface. [:octicons-arrow-right-24: DSL reference](dsl.md) - :material-robot: __MCP (agents)__ Model Context Protocol tool surface for AI agents — a single `aoi_dsl_query` tool that speaks DSL. [:octicons-arrow-right-24: MCP reference](mcp.md) - :material-history: __REST (legacy)__ The original endpoint-based API. Still supported for existing clients, but new work should prefer DSL. [:octicons-arrow-right-24: REST reference](rest.md) - :material-database: __Data dictionary__ Schema fields, allowed values, and which REST / DSL / MCP surfaces serve each table. [:octicons-arrow-right-24: Data dictionary](data-dictionary/index.md)

Base URL and authentication

  • Base URL: https://aonav.ai
  • Protocol: HTTPS only
  • Authentication: JWT Bearer token on every request
# 1. Obtain a token
curl -s -X POST https://aonav.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "<your-user>", "password": "<your-password>"}'

# 2. Call the API with the token (DSL example)
curl -s -X POST https://aonav.ai/api/dsl \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "TITLECONVERT \"registered nurse\""}'

All endpoints require authentication — there is no anonymous access.

Conventions

  • Responses are JSON. DSL success responses use {"status": "success", "data": [...], "count": N}.
  • Errors are structured with a code, message, and (where useful) a suggestion and example to guide recovery.
  • No pipe operators. DSL does not support | or ; chaining — multi-step workflows run as sequential queries. See the DSL reference.
  • TITLECONVERT pick: after convert returns a list and the user chooses a row, record it with SUBMIT TITLECONVERT (DSL/MCP) or POST /api/titleconvert (REST). Do not re-run the convert.