---
title: "Agent-Friendly Docs"
description: "Learn how agents reach and read API documentation, then apply explicit endpoint signatures, parameter tables, realistic examples, error cases, and schemas that reduce ambiguity for any API consumer."
canonical_url: "https://vercel.com/academy/agent-friendly-apis/agent-friendly-docs"
md_url: "https://vercel.com/academy/agent-friendly-apis/agent-friendly-docs.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-08-26T21:03:36.462Z"
content_type: "lesson"
course: "agent-friendly-apis"
course_title: "Agent-Friendly APIs"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Agent-Friendly Docs

# What Makes Docs Agent-Friendly

Human readers scan headings, find an endpoint, and copy a curl command. When an example contains a small mistake or omits an error case, experience can help them fill the gap.

Agents rely more heavily on what the documentation states.

If the docs name a parameter `course_slug` while the API expects `courseSlug`, an agent may send the wrong name and receive a 400. An undocumented error leaves it without a recovery path. Placeholder values such as `"string"` can also end up in a request unchanged.

The documentation needs to remove that ambiguity. It also has to survive two earlier gates: the agent must be able to reach the page, and the answer must appear in the fetched response.

Recent Vercel and Ora research followed 1,033 agent runs across 25 sites. Of the runs with an answer-provenance result, 82.5% grounded the final answer in a page the agent fetched. Docs pages were the most common source. A separate controlled experiment found that a fetch-only client could not retrieve an answer hidden behind JavaScript, and neither tested client could retrieve an answer from a page that returned 403.

That gives us a useful sequence for this course:

1. **Reachable:** the public docs return a successful response without an access challenge
2. **Readable:** the response body contains the documentation without requiring JavaScript
3. **Actionable:** the docs provide exact requests, response shapes, constraints, and recovery paths

This lesson concentrates on the third step. Lesson 2.3 verifies the first two against the deployed API.

## Outcome

Understand the reachability, readability, and actionability sequence, then apply seven documentation patterns that reduce ambiguity for agents.

## Fast Track

1. Learn the three gates an agent passes before it can use documentation
2. See concrete before/after examples for each pattern
3. Understand why you'll automate doc generation instead of maintaining docs manually

\*\*Note: Evidence and recommendations\*\*

The reachability findings above come from observed runs and controlled fetch probes. The seven formatting patterns below are design recommendations. The study did not compare Markdown tables against bullet lists or test each pattern independently.

## Endpoint signatures in code blocks

Use code blocks for endpoint signatures so the method and path are explicit:

```
GET /api/feedback
```

A prose-only version leaves more room for interpretation:

> Send a GET request to the feedback endpoint to retrieve all entries.

The code block provides an exact method and path without asking the reader to infer either one from prose.

Every endpoint in your docs should start with a code block containing the HTTP method and path. No extra words, no surrounding explanation inside the block. The code block is the source of truth.

## Parameters as tables

Markdown tables give parameter definitions a consistent structure. They keep names, types, requirements, and descriptions aligned for readers and tools.

```markdown
| Parameter   | Type   | Required | Description           |
|-------------|--------|----------|-----------------------|
| courseSlug  | string | no       | Filter by course slug |
```

Compare that to:

> - `courseSlug` (optional) - a string that filters by course

The table exposes stable column names and one parameter per row.

The column headers establish the meaning of each value, and each parameter gets one row. Every query parameter and request body field uses the same shape.

## Curl examples with real values

Every request example should use working values from the seed file. Avoid placeholders such as `"string"`, `"example"`, and `"YOUR_VALUE_HERE"`.

```bash
curl -X POST "http://localhost:3000/api/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "courseSlug": "bread-baking",
    "lessonSlug": "scoring-dough",
    "rating": 5,
    "comment": "The lame technique demo was incredibly helpful.",
    "author": "Alex Turner"
  }'
```

An agent may copy example values into a request. Seed data demonstrates the required format, casing, and data types with a request that can run unchanged.

In the Vercel and Ora trace study, 73 of the 119 answers containing code included at least one line copied verbatim from a fetched page. That result does not prove one ideal documentation format, but it raises the cost of publishing examples that are incomplete or wrong.

\*\*Warning: Placeholder values are landmines\*\*

An agent can treat example values as templates. If your curl example uses `"example-slug"`, an agent might send that exact string to your API. Use values from your actual seed data so the examples work when copied verbatim.

## Complete response bodies

Show the full JSON response for every endpoint. No `...` or "and so on." A truncated example leaves the response shape incomplete.

```json
{
  "id": "fb-001",
  "courseSlug": "knife-skills",
  "lessonSlug": "the-claw-grip",
  "rating": 5,
  "comment": "Finally understand why my onion cuts were uneven. The claw grip changed everything.",
  "author": "Priya Sharma",
  "createdAt": "2026-03-01T10:30:00Z"
}
```

Complete response examples expose the full data shape.

## Exhaustive error documentation

Every error response gets its own block with the status code, the condition that triggers it, and the exact response body.

```markdown
**Error response (400), missing fields:**

\`\`\`json
{
  "error": "Missing required fields: courseSlug, lessonSlug, rating, comment, author"
}
\`\`\`

**Error response (400), invalid rating:**

\`\`\`json
{
  "error": "Rating must be an integer between 1 and 5"
}
\`\`\`
```

The label `Error response (STATUS), DESCRIPTION:` identifies the status code and trigger condition. Document each response shape so a client can handle failures programmatically.

## A schema section

Parameter tables tell agents what an endpoint accepts. A schema section tells them the shape of every data type in the system.

```markdown
## Schema

### Feedback

| Field       | Type   | Description                              |
|-------------|--------|------------------------------------------|
| id          | string | Unique identifier (e.g. "fb-001")        |
| courseSlug  | string | Slug of the course                       |
| lessonSlug  | string | Slug of the lesson                       |
| rating      | number | Integer from 1 to 5                      |
| comment     | string | Feedback text                            |
| author      | string | Name of the person                       |
| createdAt   | string | ISO 8601 timestamp                       |
```

The schema section defines each field across the API, while endpoint tables identify which fields a request accepts. Together, they provide the information needed to construct valid requests.

Include format hints ("ISO 8601 timestamp"), value constraints ("Integer from 1 to 5"), and example values where helpful. The agent doesn't read your TypeScript types. It reads the docs.

## Workflow examples

The preceding patterns explain individual endpoints. Many tasks require a sequence of calls.

To find the worst-performing lessons in a course, an agent must check the summary, filter low ratings, and fetch the relevant details. A workflow documents that order directly.

Workflow examples show agents how endpoints chain together to accomplish a task:

```markdown
## Workflows

### Investigate low-rated feedback for a course

1. `GET /api/feedback/summary?courseSlug=knife-skills`: check the average rating and total entries
2. `GET /api/feedback?courseSlug=knife-skills&minRating=1`: pull all entries (minRating sets the floor, so 1 returns everything)
3. `GET /api/feedback/fb-003`: get the full details on a specific entry

### Submit and verify new feedback

1. `POST /api/feedback`: submit the feedback entry with all required fields
2. `GET /api/feedback/:id`: fetch the newly created entry using the `id` from the POST response
3. `GET /api/feedback/summary?courseSlug=bread-baking`: check updated stats for the course
```

Each step names the endpoint, the key parameters, and why you're making that call. The numbered sequence removes all ambiguity about what comes first.

Endpoint docs explain how to make one call. Workflows explain how several calls accomplish a task.

\*\*Note: Workflows are task-oriented\*\*

Start with tasks someone would perform with the API. A workflow connects the required endpoints in the order needed to finish one of those tasks.

## Documentation for both audiences

Structured examples and explicit error cases also help human developers. The same documentation can serve both audiences.

\*\*Note: Better for humans too\*\*

Consistent formatting, realistic examples, and complete error documentation reduce guesswork for any API consumer.

## You won't write these by hand

Applying seven patterns to every endpoint creates a substantial maintenance burden. When the API changes, manually written docs can drift.

In Section 3, you'll turn these patterns into a skill that generates documentation from the route handlers.

First, you'll implement a reference version of the documentation.

## Try It

No code changes in this lesson. Review the seven patterns above. You'll apply them when building the docs endpoint and again when the skill generates docs automatically.

## Commit

No code changes to commit.

## Done-When

- [ ] You can name the seven patterns that make docs agent-friendly: endpoint signatures, parameter tables, curl examples, complete responses, error documentation, schema section, workflow examples
- [ ] You can explain why documentation must be reachable and readable before its formatting can help
- [ ] You understand why real values matter more than placeholders in examples
- [ ] You know why exhaustive error documentation is critical for agents
- [ ] You understand that these docs will be generated by a skill, not written by hand

## Solution

No code solution for this lesson. The patterns here become the template for the docs you'll implement in 2.2 and the skill you'll build in Section 3.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)