POST
/reports/custom Save a custom report
Idempotent: an Idempotency-Key header (or an idempotency_key body field) used before on this ledger returns the report it created, with meta.replayed: true, for the same name and definition; with another body it is refused on idempotency_key. A definition that names anything not the ledger's is refused, by its path under definition..
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string max length: 255 |
Request bodyrequired
| Field | Type | Description |
|---|---|---|
namerequired | string max length: 120 | Once per ledger, whatever its case |
definitionrequired | object | A report specification v2: version, filter, columns, sort |
idempotency_key | string max length: 255 · nullable |
Responses
200A replay of an idempotency key: the report it created, with meta.replayed: true
{
"success": true,
"meta": {
"replayed": true
},
"data": {
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"name": "Card payments over 100 last month",
"definition": {},
"lock_version": 0,
"created_by": null,
"updated_by": null,
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
} 201Saved
{
"success": true,
"data": {
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"name": "Card payments over 100 last month",
"definition": {},
"lock_version": 0,
"created_by": null,
"updated_by": null,
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
} 401Unauthenticated
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 403Forbidden
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 422A name in use, a definition outside the rules, one naming something not the ledger's, or an idempotency key used for another report
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} Examples
curl -X POST https://ledga.io/api/v1/reports/custom \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"definition": {}
}'