> ## 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. # Reserve Transaction Capacity > Use this endpoint to reserve transaction capacity against spending limits — phase one of the two-phase reservation flow. Provide the ledger `transactionId` the reservation is keyed on; the response returns one reservation ID per counter-backed limit that must later be confirmed or released. When a spending limit would be exceeded, the response is returned with `denied` set to `true` and no capacity is held. Reserves are idempotent by `transactionId` — retrying the same reserve returns the same handle. ## OpenAPI ````yaml en/openapi/v3-current/tracer.yaml post /v1/reservations openapi: 3.1.0 info: title: Tracer API description: >- Complete API reference for Tracer services including transaction validation, rules management, spending limits, and audit events for SOX/GLBA compliance. version: 1.0.1 servers: - url: https://tracer.sandbox.lerian.net security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Health API description: >- Health check endpoints for liveness and readiness probes. These endpoints do not require authentication. - name: Validations API description: >- Transaction validation endpoints. Performance target is under 80ms (p99). Validations are idempotent by `requestId` — a duplicate request returns the cached result with HTTP 200, while a new request returns HTTP 201. No idempotency header is required. - name: Rules API description: >- Validation rule management endpoints. Rules use CEL (Common Expression Language) expressions. - name: Limits API description: >- Spending limit management endpoints. Limits control transaction amounts by scope and period. - name: Reservations API description: >- Two-phase transaction-capacity reservation endpoints. A reserve holds capacity against spending limits; a confirm commits it and a release returns it. Confirm and release are idempotent. - name: Audit Events API description: >- Audit trail endpoints for SOX/GLBA compliance. All validation decisions and configuration changes are recorded. paths: /v1/reservations: post: tags: - Reservations API summary: Reserve Transaction Capacity description: >- Use this endpoint to reserve transaction capacity against spending limits — phase one of the two-phase reservation flow. Provide the ledger `transactionId` the reservation is keyed on; the response returns one reservation ID per counter-backed limit that must later be confirmed or released. When a spending limit would be exceeded, the response is returned with `denied` set to `true` and no capacity is held. Reserves are idempotent by `transactionId` — retrying the same reserve returns the same handle. operationId: createReservation parameters: - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XApiKey' - $ref: '#/components/parameters/XRequestId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReserveRequest' example: transactionId: 019c96a0-1071-7a0d-9916-a831221de252 requestId: 019c96a0-10ce-75fc-a273-dc799079a99c transactionType: CARD amount: '1500.00' currency: USD transactionTimestamp: '2026-01-30T10:00:00Z' account: accountId: 019c96a0-0c0d-7915-84b9-e497bfee9916 type: checking status: active responses: '201': description: >- Indicates that the reserve was processed. Inspect `denied` to confirm capacity was granted rather than rejected by a spending limit. content: application/json: schema: $ref: '#/components/schemas/ReserveResponse' example: transactionId: 019c96a0-1071-7a0d-9916-a831221de252 denied: false reservationIds: - 019c96a0-10d2-7193-8841-0d7347efd09a '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0003: $ref: '#/components/examples/Error0003' Error0011: $ref: '#/components/examples/Error0011' Error0020: $ref: '#/components/examples/Error0020' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorUnauthenticated: $ref: '#/components/examples/ErrorUnauthenticated' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0004: $ref: '#/components/examples/Error0004' components: parameters: ContentType: name: Content-Type in: header description: The type of media of the resource. Must be `application/json`. required: true example: application/json schema: type: string XApiKey: name: X-API-Key in: header description: >- The API Key for authentication. **This header is required for all endpoints except health checks**. required: true schema: type: string XRequestId: name: X-Request-Id in: header description: A unique identifier used to trace and track each request. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string format: uuid schemas: ReserveRequest: type: object description: >- Reserve request for phase one. Mirrors the transaction validation payload and adds the ledger `transactionId` the reservation lifecycle is keyed on. For reserves, `transactionType` and `account` are optional because the ledger may not know the payment rail or an internal account UUID at the reserve anchor; `requestId`, `amount`, `currency` and `transactionTimestamp` remain required. required: - transactionId - requestId - amount - currency - transactionTimestamp properties: transactionId: type: string format: uuid description: >- Ledger transaction correlation ID the reservation is keyed on. Also the idempotency grain for retried reserves. longLived: type: boolean default: false description: >- Selects the reservation lifetime. Use `true` for a pending transaction that must not expire while it remains valid; `false` (the default) for a direct transaction. requestId: type: string format: uuid description: >- Client-generated unique ID for idempotency and audit trail correlation. transactionType: type: string enum: - CARD - WIRE - Pix - CRYPTO description: Type of transaction (payment method). Optional for reserves. subType: type: string maxLength: 50 description: >- Transaction subtype for additional context (e.g., debit, credit, prepaid). amount: type: string description: >- Transaction amount as a decimal string (e.g., "1500.00"). Must be a positive decimal value. currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code (uppercase). Lowercase codes are rejected. transactionTimestamp: type: string format: date-time description: Transaction timestamp in RFC3339 format with timezone. account: $ref: '#/components/schemas/AccountContext' segment: $ref: '#/components/schemas/SegmentContext' portfolio: $ref: '#/components/schemas/PortfolioContext' merchant: $ref: '#/components/schemas/MerchantContext' metadata: type: object additionalProperties: true description: Custom key-value pairs for rule expressions. ReserveResponse: type: object description: >- Handle returned on a successful reserve. When `denied` is true no capacity was held and `reservationIds` is empty; otherwise `reservationIds` holds one ID per counter-backed limit the ledger must later confirm or release. required: - transactionId - denied - reservationIds properties: transactionId: type: string format: uuid description: The ledger transaction correlation ID from the request. denied: type: boolean description: >- Whether the reserve was denied because a spending limit would be exceeded. When true, no capacity is held. reservationIds: type: array items: type: string format: uuid description: >- One reservation ID per counter-backed limit to confirm or release in phase two. Empty when denied. ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. fields: type: object additionalProperties: true description: Additional information about the fields that caused the error. AccountContext: type: object description: Account context for validation. required: - accountId properties: accountId: type: string format: uuid description: Account identifier (required). type: type: string description: Account type. enum: - checking - savings - credit status: type: string description: Account status. enum: - active - suspended - closed metadata: type: object additionalProperties: true description: Additional account attributes for rule evaluation. SegmentContext: type: object description: Segment context (optional). If provided, segmentId is required. properties: segmentId: type: string format: uuid description: Segment identifier (required if segment object provided). name: type: string description: Segment name for rule expressions. metadata: type: object additionalProperties: true description: Additional segment attributes for rule evaluation. PortfolioContext: type: object description: Portfolio context (optional). If provided, portfolioId is required. properties: portfolioId: type: string format: uuid description: Portfolio identifier (required if portfolio object provided). name: type: string description: Portfolio name for rule expressions. metadata: type: object additionalProperties: true description: Additional portfolio attributes for rule evaluation. MerchantContext: type: object description: >- Merchant context (optional, recommended for card transactions). If provided, merchantId is required. properties: merchantId: type: string format: uuid description: Merchant identifier (required if merchant object provided). name: type: string description: Merchant name. category: type: string description: Merchant Category Code (MCC). Must be a 4-digit code per ISO 18245. pattern: ^[0-9]{4}$ country: type: string description: >- Merchant country. Must be ISO 3166-1 alpha-2 code (2 uppercase letters). pattern: ^[A-Z]{2}$ metadata: type: object additionalProperties: true description: Additional merchant attributes for rule evaluation. examples: Error0003: summary: Invalid Request Body value: code: TRC-0003 title: Invalid Request Body message: >- The request body is invalid or malformed. Please verify the JSON format and try again. Error0011: summary: Payload Too Large value: code: TRC-0011 title: Payload Too Large message: >- The request payload exceeds the maximum size limit of 100KB. Please reduce the payload size and try again. Error0020: summary: Invalid Date Format value: code: TRC-0020 title: Invalid Date Format message: >- The date must be in RFC3339 format with timezone (e.g., 2026-01-28T10:30:00Z). Date-only format is not accepted. ErrorUnauthenticated: summary: Unauthorized value: code: Unauthenticated title: Unauthorized message: >- API Key missing or invalid. Provide a valid API Key in the X-API-Key header. Error0004: summary: Internal Server Error value: code: TRC-0004 title: Internal Server Error message: >- An unexpected error occurred. Please try again later or contact support if the issue persists. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API Key authentication. Used by single-tenant deployments (`MULTI_TENANT_ENABLED=false`). Sent on every `/v1/*` request. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer authentication. Used by multi-tenant deployments (`MULTI_TENANT_ENABLED=true`). The JWT is issued by Access Manager and must carry the `tenantId` claim — Tracer resolves the tenant from the token, not from any header or body field. ````