---
title: "Agent API Reference"
type: index
id: "api-reference"
description: "Use the AI Future Ready agent API: JSON indexes, per-item data, raw markdown, ranked search, schema, changes, recommendations, pricing snapshots, and feeds."
last_updated: "2026-07-03"
---

# Agent API Reference

This site exposes structured content through multiple machine-readable access paths. All endpoints are public, require no authentication, and return typed data.

Transport: every content and API response sends `Access-Control-Allow-Origin: *`, an `ETag` (send it back as `If-None-Match` for cheap `304` revalidation), and `Cache-Control: public, max-age=3600, stale-while-revalidate=86400`.

Raw markdown for any canonical page URL: append `.md` (`/models/gpt-5.4.md`), send `Accept: text/markdown`, or follow the page's `<link rel="alternate" type="text/markdown">` tag. All three lead to the `/content/` path for that page.

## Commercial Access

The public API stays open. Paid access is intended for teams that need commercial reuse rights, bulk packaging, richer pricing snapshots, source verification metadata, change history, and support.

| Page | Description |
|------|-------------|
| [`/pricing`](/pricing) | Free access, Pro Data, commercial licensing, audits, and model pricing references |
| [`/pricing/pro-data`](/pricing/pro-data) | Draft Pro Data package, export formats, paid API targets, and included fields |
| [`/pricing/commercial-license`](/pricing/commercial-license) | Draft commercial data license shape |
| [`/pricing/agent-readiness-audit`](/pricing/agent-readiness-audit) | Service package for making external sites agent-readable |
| [`/pricing/pro-data-sample`](/pricing/pro-data-sample) | Public sample of the planned Pro Data JSON shape |
| [`/pricing/sponsor-policy`](/pricing/sponsor-policy) | Disclosure and ranking rules for sponsorships |
| [`/api-reference/data-changelog`](/api-reference/data-changelog) | Data update and change-tracking notes |

Draft paid API targets use `/api/pro/v1/`. They are not implemented yet.

## Discovery

| Endpoint | Format | Description |
|----------|--------|-------------|
| [`/.well-known/ai.json`](/.well-known/ai.json) | JSON | Agent discovery manifest for protocols and capabilities |
| [`/llms.txt`](/llms.txt) | Text | Machine-readable index of all content — the front door for agents |
| [`/llms-full.txt`](/llms-full.txt) | Text | All content concatenated into one file for bulk access |
| [`/openapi.json`](/openapi.json) | OpenAPI 3.1 | Client-generation contract for the public JSON API |
| [`/api/v1/openapi.json`](/api/v1/openapi.json) | OpenAPI 3.1 | Versioned copy of the OpenAPI contract |
| [`/search-index.json`](/search-index.json) | JSON | Structured index with titles, descriptions, tags, and URLs |
| [`/feed.json`](/feed.json) | JSON Feed | Timestamped update feed for change detection |
| [`/feed.xml`](/feed.xml) | RSS | RSS mirror of the change feed |
| [`/sitemap.xml`](/sitemap.xml) | XML | Sitemap with both HTML and raw content URLs |
| [`/robots.txt`](/robots.txt) | Text | Agent access permissions |
| [`/status`](/status) | HTML/JSON view | Human and agent-readable operational status |

## JSON API

Base URL: `/api/v1/`

| Endpoint | Description |
|----------|-------------|
| [`/api/v1/index.json`](/api/v1/index.json) | All content types with descriptions and counts |
| [`/api/v1/openapi.json`](/api/v1/openapi.json) | OpenAPI 3.1 contract for API clients and agent tool generation |
| [`/api/v1/schema.json`](/api/v1/schema.json) | Observed fields, value types, coverage, examples, and generated fields |
| [`/api/v1/search.json?q=cheap+coding+model`](/api/v1/search.json?q=cheap+coding+model) | Ranked keyword search across all content (`q`, optional `type`, `limit`) |
| [`/api/v1/status.json`](/api/v1/status.json) | Build freshness, content freshness, internal-link health, and source metadata coverage |
| [`/api/v1/models.json`](/api/v1/models.json) | All models with pricing, benchmarks, context windows, and metadata |
| [`/api/v1/models-filter.json?capability=vision&availability_status=available`](/api/v1/models-filter.json?capability=vision&availability_status=available) | Queryable model filter for agent routing |
| [`/api/v1/diff.json?a=gpt-5.4&b=claude-opus-4.6`](/api/v1/diff.json?a=gpt-5.4&b=claude-opus-4.6) | Structured model-to-model diff for pricing, benchmarks, metadata, capabilities, and sources |
| [`/api/v1/cost.json?input_tokens=1000000&output_tokens=1000000`](/api/v1/cost.json?input_tokens=1000000&output_tokens=1000000) | Ranked token-cost estimates across model records |
| [`/api/v1/models/claude-opus-4.6.json`](/api/v1/models/claude-opus-4.6.json) | Per-item JSON with metadata, body text, relationships, and hashes |
| [`/api/v1/providers.json`](/api/v1/providers.json) | Provider profiles and ecosystem guidance |
| [`/api/v1/agents.json`](/api/v1/agents.json) | All agent platforms with categories, licensing, and languages |
| [`/api/v1/comparisons.json`](/api/v1/comparisons.json) | Model comparison summaries |
| [`/api/v1/blog.json`](/api/v1/blog.json) | Blog posts with dates, categories, and descriptions |
| [`/api/v1/recommend.json`](/api/v1/recommend.json) | Pre-scored model rankings by task |
| [`/api/v1/recommend/coding.json`](/api/v1/recommend/coding.json) | Task-specific recommendation slice |
| [`/api/v1/model-verification.json`](/api/v1/model-verification.json) | Model-level verification inventory and source-coverage checklist |
| [`/api/v1/pricing-snapshots.json`](/api/v1/pricing-snapshots.json) | Generated current pricing snapshot for model entries |
| [`/api/v1/samples/pro-data.json`](/api/v1/samples/pro-data.json) | Public sample of planned Pro Data fields |
| [`/api/v1/changes.json?since=2026-04-01`](/api/v1/changes.json?since=2026-04-01) | Queryable changed-since endpoint |

All endpoints return JSON with consistent field naming. No authentication required.

Per-item JSON uses this pattern:

```
/api/v1/[type]/[slug].json
```

Recommendation slices use this pattern:

```
/api/v1/recommend/[task].json
```

Supported recommendation tasks include `coding`, `writing`, `math`, `reasoning`, `multilingual`, `speed`, `research`, `cheap`, `local`, `agentic`, `images`, and `education`.

Model filtering supports repeated parameters or comma-separated values:

```
/api/v1/models-filter.json?capability=vision&capability=function_calling&availability_status=available&context_min=1000000&max_input_price=3
```

Supported filters: `capability`, `provider`, `availability_status`, `deprecated`, `model_type`, `tool_schema_format`, `context_min`, `max_input_price`, `max_output_price`, and `free`.

Model diffing accepts a model slug, permanent id, API model id, or title for each side:

```
/api/v1/diff.json?a=gpt-5.4&b=claude-opus-4.6
```

The response includes both model summaries plus structured comparisons for metadata, context window, numeric pricing, benchmarks, capabilities, modality, confidence, and sources.

Model cost calculation accepts either query parameters or a POST JSON body:

```
GET /api/v1/cost.json?input_tokens=1000000&output_tokens=1000000
POST /api/v1/cost.json
```

POST body:

```json
{
  "input_tokens": 1000000,
  "output_tokens": 1000000,
  "include_unpriced": false,
  "limit": 25
}
```

The response ranks priced models by `estimated_cost_usd` and includes per-component price sources, missing price components, availability status, and pricing confidence.

## MCP Access

This project also includes a local MCP server for agents that prefer tool calls over raw document fetches.

- Docs: [`/mcp`](/mcp)
- Server command: `npx tsx scripts/mcp-server.ts`
- Claude Code example: `claude mcp add ai-future-ready npx tsx scripts/mcp-server.ts`

## Raw Content

Every content page is available as raw markdown with YAML frontmatter at a predictable URL:

```
/content/[type]/[slug].md        → individual item
/content/[type]/_index.md        → type index
/content/_index.md               → site index
```

**Examples:**
- [`/content/models/claude-opus-4.6.md`](/content/models/claude-opus-4.6.md) — model page with full metadata
- [`/content/agents/crewai.md`](/content/agents/crewai.md) — agent platform with structured fields
- [`/content/blog/ai-agent-revolution-2026.md`](/content/blog/ai-agent-revolution-2026.md) — blog post with frontmatter

## Metadata Schema

Every content item includes at minimum:

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Human-readable title |
| `type` | string | Content category |
| `id` | string | Permanent canonical identifier |
| `description` | string | One-line summary |
| `last_updated` | date | ISO 8601 date of last change |

Model-specific fields: `provider`, `api_model_id`, `pricing` (human strings plus optional numeric per-1M fields), `benchmarks`, `context_window`, `knowledge_cutoff`, `capabilities`, `availability_status`, `tool_schema_format`, `sources`, `best_for`, `tags`

Agent-specific fields: `category`, `license`, `pricing`, `languages`, `github`, `website`

Generated JSON fields: `markdown_url`, `html_url`, `api_url`, `content_hash`, `sha256`, `relationships`, `content_text`

See the [Agent-Ready Web Standard](/standard) for the full metadata specification.

/api/v1/[type]/[slug].json

/api/v1/recommend/[task].json

/api/v1/models-filter.json?capability=vision&capability=function_calling&availability_status=available&context_min=1000000&max_input_price=3

/api/v1/diff.json?a=gpt-5.4&b=claude-opus-4.6

GET /api/v1/cost.json?input_tokens=1000000&output_tokens=1000000
POST /api/v1/cost.json

{
  "input_tokens": 1000000,
  "output_tokens": 1000000,
  "include_unpriced": false,
  "limit": 25
}

/content/[type]/[slug].md        → individual item
/content/[type]/_index.md        → type index
/content/_index.md               → site index