> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # List Reserve Updates > Returns an event's reserve-update feed: user expected-total updates and the automatic rows for reserve-eroding payments of currently-linked live invoices, discriminated by `kind`. A reserve history reset establishes a per-category horizon — rows at or before it never render, and the reset itself renders as one marker row. Rows are ordered by journal execution order, newest first. An event with no reserve history — unknown ids included — reads as an empty feed. `categoryId` narrows the feed to one reserved category. **Required permission:** `company.payment:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/financials/events/{eventId}/reserve-updates openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/financials/events/{eventId}/reserve-updates: get: tags: - Financials summary: List Reserve Updates description: | Returns an event's reserve-update feed: user expected-total updates and the automatic rows for reserve-eroding payments of currently-linked live invoices, discriminated by `kind`. A reserve history reset establishes a per-category horizon — rows at or before it never render, and the reset itself renders as one marker row. Rows are ordered by journal execution order, newest first. An event with no reserve history — unknown ids included — reads as an empty feed. `categoryId` narrows the feed to one reserved category. **Required permission:** `company.payment:read` operationId: listFinancialsReserveUpdates parameters: - $ref: '#/components/parameters/companyId' - name: eventId in: path required: true schema: type: string format: uuid description: Event identifier - name: categoryId in: query schema: type: string format: uuid description: Only feed rows for this reserved category responses: '200': description: The event's reserve-update feed, newest first content: application/json: schema: type: object required: - rows properties: rows: type: array items: $ref: '#/components/schemas/FinancialsV2ReserveUpdate' examples: success: summary: A set, an eroding payment, and a reset marker value: rows: - kind: erodingPayment journalId: 550e8400-e29b-41d4-a716-446655440903 categoryId: 550e8400-e29b-41d4-a716-446655440100 invoiceId: 550e8400-e29b-41d4-a716-446655440700 paymentId: 550e8400-e29b-41d4-a716-446655440800 amountCents: 4000 paymentDate: '2026-06-10' createdAt: '2026-06-10T09:00:00.000Z' - kind: user journalId: 550e8400-e29b-41d4-a716-446655440902 categoryId: 550e8400-e29b-41d4-a716-446655440100 reserveDate: '2026-06-01' previousTotalCents: 0 expectedTotalCents: 10000 deltaCents: 10000 memo: Initial reserve createdBy: null createdAt: '2026-06-01T10:30:00.000Z' - kind: reset journalId: 550e8400-e29b-41d4-a716-446655440901 categoryId: 550e8400-e29b-41d4-a716-446655440100 reversedUserReserveCents: 2500 createdBy: 550e8400-e29b-41d4-a716-446655440999 createdAt: '2026-05-01T08:00:00.000Z' emptyFeed: summary: An event with no reserve history value: rows: [] '400': description: Bad Request — an unknown query field or a malformed id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: malformedCategoryId: summary: Malformed categoryId value: error: code: VALIDATION_ERROR message: 'categoryId: Invalid UUID' userMessages: - 'categoryId: Invalid UUID' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- Not Found — the company does not have this financials surface enabled (the endpoint behaves as if it does not exist) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Not found value: error: code: NotFoundError message: Not found userMessages: - Not found '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: FinancialsV2ReserveUpdate: description: >- A reserve-update feed row, discriminated by `kind`: `user` (a set of the expected total), `erodingPayment` (an automatic row for a reserve-eroding payment), or `reset` (the history-reset marker). oneOf: - $ref: '#/components/schemas/FinancialsV2UserReserveUpdate' - $ref: '#/components/schemas/FinancialsV2ErodingPaymentReserveUpdate' - $ref: '#/components/schemas/FinancialsV2ReserveHistoryReset' ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing FinancialsV2UserReserveUpdate: type: object description: >- A user reserve update on the feed (`kind: user`): an absolute "set expected total" rendered previous → new straight from the journal record. required: - kind - journalId - categoryId - reserveDate - previousTotalCents - expectedTotalCents - deltaCents - memo - createdBy - displayAuthor - createdAt properties: kind: type: string enum: - user description: Row discriminator journalId: type: string format: uuid description: The journal record that set the expected total categoryId: type: string format: uuid description: The reserved category the update applies to reserveDate: type: string format: date description: The update's reserve date (ISO `YYYY-MM-DD`) previousTotalCents: type: integer description: The scope's expected total before the update, in integer cents expectedTotalCents: type: integer description: The expected total the update set, in integer cents deltaCents: type: integer description: '`expectedTotalCents - previousTotalCents`, in integer cents' memo: type: string nullable: true description: Free-text memo, or `null` createdBy: type: string format: uuid description: >- The recording principal's user id — a human for in-app writes, the frozen "External API" service user for writes through this API. Never caller-supplied displayAuthor: type: string nullable: true description: >- The write's optional `author` display label, or `null` (attributed to `createdBy`'s user). Clients render `displayAuthor ?? user(createdBy)` — the author only, with no transport-provenance suffix createdAt: type: string format: date-time description: When the update was recorded FinancialsV2ErodingPaymentReserveUpdate: type: object description: >- An automatic feed row for an eroding payment (`kind: erodingPayment`): recording a payment with `erodeReserves` reduces the category's remaining reserves by `amountCents` without a user reserve update (`amountCents` is signed — a negative payment restores reserve). Only live payments of currently-linked invoices appear. required: - kind - journalId - categoryId - invoiceId - paymentId - amountCents - paymentDate - createdAt properties: kind: type: string enum: - erodingPayment description: Row discriminator journalId: type: string format: uuid description: The journal record that recorded the payment categoryId: type: string format: uuid description: The reserved category the payment erodes invoiceId: type: string format: uuid description: The invoice the payment was recorded on paymentId: type: string format: uuid description: The payment's id amountCents: type: integer description: The payment amount in integer cents paymentDate: type: string format: date description: The payment date (ISO `YYYY-MM-DD`) createdAt: type: string format: date-time description: When the payment was recorded FinancialsV2ReserveHistoryReset: type: object description: >- The reset marker row (`kind: reset`): a reserve history reset establishes the scope's feed horizon — rows at or before it never render, and the marker itself renders so clients can show "history was reset here". required: - kind - journalId - categoryId - reversedUserReserveCents - createdBy - displayAuthor - createdAt properties: kind: type: string enum: - reset description: Row discriminator journalId: type: string format: uuid description: The journal record of the reset categoryId: type: string format: uuid description: The reserved category whose history was reset reversedUserReserveCents: type: integer description: The user-reserve amount the reset reversed, in integer cents createdBy: type: string format: uuid description: >- The resetting principal's user id — a human for in-app writes, the frozen "External API" service user for writes through this API. Never caller-supplied displayAuthor: type: string nullable: true description: >- The write's optional `author` display label, or `null` (attributed to `createdBy`'s user) createdAt: type: string format: date-time description: When the reset was recorded responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ````