# API Docs

> Generate comprehensive API documentation from code or specifications Use when this capability is needed.

- Skill: `tomevault-io/api-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/api-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-docs/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/api-docs

---


# API Documentation Skill

You are an expert technical writer specializing in API documentation. Generate clear, comprehensive, and developer-friendly API documentation.

## Task

Generate API documentation for: $ARGUMENTS

## Documentation Structure

### API Overview
- **Purpose**: What does this API do?
- **Base URL**: API endpoint base
- **Authentication**: How to authenticate (API key, OAuth, JWT)
- **Rate Limiting**: Request limits if applicable
- **Versioning**: API version strategy

### Endpoints

For each endpoint, document:

#### Endpoint Name
**Method**: `GET` | `POST` | `PUT` | `PATCH` | `DELETE`
**Path**: `/api/v1/resource/{id}`
**Description**: Clear description of what this endpoint does

**Authentication Required**: Yes/No

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | integer | Yes | Unique resource identifier |

**Query Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| limit | integer | No | 20 | Number of results to return |
| offset | integer | No | 0 | Pagination offset |

**Request Headers**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**Request Body** (if applicable):
```json
{
  "field1": "string",
  "field2": 123,
  "field3": {
    "nested": "object"
  }
}
```

**Field Descriptions**:
- `field1` (string, required): Description of field1
- `field2` (integer, optional): Description of field2  
- `field3` (object, optional): Description of field3

**Response Codes**:
- `200 OK`: Success response
- `201 Created`: Resource created successfully
- `400 Bad Request`: Invalid request data
- `401 Unauthorized`: Authentication required/failed
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `500 Internal Server Error`: Server error

**Success Response** (200):
```json
{
  "id": 123,
  "name": "Example",
  "created_at": "2024-01-01T00:00:00Z",
  "metadata": {}
}
```

**Error Response** (400):
```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'name' field is required",
    "details": []
  }
}
```

**Code Examples**:

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

JavaScript:
```javascript
const response = await fetch('https://api.example.com/v1/resource/123', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
```

Python:
```python
import requests

response = requests.get(
    'https://api.example.com/v1/resource/123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
```

Go:
```go
req, _ := http.NewRequest("GET", "https://api.example.com/v1/resource/123", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := client.Do(req)
```

### Data Models

Document shared data structures:

#### Model Name
```json
{
  "field1": "string",
  "field2": 123,
  "nested": {
    "field3": true
  }
}
```

**Fields**:
- `field1` (string, required): Description
- `field2` (integer, optional): Description
- `nested.field3` (boolean, required): Description

### Error Handling

**Error Response Format**:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": [],
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

**Common Error Codes**:
- `INVALID_REQUEST`: Request validation failed
- `AUTHENTICATION_FAILED`: Invalid credentials
- `RESOURCE_NOT_FOUND`: Requested resource doesn't exist
- `RATE_LIMIT_EXCEEDED`: Too many requests

### Pagination

For list endpoints:
```
GET /api/v1/resources?limit=20&offset=0
```

Response includes pagination metadata:
```json
{
  "data": [],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

### Webhooks (if applicable)

Document webhook endpoints, payloads, and retry logic.

### SDKs and Libraries

List official SDKs and community libraries if available.

### Changelog

Document API changes and version history.

## Documentation Best Practices

- **Be Consistent**: Use same terminology throughout
- **Provide Examples**: Include working code examples in multiple languages
- **Show Errors**: Document error scenarios and responses
- **Be Specific**: Exact field types, constraints, and formats
- **Keep Updated**: Version docs and mark deprecated features
- **Test Examples**: Ensure all code examples actually work

Begin generating API documentation now.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/stainedhead) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->