> ## 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 standards

> Design conventions and requirements for plugin APIs in the Lerian ecosystem.

All plugins exposing APIs must adhere to Lerian's API standards to ensure consistency, interoperability, and a predictable developer experience across the ecosystem. APIs must follow RESTful principles and be described using the **OpenAPI 3.1** specification. GraphQL is optional but allowed as a complementary interface.

This page defines the conventions that apply to every Lerian plugin API — from parameter naming to error formatting.

## Header parameters

***

### Authorization

All plugins support optional integration with [Access Manager](/en/platform/access-manager/access-manager). The `Authorization` header must be documented as **optional** in your API schema. It is required only when the environment has the Access Manager plugin enabled.

Use the description field to communicate this conditionality — do not set the `required` flag to `true`.

Recommended description text:

> *The authorization token. This header is required only if your environment has the Access Manager plugin enabled.*

### Custom headers

Service-specific headers follow the pattern `X-{Service}-{Name}` using PascalCase. For example: `X-Account-ID`.

## Query parameters

***

All query parameters must use `snake_case`.

Lerian defines a set of standard query parameters that should be supported across all list endpoints:

| Parameter    | Type    | Description                                              | Default |
| ------------ | ------- | -------------------------------------------------------- | ------- |
| `metadata`   | string  | JSON string to filter by metadata fields                 | —       |
| `limit`      | integer | Maximum number of records per page (1–100)               | 10      |
| `page`       | integer | Page number for pagination (minimum 1)                   | 1       |
| `start_date` | string  | Filter items created on or after this date (YYYY-MM-DD)  | —       |
| `end_date`   | string  | Filter items created on or before this date (YYYY-MM-DD) | —       |
| `sort_order` | string  | Sort direction: `asc` or `desc`                          | —       |

## Body parameters

***

Fields in request and response bodies must use `lowerCamelCase`.

Do not use `snake_case`, `kebab-case`, or `PascalCase` in JSON payloads. This convention applies to all field names at every nesting level.

## Response status codes

***

Lerian APIs use a minimal set of HTTP status codes:

| Code             | Usage                                             |
| ---------------- | ------------------------------------------------- |
| `200 OK`         | Request processed successfully (synchronous)      |
| `201 Created`    | Resource created successfully                     |
| `202 Accepted`   | Accepted for asynchronous processing              |
| `204 No Content` | Success with no response body (e.g., soft-delete) |

## Date and time format

***

All date-time fields must follow **ISO 8601** in **UTC** with the `Z` suffix. Do not return dates without the `Z` suffix or in local timezones.

```json theme={null}
{
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}
```

Date-only fields (such as query parameters) use the `YYYY-MM-DD` format.

## Error format

***

All error responses must follow the standard Lerian error structure:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Error title",
  "message": "Error message."
}
```

When the error relates to specific fields (e.g., validation failures), include a `fields` object with per-field details:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Bad Request",
  "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
  "fields": {
    "legalName": "legalName is a required field.",
    "parentOrganizationId": "parentOrganizationId must be a valid UUID"
  }
}
```

### Error code conventions

Error codes follow the pattern: **3-letter plugin prefix** + **4 digits**.

* Each plugin has its own prefix (e.g., `MDZ` for Midaz, `PIX` for Pix, `TRC` for Tracer)
* Codes in the `0001`–`0999` range are plugin-internal errors
* Codes starting with `1` (e.g., `XXX-1000`) indicate errors from external integrations

<Warning>
  Error responses must comply with Lerian's standard format according to the [Error model](/en/partners-hub/error-model) guideline.
</Warning>

## PATCH behavior

***

All PATCH endpoints follow **RFC 7386 — JSON Merge Patch**.

* **Content-Type**: `application/merge-patch+json`
* **Omitted properties**: remain unchanged
* **Properties set to `null`**: are removed or reset to default
* **Objects**: are merged recursively
* **Arrays**: are replaced entirely (no element-wise merge)

This means a PATCH request only needs to include the fields being changed. Any field not present in the request body stays as-is.

## Soft-delete pattern

***

Delete operations follow the **soft-delete** pattern:

* Return `204 No Content`
* Set the `deletedAt` field to the current ISO 8601 UTC timestamp
* Exclude soft-deleted records from default listings (unless an explicit filter is applied)
* The operation is **idempotent** — calling DELETE on an already-deleted resource returns the same `204`

Soft-deleted resources are preserved for audit and compliance purposes. Hard-delete is not used unless explicitly justified.

## Metadata objects

***

Lerian APIs support a `metadata` object for storing arbitrary key-value pairs on resources. This allows clients to attach custom data without schema changes.

Conventions for metadata:

* Keys must use `lowerCamelCase`
* Values can be JSON primitives or nested objects
* Unknown keys must be **preserved verbatim** — never transform, rename, or drop metadata fields
* Metadata can be filtered via the `metadata` query parameter as a JSON string

## Quick reference

***

| Convention       | Standard                      |
| ---------------- | ----------------------------- |
| Query parameters | `snake_case`                  |
| JSON body fields | `lowerCamelCase`              |
| Custom headers   | `X-Service-Name` (PascalCase) |
| Dates            | ISO 8601 UTC with `Z` suffix  |
| PATCH            | RFC 7386 JSON Merge Patch     |
| DELETE           | Soft-delete, `204 No Content` |
| Error codes      | 3-letter prefix + 4 digits    |
| OpenAPI          | 3.1                           |