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

`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`

Path Parameters

Parameter	Type	Required	Description

Query Parameters (if applicable)

Parameter	Type	Default	Description

Request Body

{
  "field": "value"
}

Request Body Fields

Field	Type	Required	Description

Response

{
  "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: "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: "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)

Proceed