> ## 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 Company Reserve Updates > Lists every event's reserve change history in one feed, as the app's company-wide Reserve Updates listing and its export show it: each expected-total change a user made, each automatic reserve reduction from a payment, and each reserve history reset marker, with the event it belongs to and the running reserve after each change. Use it to copy reserve history into a data warehouse. For one event's history, use List Reserve Updates (`listFinancialsReserveUpdates`); for current reserve, paid, and incurred figures, use Get Balances (`getFinancialsBalances`). Each event's feed follows the same rules as List Reserve Updates: a reserve history reset establishes a per-event, per-category horizon — rows at or before it never render, and the reset itself renders as one marker row. `categoryId` narrows the feed to one reserved category. `asOfDate` returns the feed as of that date, like the app export's **As of** date: `user` rows with a later `reserveDate` and `erodingPayment` rows with a later `paymentDate` are left out; reset markers have no date and always render. Cursor-paginated: pass the previous page's `nextCursor` back as `cursor` until it is `null`. Rows are ordered by journal execution order, newest first. A change recorded while you page appears at the top of the feed on your next full read and never shifts the pages still to come. **Required permission:** `event.view` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/financials/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/reserve-updates: get: tags: - Financials summary: List Company Reserve Updates description: > Lists every event's reserve change history in one feed, as the app's company-wide Reserve Updates listing and its export show it: each expected-total change a user made, each automatic reserve reduction from a payment, and each reserve history reset marker, with the event it belongs to and the running reserve after each change. Use it to copy reserve history into a data warehouse. For one event's history, use List Reserve Updates (`listFinancialsReserveUpdates`); for current reserve, paid, and incurred figures, use Get Balances (`getFinancialsBalances`). Each event's feed follows the same rules as List Reserve Updates: a reserve history reset establishes a per-event, per-category horizon — rows at or before it never render, and the reset itself renders as one marker row. `categoryId` narrows the feed to one reserved category. `asOfDate` returns the feed as of that date, like the app export's **As of** date: `user` rows with a later `reserveDate` and `erodingPayment` rows with a later `paymentDate` are left out; reset markers have no date and always render. Cursor-paginated: pass the previous page's `nextCursor` back as `cursor` until it is `null`. Rows are ordered by journal execution order, newest first. A change recorded while you page appears at the top of the feed on your next full read and never shifts the pages still to come. **Required permission:** `event.view` operationId: listFinancialsCompanyReserveUpdates parameters: - $ref: '#/components/parameters/companyId' - name: categoryId in: query schema: type: string format: uuid description: Only feed rows for this reserved category - name: asOfDate in: query schema: type: string format: date description: >- Return the feed as of this date (ISO `YYYY-MM-DD`); omit for the current feed example: '2026-06-30' - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 description: Page size (default 50, maximum 200) - name: cursor in: query schema: type: string description: >- The previous page's `nextCursor`, echoed verbatim. Opaque — its internals may change shape at any time responses: '200': description: One page of the company-wide reserve-update feed, newest first content: application/json: schema: type: object required: - rows - nextCursor properties: rows: type: array items: $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdate' nextCursor: type: string nullable: true description: >- Cursor for the next page; `null` exactly when the feed is exhausted examples: success: summary: One page with more to fetch 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' linkedEvent: id: 550e8400-e29b-41d4-a716-446655440500 displayName: Warehouse Fire eventReferenceId: A1B2C3 runningReserveCents: 6000 - 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: 550e8400-e29b-41d4-a716-446655440999 displayAuthor: null createdAt: '2026-06-01T10:30:00.000Z' linkedEvent: id: 550e8400-e29b-41d4-a716-446655440500 displayName: Warehouse Fire eventReferenceId: A1B2C3 runningReserveCents: 10000 - kind: reset journalId: 550e8400-e29b-41d4-a716-446655440901 categoryId: 550e8400-e29b-41d4-a716-446655440100 reversedUserReserveCents: 2500 createdBy: 550e8400-e29b-41d4-a716-446655440999 displayAuthor: null createdAt: '2026-05-01T08:00:00.000Z' linkedEvent: id: 550e8400-e29b-41d4-a716-446655440500 displayName: Warehouse Fire eventReferenceId: A1B2C3 nextCursor: eyJ2IjoxLCJzZXEiOjEyMzQ1fQ lastPage: summary: The final page value: rows: [] nextCursor: null '400': description: >- Bad Request — an unknown query field, a malformed parameter, or an invalid cursor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: malformedAsOfDate: summary: Malformed asOfDate value: error: code: VALIDATION_ERROR message: 'asOfDate: Expected an ISO date (YYYY-MM-DD)' userMessages: - 'asOfDate: Expected an ISO date (YYYY-MM-DD)' invalidCursor: summary: Invalid pagination cursor value: error: code: INVALID_CURSOR message: >- The cursor is not a valid pagination cursor for this listing. userMessages: - >- The cursor is not a valid pagination cursor for this listing. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- Not returned by this endpoint: a company with no reserve history reads as an empty feed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: FinancialsV2CompanyReserveUpdate: description: >- A company-wide reserve-update feed row, discriminated by `kind`: a reserve-update feed row (`user`, `erodingPayment`, or `reset`) plus the event it belongs to and, on `user` and `erodingPayment` rows, the running reserve. The same rows the app's company-wide Reserve Updates listing and its export show. oneOf: - title: User reserve update allOf: - $ref: '#/components/schemas/FinancialsV2UserReserveUpdate' - $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdateEvent' - $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdateBalance' - title: Eroding payment allOf: - $ref: '#/components/schemas/FinancialsV2ErodingPaymentReserveUpdate' - $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdateEvent' - $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdateBalance' - title: Reserve history reset allOf: - $ref: '#/components/schemas/FinancialsV2ReserveHistoryReset' - $ref: '#/components/schemas/FinancialsV2CompanyReserveUpdateEvent' 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 code: type: string description: Stable problem code for this individual validation failure example: BLANK_LIST_ELEMENT reason: type: string description: Stable reason the value violates its canonical contract example: blank-list-element expected: type: string description: The expected canonical value contract example: nonblank trimmed string 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 FinancialsV2CompanyReserveUpdateEvent: type: object description: The event fields every company-wide reserve-update feed row carries required: - linkedEvent - eventReferenceId properties: linkedEvent: type: object description: >- The event the row belongs to, display-ready (the server resolves the display name; an event without a name shows its reference id, then its id) required: - id - displayName properties: id: type: string format: uuid description: The event's id displayName: type: string description: The event's display name eventReferenceId: type: string nullable: true description: >- The event's own reference id (the app's Event ID column), or `null` when the event has none FinancialsV2CompanyReserveUpdateBalance: type: object description: >- The running reserve on a company-wide `user` or `erodingPayment` feed row required: - runningReserveCents properties: runningReserveCents: type: integer description: >- The event's reserve for this row's category just after this row, in signed integer cents (the app's Reserve column shows its magnitude). Computed over the whole feed, so a row reads the same on every page 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.