> ## 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. # Integrating with Lerian CCS > The Lerian CCS API surface, its authentication and tenancy model, idempotency, error contract, and the events it publishes. Lerian CCS exposes one REST API under `/v1`. Every business route needs a bearer token. ## API surface *** | Area | Operation | Purpose | | -------------- | --------------------------------------------------------------- | --------------------------------------- | | Configuration | `GET /v1/configurations` | Read the current configuration. | | Configuration | `POST /v1/configurations` | Create a configuration. | | Configuration | `GET /v1/configurations/{id}` | Read one configuration. | | Configuration | `PATCH /v1/configurations/{id}` | Update one configuration. | | Configuration | `POST /v1/configs/{configId}/conglomerate-members` | Add a member. | | Configuration | `GET /v1/configs/{configId}/conglomerate-members` | List members. | | Configuration | `DELETE /v1/configs/{configId}/conglomerate-members/{memberId}` | Remove a member. | | Batch | `POST /v1/batches` | Generate the batch for a movement date. | | Batch | `GET /v1/batches` | List batches. | | Batch | `GET /v1/batches/{id}` | Read one batch. | | Batch | `POST /v1/batches/{id}/approve` | Approve and start the render. | | Batch | `POST /v1/batches/{id}/submit` | Alias of approve. | | Batch | `POST /v1/batches/{id}/reject` | Reject a batch under review. | | Batch | `GET /v1/batches/{id}/items` | List line items. | | Batch | `GET /v1/batches/{id}/items/{itemId}/errors` | List item errors. | | Batch | `POST /v1/batches/resend` | Resend from a terminal batch. | | Batch | `POST /v1/batches/{id}/reprocess-last-event` | Admin. Re-fire the last event. | | Batch | `POST /v1/batches/{id}/drain-parked-response` | Admin. Apply a parked ACCS003. | | Batch | `POST /v1/batches/reconcile-partial-applies` | Admin. Repair a contradicted verdict. | | Batch | `POST /v1/batches/recompute-mirror` | Admin. Recompute the mirror. | | Batch | `POST /v1/batches/backfill-sta-transfer-id` | Admin. Restore a lost identity. | | Detail request | `GET /v1/detail-requests` | List detail requests. | | Detail request | `GET /v1/detail-requests/{id}` | Read one detail request. | | Detail request | `POST /v1/detail-requests/{id}/cancel` | Cancel a detail request. | | Injunction | `POST /v1/injunctions` | Record a block or unblock. | | Injunction | `GET /v1/injunctions` | List injunctions. | | Injunction | `GET /v1/injunctions/{id}` | Read one injunction. | | Injunction | `POST /v1/injunctions/{id}/revoke` | Revoke an injunction. | | Reconciliation | `POST /v1/reconciliations` | Start a run against an ACCS004. | | Reconciliation | `GET /v1/reconciliations` | List runs. | | Reconciliation | `GET /v1/reconciliations/{id}` | Read one run. | | Reconciliation | `GET /v1/reconciliations/{id}/divergences` | List divergences. | | Transfer | `POST /v1/transfers` | Create a transfer. | | Transfer | `GET /v1/transfers` | List transfers. | | Transfer | `GET /v1/transfers/{id}` | Read one transfer with its legs. | | Audit | `GET /v1/audit/entries` | List audit entries. | | Audit | `POST /v1/audit/verify-chain` | Verify the audit chain. | Operator endpoints sit outside `/v1`. | Endpoint | Purpose | | ------------------------- | ---------------------------------------------------- | | `GET /health` | Liveness. It answers 503 while the self-probe fails. | | `GET /readyz` | Readiness of every dependency. | | `GET /readyz/tenant/{id}` | Readiness of one institution. | | `GET /version` | Build version. | | `GET /metrics` | Readiness metrics, Prometheus text. | | `GET /streaming` | The event manifest. | | `/system/{namespace}` | Runtime configuration. | | `/swagger/*` | The API specification, when `SWAGGER_ENABLED=true`. | ## Authentication and tenancy *** Every `/v1` route takes an OAuth2 bearer token from [Lerian Access Manager](/en/platform/access-manager/access-manager). Set `PLUGIN_AUTH_ENABLED=true` and `PLUGIN_AUTH_HOST` to turn the gate on. Production requires both. Each institution keeps its own database schema. The service reads the institution identity from the validated token, never from a request body, a header, or a path parameter. ## Idempotency *** Lerian CCS accepts an `Idempotency-Key` header. The header is mandatory on `POST /v1/batches` and optional on the cancel route. A middleware caches the first response and replays it for a repeat of the same key. Keys belong to one institution, and the default retention is 7 days. ## Errors *** Every error body is an RFC 9457 problem document with the media type `application/problem+json`. Each body carries a product code. The code values are frozen contract, so a client matches on the code, not the message text. | Code | Status | When | | ---------- | ------ | ---------------------------------------------- | | `CCS-0001` | 409 | A configuration already exists. | | `CCS-0004` | 404 | The configuration does not exist. | | `CCS-0010` | 409 | A non-terminal batch holds that movement date. | | `CCS-0012` | 400 | The movement date is outside the window. | | `CCS-0020` | 404 | The batch does not exist. | | `CCS-0024` | 422 | The batch refuses that transition. | | `CCS-0050` | 400 | The transfer names the institution itself. | | `CCS-0061` | 409 | An injunction already covers that document. | | `CCS-0064` | 404 | The detail request does not exist. | | `CCS-0066` | 409 | The cancellable window closed. | | `CCS-0074` | 409 | A reconciliation is already in progress. | | `MYS-0008` | 503 | An upstream or the template is unavailable. | A route whose collaborators failed to wire answers 501. ## Events *** Lerian CCS publishes one business event on its own topic, with a matching dead-letter topic. The topic and the event type follow the [Streaming Hub naming rule](/en/streaming-hub/how-streaming-hub-works), with this service's CloudEvents source as the namespace. | Event | Meaning | | --------------- | ------------------------------------- | | Batch submitted | The ACCS001 batch went to Lerian STA. | It carries the critical delivery posture. The service writes it to the transactional outbox in the same transaction as the state change. Streaming is off by default. While it is off, the service wires a no-operation emitter and publishes nothing. [Lerian Streaming Hub](/en/streaming-hub/what-is-streaming-hub) is the delivery layer. Lerian CCS also publishes notifications on the exchange named by `RABBITMQ_EXCHANGE`. | Routing key | Meaning | | -------------------------------------- | ----------------------------------------- | | `ccs.events.batch` | A batch changed state. | | `ccs.events.batch.generation_failed` | Batch generation failed. | | `ccs.events.detail_request.received` | A detail request arrived. | | `ccs.events.detail_request.cancelled` | A detail request moved to cancelled. | | `ccs.events.reconciliation.divergence` | A run found a divergence. | | `ccs.outbox.dlq` | An outbox message exhausted its attempts. | Documents in those payloads are masked. ## Integration conventions *** * **Headers.** `CORS_ALLOWED_HEADERS` carries no default. While it stays unset, a preflight response echoes the headers the browser asked for. A value you set replaces that behavior with a fixed list, so name every header your browser client sends. * **Pagination.** Each list route caps its own page size. A `limit` of 100 or less stays within every route's cap. * **Rate limits.** The limiter covers `/v1` only. Export and dispatch routes carry tighter tiers. * **File references.** The regulatory XML stays in object storage. Only file references travel over the wire. [How Lerian CCS works](/en/rails/native/ccs/how-ccs-works) covers these flows.