API Reference template

Use this template to create pages in the API Reference section of the Lerian documentation. It ensures consistency, clarity, and a great developer experience.


Endpoint page


Title

Use short, clear titles that fit in one line on the table of contents (ToC). Follow the standard verb pattern:

MethodVerbExample
POSTCreateCreate an Account
GETListList Accounts
GET (by ID)RetrieveRetrieve an Account
PATCHUpdateUpdate an Account
DELETEDelete / DeactivateDelete an Account

Description

Start with a clear and concise explanation of what the endpoint does and when to use it.


Prerequisites

List what is required to use the endpoint (e.g., authentication, permissions, required entities).


Parameters

Include all parameters, grouped by where they appear:

  • Header parameters
  • Path parameters
  • Query parameters

Body (Payload)

Document all fields that appear in the request body.

FieldTypeRequiredDescriptionPossible ValuesDefaultConstraintsExample
namestringYesName of the accountMaxLength: 100"Main Account"
typestringYesAccount typeasset, liability"asset"
assetIdstringYesAssociated asset IDUUID"01fbc1..."

Success responses

Describe what users receive when the request is successful. Include status codes like 200, 201, or 204.


Error Responses

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


Full error list


Create a separate page to group all possible error codes for each API/plugin. Divide them by HTTP status (e.g., 400, 404, 409, 500) and include a table with:

CodeTitleMessage
0001Duplicate Ledger ErrorA ledger with the name already exists in the division.
0004Code Uppercase RequirementThe code must be in uppercase.
👍

Tip

Check this example: Access Manager Error List


YAML File (Optional)


Whenever possible, add the OpenAPI spec (.yaml) for this endpoint, following the OpenAPI 3.1 standard.