ReferenceAPI ReferenceReport

Create report

POST/reports●Configure a structured data export for auditing, reconciliation, or compliance.

The report starts in created status and transitions through pending → completed → settled as it is processed and finalized. Reports can be rejected at any stage before completion.

Broadcasts the report-created signal. Use effects to subscribe.

POST
/reports

Usage Examples

curl -X POST "http://localhost:3000/v2/reports" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "1f95c06af953019eac2885bb205fd815efe1995409a3fab1a9c17ea9af932eca",    "data": {      "handle": "payments-2025-01-01",      "schema": "trans_details_rep",      "custom": {        "start_timestamp": "2025-01-01T00:00:00.000Z",        "end_timestamp": "2025-01-02T00:00:00.000Z"      }    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "862f76b92b821a86169318ef9770260dae9a7d979809ae66db48d19f74f3d064",          "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",          "result": "/Xnf8iu5lLRaJ/lr3xc7LnjI5fv0X7p+L9qqQqCXlRinIG6pM1QIjqDkk05I1E9h6827oINKwY/viGRuQ5u1CQ==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$rep.-01xK7xYzA8jY0CD9",
  "hash": "1f95c06af953019eac2885bb205fd815efe1995409a3fab1a9c17ea9af932eca",
  "data": {
    "handle": "payments-2025-01-01",
    "schema": "trans_details_rep",
    "custom": {
      "start_timestamp": "2025-01-01T00:00:00.000Z",
      "end_timestamp": "2025-01-02T00:00:00.000Z"
    }
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk="
    ],
    "proofs": [
      {
        "signer": "tesla-bank-admin",
        "method": "ed25519-v2",
        "digest": "862f76b92b821a86169318ef9770260dae9a7d979809ae66db48d19f74f3d064",
        "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
        "result": "/Xnf8iu5lLRaJ/lr3xc7LnjI5fv0X7p+L9qqQqCXlRinIG6pM1QIjqDkk05I1E9h6827oINKwY/viGRuQ5u1CQ==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "eee006f4b0cf9fd8db46cc41cb45b73aa9ce2aeb78bfd57188e55a40024b8a0a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "LgzSu4n2SiuphFlQNQxVGuZVGChYUXCo1KUDo3flnD+m3P2vBT/bRyxLff8S8puy5POc8sfvggcvs/9eriHjBQ==",
        "custom": {
          "luid": "$rep.-01xK7xYzA8jY0CD9",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Request Body

application/json

Report body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Report

Generate reports from ledger data for auditing, compliance, and reconciliation.

List reports GET

Use this endpoint to track report processing status, find completed reports ready for export, or monitor pending report generation. Supported filters: - `data.schema` — report schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)