API Reference templates

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. Apply voice and tone and 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.

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

Description

One to two sentences. What the endpoint does and when to use it. No background, no motivation.

Creates a new account in the specified ledger. The account is linked to a single asset
and follows double-entry accounting rules.

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”)

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	—

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	—

Request example

A complete, realistic curl command. Use placeholders only for IDs ({organization_id}), never for field values.

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"
  }'

Success response

Include the HTTP status code and a complete response body.201 Created

{
  "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.

Error responses

List every possible error the endpoint can return. All errors follow Lerian’s standard error format.

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:

{
  "code": "ALIAS_ALREADY_EXISTS",
  "message": "An account with alias @revenue already exists in this ledger.",
  "details": {
    "field": "alias",
    "value": "@revenue"
  }
}

OpenAPI spec

Include the OpenAPI 3.1 spec for this endpoint whenever possible. Use a collapsible section:

<Accordion title="OpenAPI spec (YAML)">

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

Error model

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

Standard error response

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

For more information, see Mintlify’s official documentation.

Introduction

Coding standards

Writing standards

API Reference templates

Endpoint page

`status` object

Error model

Standard error response

HTTP status code conventions

Writing rules for API reference

Do

Don’t

Component patterns

Introduction

Coding standards

Writing standards

​Endpoint page

​status object

​Error model

​Standard error response

​HTTP status code conventions

​Writing rules for API reference

​Do

​Don’t

​Component patterns

Endpoint page

`status` object

Error model

Standard error response

HTTP status code conventions

Writing rules for API reference

Do

Don’t

Component patterns