> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference templates

> Adopt the official Lerian templates for API reference pages — endpoints, schemas, errors, and OpenAPI specs — to keep docs precise and predictable.

This page provides the official templates for all API reference documentation in the Lerian ecosystem: endpoint pages, request/response schemas, error handling, and OpenAPI specs.

API reference documentation is technical, dry, and precise. No narrative, no context-setting, no "why" — state facts. Describe inputs, outputs, and behavior. For task-oriented or contextual documentation, see [Guides templates](/en/partners-hub/guides-template).

Apply [voice and tone](/en/partners-hub/voice-tone) and [capitalization](/en/partners-hub/capitalization) rules to all API reference content.

## Endpoint page

***

Each API endpoint gets its own page. The structure is strict — every page follows the same format so developers can scan predictably.

<Steps>
  <Step title="Title">
    Use a short, clear title that fits in one line on the table of contents. Follow the standard verb pattern based on the HTTP method:

    | Method        | Verb                | Example             |
    | :------------ | :------------------ | :------------------ |
    | `POST`        | Create              | Create an account   |
    | `GET`         | List                | List accounts       |
    | `GET` (by ID) | Retrieve            | Retrieve an account |
    | `PATCH`       | Update              | Update an account   |
    | `DELETE`      | Delete / Deactivate | Delete an account   |
  </Step>

  <Step title="Description">
    One to two sentences. What the endpoint does and when to use it. No background, no motivation.

    ```markdown theme={null}
    Creates a new account in the specified ledger. The account is linked to a single asset
    and follows double-entry accounting rules.
    ```
  </Step>

  <Step title="Prerequisites">
    List what is required to use the endpoint:

    * Authentication method
    * Required permissions or roles
    * Entities that must exist first (e.g., "Requires an existing organization and ledger")
  </Step>

  <Step title="Parameters">
    Group by location. Use a separate table for each group:

    **Header parameters**

    | Parameter       | Type   | Required | Description  |
    | :-------------- | :----- | :------- | :----------- |
    | `Authorization` | string | Yes      | Bearer token |

    **Path parameters**

    | Parameter         | Type   | Required | Description              |
    | :---------------- | :----- | :------- | :----------------------- |
    | `organization_id` | string | Yes      | UUID of the organization |
    | `ledger_id`       | string | Yes      | UUID of the ledger       |

    **Query parameters** (when applicable)

    | Parameter | Type    | Required | Description               | Default |
    | :-------- | :------ | :------- | :------------------------ | :------ |
    | `limit`   | integer | No       | Maximum number of results | 10      |
    | `cursor`  | string  | No       | Pagination cursor         | —       |
  </Step>

  <Step title="Request body">
    Document all fields in a single table with these columns:

    | Field       | Type   | Required | Description               | Possible values                  | Default | Constraints         | Example          |
    | :---------- | :----- | :------- | :------------------------ | :------------------------------- | :------ | :------------------ | :--------------- |
    | `name`      | string | Yes      | Name of the account       | —                                | —       | MaxLength: 100      | `"Main Account"` |
    | `type`      | string | Yes      | Account type              | `deposit`, `savings`, `external` | —       | —                   | `"deposit"`      |
    | `assetCode` | string | Yes      | Currency or asset code    | —                                | —       | ISO 4217 or custom  | `"BRL"`          |
    | `alias`     | string | No       | Human-readable identifier | —                                | —       | Must start with `@` | `"@revenue"`     |

    For nested objects, use a subsection (H4) with its own table:

    #### `status` object

    | Field         | Type   | Required | Description           | Possible values                 |
    | :------------ | :----- | :------- | :-------------------- | :------------------------------ |
    | `code`        | string | Yes      | Status code           | `ACTIVE`, `INACTIVE`, `BLOCKED` |
    | `description` | string | No       | Reason for the status | —                               |
  </Step>

  <Step title="Request example">
    A complete, realistic `curl` command. Use placeholders only for IDs (`{organization_id}`), never for field values.

    ```bash theme={null}
    curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer {token}" \
      -d '{
        "name": "Revenue Account",
        "assetCode": "BRL",
        "type": "deposit",
        "status": {
          "code": "ACTIVE"
        },
        "alias": "@revenue"
      }'
    ```
  </Step>

  <Step title="Success response">
    Include the HTTP status code and a complete response body.

    **`201 Created`**

    ```json theme={null}
    {
      "id": "01fbc1e4-5678-9abc-def0-123456789abc",
      "name": "Revenue Account",
      "assetCode": "BRL",
      "type": "deposit",
      "status": {
        "code": "ACTIVE"
      },
      "alias": "@revenue",
      "createdAt": "2026-03-27T12:00:00Z",
      "updatedAt": "2026-03-27T12:00:00Z"
    }
    ```

    For `204 No Content` responses, state explicitly that no body is returned.
  </Step>

  <Step title="Error responses">
    List every possible error the endpoint can return. All errors follow [Lerian's standard error format](/en/partners-hub/error-model).

    | Status | Code                   | Description                                             |
    | :----- | :--------------------- | :------------------------------------------------------ |
    | `400`  | `INVALID_REQUEST`      | Missing or invalid required field                       |
    | `404`  | `LEDGER_NOT_FOUND`     | Ledger does not exist                                   |
    | `409`  | `ALIAS_ALREADY_EXISTS` | An account with this alias already exists in the ledger |
    | `422`  | `ASSET_NOT_FOUND`      | The specified asset code does not exist in this ledger  |

    Include a sample error response body:

    ```json theme={null}
    {
      "code": "ALIAS_ALREADY_EXISTS",
      "message": "An account with alias @revenue already exists in this ledger.",
      "details": {
        "field": "alias",
        "value": "@revenue"
      }
    }
    ```
  </Step>

  <Step title="OpenAPI spec">
    Include the OpenAPI 3.1 spec for this endpoint whenever possible. Use a collapsible section:

    ````json theme={null}
    <Accordion title="OpenAPI spec (YAML)">

      ```yaml
        /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts:
          post:
            summary: Create an account
            operationId: createAccount
            ...
      ```    
    </Accordion>

    ````
  </Step>
</Steps>

## Error model

***

All Lerian APIs follow a standard error format. Document it once and reference it from every endpoint page.

### Standard error response

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong.",
  "details": {}
}
```

| Field     | Type   | Description                                                    |
| :-------- | :----- | :------------------------------------------------------------- |
| `code`    | string | Machine-readable error code (uppercase, snake\_case)           |
| `message` | string | Human-readable description                                     |
| `details` | object | Additional context (field name, value, constraints). Optional. |

### HTTP status code conventions

| Status | Meaning               | When to use                                                |
| :----- | :-------------------- | :--------------------------------------------------------- |
| `400`  | Bad Request           | Malformed request, missing required fields, invalid values |
| `401`  | Unauthorized          | Missing or invalid authentication                          |
| `403`  | Forbidden             | Authenticated but insufficient permissions                 |
| `404`  | Not Found             | Resource does not exist                                    |
| `409`  | Conflict              | Duplicate resource (alias, idempotency key)                |
| `422`  | Unprocessable Entity  | Valid syntax but failed business rules                     |
| `429`  | Too Many Requests     | Rate limit exceeded                                        |
| `500`  | Internal Server Error | Unexpected server failure                                  |

## Writing rules for API reference

***

These rules apply to all API reference documentation. They complement the general [voice and tone](/en/partners-hub/voice-tone) guidelines.

### Do

* Start descriptions with a verb: "Creates", "Returns", "Deletes"
* Use `code formatting` for all field names, values, endpoints, and HTTP methods
* Document every field, even optional ones
* Include realistic example values — never `"string"` or `"example"`
* Show the complete request and response, not fragments
* List every possible error, not just common ones

### Don't

* Don't explain business context or motivation — that belongs in guides
* Don't use `<Tip>`, `<Note>`, or `<Warning>` in endpoint descriptions — save them for prerequisites or gotchas only
* Don't use narrative voice ("you might want to", "consider using")
* Don't describe fields with "This field is used to..." — state what it does directly
* Don't omit error cases because they're "unlikely"

## Component patterns

***

API reference pages use a smaller set of components than guides.

| Component     | When to use                                                   |
| ------------- | ------------------------------------------------------------- |
| `<Accordion>` | Collapsible OpenAPI specs, extended error lists               |
| `<CodeGroup>` | Multiple request/response formats (curl + SDK examples)       |
| `<Note>`      | Prerequisites, version-specific behavior                      |
| `<Warning>`   | Breaking changes, deprecation notices                         |
| `<Danger>`    | Irreversible operations (hard delete, data loss)              |
| Tables        | Parameters, fields, errors — always in tables, never in prose |

<Tip>
  For more information, see [Mintlify's official documentation](https://www.mintlify.com/docs/components/index).
</Tip>