Skip to content
Methodology

OpenAPI / API docs

ia.openapi · 4.5

Act SHOULD Measured study AR-ACT-02

Why it matters

OpenAPI specifications let AI agents understand and call your API programmatically. AI coding assistants and agent frameworks use OpenAPI to generate correct API calls automatically.

How to fix it

Publish an OpenAPI 3.x document at /openapi.json and link it.

  1. Generate an OpenAPI 3.1 document from the API code.

    {
  "openapi": "3.1.0",
  "info": {"title": "Example API", "version": "1.0.0"},
  "paths": {"/api/search": {"get": {"operationId": "search", "summary": "Search items"}}}
}

  2. Serve it at /openapi.json or /.well-known/openapi with HTTP 200.

  3. Link it from the API catalog and a service-desc Link header.

Verify

curl -sf https://{domain}/openapi.json | jq -e '.openapi | startswith("3.")'

Expected: exit code 0

Run a new scan for this checkpoint:

isagentready results {domain} --checkpoint ia.openapi
Details Mapping, lifecycle and references
AR mapping
Full match
Score role
Core
Introduced
2026-08-24
Methodology version
2026-10-22

Checkpoint data (JSON)