gh-lerianstudio-ring-tw-team/commands/write-api.md

name, description, argument-hint, arguments

name	description	argument-hint	arguments
write-api	Start writing API reference documentation for an endpoint	[endpoint]	name description required endpoint The API endpoint to document (e.g., POST /accounts) 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

`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: "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