---
name: write-api
description: Start writing API reference documentation for an endpoint
argument-hint: "[endpoint]"
arguments:
  - name: endpoint
    description: The API endpoint to document (e.g., POST /accounts)
    required: true
---

# Write API Reference Command

You're starting API reference documentation. Follow these steps:

## 1. Understand the Endpoint

**Endpoint to document:** $ARGUMENTS.endpoint

Gather information about:
- HTTP method and path
- Path parameters
- Query parameters
- Request body schema
- Response schema
- Error conditions

## 2. Required Sections

Every endpoint must include:

### HTTP Method and Path
```markdown
`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`
```

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|

### Query Parameters (if applicable)
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|

### Request Body
```json
{
  "field": "value"
}
```

### Request Body Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|

### Response
```json
{
  "field": "value"
}
```

### Response Fields
| Field | Type | Description |
|-------|------|-------------|

### Errors
| Status Code | Error Code | Description |
|-------------|------------|-------------|

## 3. Field Description Patterns

**UUID:** "The unique identifier of the [Entity]"

**String with constraints:** "[Purpose] (max N chars, format)"

**Enum:** "[Purpose]: `value1`, `value2`, `value3`"

**Boolean:** "If `true`, [behavior]. Default: `value`"

**Timestamp:** "Timestamp of [event] (UTC)"

**Deprecated:** "**[Deprecated]** Use `newField` instead"

**Read-only:** "**Read-only.** Generated by the system"

## 4. Example Quality

### Request examples must:
- Use realistic data (not "foo", "bar")
- Include all required fields
- Be valid JSON

### Response examples must:
- Show complete structure
- Include all fields
- Use realistic UUIDs and timestamps

## 5. Dispatch Agent

For complex API documentation, dispatch the api-writer agent:

```
Task tool:
  subagent_type: "ring-tw-team:api-writer"
  model: "opus"
  prompt: "Document the [endpoint] endpoint. Include:
          - All path/query parameters
          - Complete request body schema
          - Complete response schema
          - All error codes
          - Realistic examples"
```

## 6. Review Before Publishing

After writing, use the docs-reviewer agent:

```
Task tool:
  subagent_type: "ring-tw-team:docs-reviewer"
  model: "opus"
  prompt: "Review this API documentation for completeness and accuracy:
          [paste documentation]"
```

## Data Types Reference

| Type | Description | Example |
|------|-------------|---------|
| `uuid` | UUID v4 | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
| `string` | Text | `"Customer Account"` |
| `integer` | Whole number | `42` |
| `boolean` | True/false | `true` |
| `timestamptz` | ISO 8601 (UTC) | `2024-01-15T10:30:00Z` |
| `jsonb` | JSON object | `{"key": "value"}` |
| `array` | List | `["item1", "item2"]` |
| `enum` | Predefined values | `currency`, `crypto` |

## HTTP Status Codes

**Success:** 200 (GET/PUT), 201 (POST), 204 (DELETE)

**Errors:** 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Invalid), 429 (Rate Limited), 500 (Server Error)

Now proceed with documenting: **$ARGUMENTS.endpoint**