Skip to content

Agent Integration

Jump to bottom
Logan McDuffie edited this page Dec 23, 2025 · 1 revision

The api-docs CLI is designed for AI agent integration, providing structured output for programmatic API documentation discovery.

Why Agent Integration?

AI agents often need to understand external APIs to:

  • Generate correct API calls
  • Understand available endpoints and parameters
  • Build integrations dynamically

This CLI provides fast, cached access to API documentation in a parseable format.

Claude Code Subagent

The CLI works as a Claude Code subagent. Add this to your CLAUDE.md:

### API Docs Agent
Use the Task tool with `subagent_type="api-docs"` to look up API documentation. This agent can:
- Fetch and cache OpenAPI/Swagger specifications
- List endpoints from any API
- Get detailed info for specific endpoints
- Search APIs.guru directory by provider name

Example: `Task(subagent_type="api-docs", prompt="List endpoints for the Stripe API")`

Example Prompts

List Endpoints

Task(subagent_type="api-docs", prompt="List all endpoints for the Stripe API")

Find Specific Endpoint

Task(subagent_type="api-docs", prompt="Get details for the POST /v1/customers endpoint in Stripe")

Explore Unknown API

Task(subagent_type="api-docs", prompt="What endpoints does the n8n API have for workflow management?")

Direct URL Lookup

Task(subagent_type="api-docs", prompt="List endpoints from https://api.example.com/docs")

Programmatic Usage

Endpoint Discovery

# Get all endpoints for an API
api-docs endpoints stripe

# Output includes:
# - HTTP method (color-coded)
# - Endpoint path
# - Brief description
# - Grouped by category/tag

Endpoint Details

# Get full details for a specific endpoint
api-docs endpoint https://api.stripe.com/openapi /v1/customers --method POST

# Output includes:
# - Parameters with types and requirements
# - Request body schema
# - Response codes

Caching for Performance

The CLI caches API specifications locally:

  • Specs: 24-hour TTL in ~/.cache/api-docs-cli/specs/
  • Provider lookups: 7-day TTL

This ensures fast repeated lookups without hitting external APIs.

Cache Management

# View cached specs
api-docs list

# Clear all caches
api-docs clear

# Clear specific cache
api-docs clear https://api.stripe.com/openapi

Exit Codes

Code Meaning
0 Success
1 General error (API not found, extraction failed)

Best Practices

  1. Use provider names when possible - they're cached longer and resolve automatically
  2. Cache specs first with api-docs fetch for frequent lookups
  3. Use --grouped (default) for organized endpoint lists
  4. Use --verbose when you need full descriptions

Clone this wiki locally