Skip to main content
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. 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:
ParameterTypeDescriptionDefault
metadatastringJSON string to filter by metadata fields—
limitintegerMaximum number of records per page (1–100)10
pageintegerPage number for pagination (minimum 1)1
start_datestringFilter items created on or after this date (YYYY-MM-DD)—
end_datestringFilter items created on or before this date (YYYY-MM-DD)—
sort_orderstringSort 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:
CodeUsage
200 OKRequest processed successfully (synchronous)
201 CreatedResource created successfully
202 AcceptedAccepted for asynchronous processing
204 No ContentSuccess 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. 
{
  "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: 
{
  "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: 
{
  "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
Error responses must comply with Lerian’s standard format according to the Error model guideline.

​
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

ConventionStandard
Query parameterssnake_case
JSON body fieldslowerCamelCase
Custom headersX-Service-Name (PascalCase)
DatesISO 8601 UTC with Z suffix
PATCHRFC 7386 JSON Merge Patch
DELETESoft-delete, 204 No Content
Error codes3-letter prefix + 4 digits
OpenAPI3.1