API Inventories: Documenting Endpoints Automatically

The api_inventory artifact provides AI with a complete catalog of every API endpoint in your application. Built automatically from OpenAPI specifications, framework route registrations, and BFF route files, the inventory tells AI about every endpoint without requiring it to scan route definitions at interaction time.

Use this page when

• You want AI to have a complete, pre-built catalog of your API endpoints without scanning route files at interaction time.
• You need to understand how api_inventory artifacts are built from OpenAPI specs, Axum routes, or Next.js BFF files.
• You are using API inventories for integration planning, migration, security auditing, or client code generation.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

What an API Inventory Contains

An api_inventory artifact catalogs your endpoints with structured metadata:

Endpoint Definitions

For each API endpoint, the inventory records:

• HTTP method and path pattern
• Request parameters (path, query, header)
• Request body schema
• Response schemas (success and error variants)
• Authentication requirements
• Rate limiting and quota rules

Route Registration Sources

Where each endpoint is defined in your codebase:

• Source file and line number
• Framework-specific registration pattern
• Router composition hierarchy
• Middleware chain applied to the route

Domain Groupings

How endpoints are organized logically:

• API version prefixes (/v1/, /v2/)
• Domain boundaries (auth, events, config, exports)
• Public vs. internal endpoints
• Admin-only routes

Schema Relationships

How request and response schemas relate:

• Shared types used across multiple endpoints
• Nested object structures
• Enum values and constraints
• Optional vs. required fields

How API Inventories Are Built

Context Fabric builds API inventories from multiple sources:

OpenAPI Specifications

If your project maintains an OpenAPI spec (YAML or JSON), the inventory starts there. The spec provides authoritative endpoint definitions, schemas, and documentation.

Axum Route Registrations

For Rust/Axum applications, the pipeline parses router composition:

• Router::new().route() declarations
• .nest() hierarchies for path prefixes
• .merge() compositions from domain modules
• Handler function signatures for type information

Next.js App Router BFF Routes

For Next.js applications, the pipeline discovers endpoints from the filesystem:

• route.ts files under app/api/ directories
• HTTP method exports (GET, POST, PUT, DELETE)
• Dynamic route segments from directory naming
• Middleware applied via middleware.ts

Express/Koa Route Files

For Node.js applications using Express or Koa:

• router.get(), router.post() registrations
• Route prefix mounting
• Middleware chains

How API Inventories Reduce Prompt Size

When an engineer asks "what endpoints handle authentication?" or "what's the request format for creating an event?", the AI traditionally needs to find and read route files, handler implementations, and type definitions.

A cached API inventory delivers this information in 1,000–3,000 tokens. Scanning route files, handlers, and schemas manually costs 10,000–50,000 tokens depending on your codebase size.

Use Cases

Integration Planning

When building a new feature that calls existing endpoints, the AI references the inventory to provide:

• Exact request formats with field types and constraints
• Authentication requirements and header expectations
• Error response shapes and status codes
• Rate limit considerations

Documentation Generation

The inventory serves as a source of truth for generating or updating API documentation. AI produces accurate endpoint descriptions because it references structured definitions rather than inferring from code.

Migration Planning

When migrating between API versions or restructuring routes, the AI uses the inventory to:

• List all endpoints affected by the migration
• Identify breaking changes in request/response schemas
• Map old endpoints to new equivalents
• Generate migration guides for consumers

Client Code Generation

When engineers need to call an endpoint from a new client, the AI generates type-safe request code directly from inventory schemas. No manual spec reading required.

Security Auditing

The inventory reveals:

• Endpoints without authentication requirements
• Admin routes that may need additional access controls
• Input fields that require validation
• Response fields that might leak sensitive data

Shared Across Your Organization

The API inventory is one of the most impactful shared artifacts. Every engineer who integrates with your API benefits from the same cached endpoint catalog:

• Backend engineers discover internal endpoints without reading route files
• Frontend engineers find BFF routes and their upstream mappings
• Platform engineers audit authentication and authorization coverage
• External integrators get accurate endpoint documentation

When API Inventories Regenerate

Regeneration triggers include:

• OpenAPI spec file changes
• New route files added
• Route registration modifications (new endpoints, changed paths)
• Handler signature changes (request/response type modifications)
• Middleware chain updates

Content changes within handler implementations (business logic) do not trigger regeneration unless they change the request/response contract.

Configuration

You configure api_inventory generation in your repository settings:

• Source priority — Prefer OpenAPI spec over code analysis, or merge both
• Include internal routes — Whether to catalog admin and internal-only endpoints
• Schema depth — How deeply to expand nested object schemas
• Version scoping — Catalog all API versions or only the latest

Next steps

• Symbol Indexes — Look up handler functions and types
• Dependency Graphs — Understand route-to-handler dependencies

For AI systems

• Canonical terms: Keeptrusts, Codebase Context Fabric, api_inventory artifact, endpoint catalog, OpenAPI spec, Axum route registration, Next.js App Router BFF routes, route mapping, schema relationships.
• Feature/config names: api_inventory artifact type, source priority (OpenAPI vs. code analysis), include internal routes, schema depth, version scoping, regeneration triggers (route file changes, OpenAPI spec changes, handler signature changes).
• Best next pages: Dependency Graphs, File Summaries, Fabric Slices Reduce Prompts.

For engineers

• API inventories are built from: OpenAPI specs (highest priority), Axum Router::new().route() patterns, Next.js app/api/ route files, and Express/Koa registrations.
• Regeneration triggers: new route files, route path changes, handler signature changes, middleware chain updates. Business logic changes within handlers do NOT trigger regeneration.
• Token savings: a cached inventory delivers endpoint information in 1,000-3,000 tokens vs. 10,000-50,000 tokens for manual route scanning.
• Configure source priority, schema depth, and version scoping in repository settings.

For leaders

• API inventories eliminate redundant endpoint discovery across your entire engineering org — every integration question benefits from one shared catalog.
• Security value: the inventory reveals endpoints without authentication requirements, missing access controls, and response fields that might leak sensitive data.
• Onboarding: new engineers get accurate API context immediately without reading route files or asking teammates.
• Maintenance cost is near zero — regeneration is incremental and triggered only by structural changes to routes.