# API Documentation

> Creates API documentation templates with endpoint descriptions, request/response examples, and authentication guides. Use when documenting REST APIs for developers.

- Skill: `reaperinvest/api-documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add reaperinvest/api-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reaperinvest/api-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: reaperinvest (https://skillmd.com/u/reaperinvest)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/reaperinvest/api-documentation

---


# API Documentation

## When to Use This Skill

Use this skill when you need to:
- Create API documentation for a REST API with endpoint references
- Write authentication guides, request/response examples, and error handling docs
- Build a getting started guide for API consumers
- Structure a complete API reference for developer onboarding

**DO NOT** use this skill for internal code documentation, SDK documentation, or webhook setup guides. This is for external-facing REST API documentation.

---

## Core Principle

API DOCUMENTATION IS WRITTEN FOR DEVELOPERS WHO WANT TO INTEGRATE, NOT READ — EVERY PAGE MUST ANSWER "HOW DO I DO THIS?" WITH A COPY-PASTE EXAMPLE.

---

## Phase 1: Brief

### Required Inputs

| Input | What to Ask | Default |
|-------|------------|---------|
| **API purpose** | "What does this API do in one sentence?" | No default — must be provided |
| **Base URL** | "What is the base URL for API requests?" | No default — must be provided |
| **Authentication method** | "How do users authenticate? API key, OAuth, Bearer token?" | API key in header |
| **Endpoints to document** | "List all endpoints with their HTTP methods." | No default — must be provided |
| **Response format** | "JSON, XML, or both?" | JSON |
| **Rate limits** | "Are there rate limits? If so, what are they?" | 100 requests per minute |

**GATE: Confirm the brief before structuring the documentation.**

---

## Phase 2: Structure

### Documentation Architecture

1. **Overview** — What the API does, who it is for, base URL
2. **Authentication** — How to get and use API keys
3. **Quick Start** — First API call in under 5 minutes
4. **Endpoints Reference** — Full endpoint documentation
5. **Error Handling** — Error codes, messages, and resolution
6. **Rate Limits** — Limits, headers, and handling 429 responses
7. **Changelog** — Version history and breaking changes

### Endpoint Documentation Template

For each endpoint, document:
- HTTP method and path
- Description (one sentence)
- Authentication required (yes/no)
- Request parameters (path, query, body)
- Request example (cURL)
- Response example (JSON)
- Error responses
- Rate limit notes

**GATE: Confirm structure and endpoint list before writing.**

---

## Phase 3: Write

### Authentication Section

```
## Authentication

All API requests require an API key passed in the header:

\`\`\`
Authorization: Bearer YOUR_API_KEY
\`\`\`

**Getting your API key:**
1. Log in to your dashboard
2. Navigate to Settings → API
3. Click "Generate API Key"
4. Copy and store securely — it will not be shown again

**Security:** Never expose your API key in client-side code, public repositories, or URLs.
```

### Quick Start Section

Write a complete first-request walkthrough:
1. Get your API key (link to auth section)
2. Make your first request (cURL example)
3. Understand the response
4. Next steps (link to full reference)

### Endpoint Reference Format

```
## [METHOD] /endpoint/path

[One-sentence description of what this endpoint does.]

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | The resource ID |
| limit | integer | No | Max results (default: 20, max: 100) |

### Request Example

\`\`\`bash
curl -X GET "https://api.example.com/v1/resource" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
\`\`\`

### Response Example

\`\`\`json
{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}
\`\`\`

### Error Responses

| Code | Message | Resolution |
|------|---------|------------|
| 401 | Unauthorized | Check your API key |
| 404 | Not found | Verify the resource ID exists |
| 429 | Rate limited | Wait and retry after the Retry-After header value |
```

### Writing Rules

- Every endpoint has a cURL example that can be copied and run immediately
- Response examples use realistic (but fake) data
- Error responses include resolution steps, not just codes
- Parameters table specifies type, required/optional, and default values
- Use consistent formatting across all endpoints

---

## Phase 4: Polish

### 1. Error Reference Table

```
## Error Codes

| HTTP Code | Error Type | Description | Resolution |
|-----------|-----------|-------------|------------|
| 400 | Bad Request | Invalid parameters | Check request body against schema |
| 401 | Unauthorized | Missing or invalid API key | Verify your API key |
| 403 | Forbidden | Insufficient permissions | Check your plan's API access level |
| 404 | Not Found | Resource does not exist | Verify the resource ID |
| 429 | Too Many Requests | Rate limit exceeded | Retry after Retry-After header value |
| 500 | Internal Server Error | Server-side issue | Retry; contact support if persistent |
```

### 2. SDK and Library Suggestions

List official or community SDKs if available. If none exist, provide example code in 2-3 popular languages (Python, JavaScript, cURL).

### 3. Quality Checklist

```
## API Documentation Checklist

- [ ] Base URL is clearly stated at the top
- [ ] Authentication section includes step-by-step key setup
- [ ] Quick start gets a developer to their first response in under 5 minutes
- [ ] Every endpoint has method, path, description, parameters, and examples
- [ ] cURL examples are copy-paste ready
- [ ] Response examples use realistic fake data
- [ ] Error codes include resolution steps
- [ ] Rate limit policy is documented with handling guidance
- [ ] Changelog tracks breaking changes with dates
- [ ] No placeholder text or TODO items remain
```

---

## Example

**API:** Invoice management API for a billing SaaS

**Quick start excerpt:**
```
## Quick Start

Make your first API call in 3 steps:

### 1. Get your API key
Go to Settings → API in your dashboard and generate a key.

### 2. List your invoices
curl -X GET "https://api.invoicebot.com/v1/invoices" \
  -H "Authorization: Bearer sk_test_abc123"

### 3. Check the response
{
  "data": [
    {
      "id": "inv_001",
      "client": "Acme Corp",
      "amount": 2500.00,
      "status": "paid"
    }
  ]
}

You are ready. Explore the full endpoint reference below.
```

---

## Anti-Patterns

- **No examples** — documentation without copy-paste examples is unusable. Every endpoint needs a request and response sample.
- **Outdated examples** — examples that return errors destroy developer trust. Test every example before publishing.
- **Missing error documentation** — developers spend more time handling errors than happy paths. Document every error code.
- **Jargon-heavy descriptions** — "Retrieves a paginated collection of resource entities" should be "Lists all invoices."
- **No quick start** — forcing developers to read the entire reference before making their first call is a conversion killer.

---

## Recovery

- **API is still changing:** Mark the docs as "beta" and version the API. Document known limitations upfront.
- **Too many endpoints to document at once:** Start with the 5 most-used endpoints. Add the rest incrementally.
- **No SDK available:** Provide examples in cURL, Python (requests), and JavaScript (fetch) for the top 3 endpoints.
- **Authentication is complex (OAuth):** Create a dedicated authentication guide with a flow diagram and step-by-step walkthrough.