> ## 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. # Get connection schema history > Use this endpoint to list the earlier generations of a connection's schema map, oldest first. Each generation records when it stopped being the live schema map, and `retirementCause` records what Matcher observed when it retired it. ## OpenAPI ````yaml /pt/openapi/v3-current/matcher.yaml get /v1/discovery/connections/{connectionId}/schema/history openapi: 3.1.0 info: title: Matcher APIs description: >- Complete API reference for the Matcher reconciliation engine, providing automated transaction matching between Midaz Ledger and external systems. version: 5.0.0 license: name: Lerian Studio General License servers: - url: https://matcher.sandbox.lerian.net security: [] paths: /v1/discovery/connections/{connectionId}/schema/history: get: tags: - Discovery summary: Get connection schema history description: >- Use this endpoint to list the earlier generations of a connection's schema map, oldest first. Each generation records when it stopped being the live schema map, and `retirementCause` records what Matcher observed when it retired it. operationId: getDiscoveryConnectionSchemaHistory parameters: - description: Connection ID (UUID) in: path name: connectionId required: true schema: description: Connection ID (UUID) examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConnectionSchemaHistoryResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: ConnectionSchemaHistoryResponse: additionalProperties: false properties: connectionId: description: Internal Matcher connection identifier the history belongs to examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string generations: description: >- Prior generations of the schema map, oldest first; empty when the map has never changed items: $ref: '#/components/schemas/SchemaGenerationResponse' type: - array - 'null' required: - connectionId - generations type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object SchemaGenerationResponse: additionalProperties: false properties: archivedAt: description: When this generation stopped being the live schema map examples: - '2026-07-15T12:30:00Z' format: date-time type: string fieldReport: description: >- How this retired generation's field lists were obtained, read off its own rows: ENUMERATED from the source's own catalog, exhaustively for the credential that read it, so this generation's column sets are a statement about the source; SAMPLED from a sample of the source's data (MongoDB reads the union of top-level keys over $sample-d documents), so it may name a field the source no longer held, because nothing observed a removal — how such a field list built up while this generation was live, and what closed the generation, is stated in full in this operation's description. Present only when every table of this generation records the same kind: absent when they disagree, for every generation retired before the fact was recorded per row, and when the probe that installed a table of it could not show which connector produced its snapshot. It is never derived from the connection's current databaseType: that field is editable and a generation's provenance is not enum: - ENUMERATED - SAMPLED examples: - SAMPLED type: string retirementCause: description: >- What was observed of this whole generation when it was retired, when every table in it agrees; absent when one install retired different tables for different observed reasons, in which case each table carries its own. Values carry the same meanings as on a table, and none of them asserts that the source removed anything enum: - ABSENT_FROM_CATALOG - COLUMN_SET_SUPERSEDED - CONNECTION_RETIRED - UNKNOWN_LEGACY examples: - ABSENT_FROM_CATALOG type: string tables: description: The tables and columns this generation of the map asserted items: $ref: '#/components/schemas/SchemaTableResponse' type: - array - 'null' required: - archivedAt - tables type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object SchemaTableResponse: additionalProperties: false properties: columns: description: >- Columns discovered for the table. WHAT THIS LIST IS A STATEMENT ABOUT DEPENDS ON HOW THE CONNECTOR OBTAINED IT — see fieldReport on the map, or on the generation, that carries this table. WHERE THE FIELD LISTS ARE ENUMERATED from the source's own catalog, these are the columns the latest probe asserted for the credential that read it. WHERE THEY ARE SAMPLED from the source's data instead, a field listed here may appear in no document the source currently holds: it carries no marker saying so and stays extractable, deliberately, because nothing observed its removal. How a sampled connector's field lists build up, and what ends that, is stated in full in this operation's description — read it before authoring a field map against these columns items: $ref: '#/components/schemas/SchemaColumnResponse' type: - array - 'null' columnsNarrowed: description: >- The source now reports FEWER columns for this table than the read before did: the columns shown were confirmed by the latest probe, and at least one column it used to report is no longer among them. The table stays extractable from the narrower set; a field map projecting a column that stopped being reported will fail at extraction. It says nothing about WHY the set narrowed — a narrowed grant and a dropped column are the same answer from a catalog type: boolean columnsStale: description: >- The last probe named this table without confirming its columns, so the column list is the last CONFIRMED one and may no longer match the source. The table is still extractable from it; a field map authored against it may silently stop matching. ABSENT DOES NOT MEAN THE WHOLE LIST WAS CONFIRMED BY THE LATEST PROBE: it means that probe reported columns for this table, which confirms the list only where the field lists are ENUMERATED from a catalog. Where they are SAMPLED from the source's data a draw confirms only the fields it showed, and the rest of the list may include fields the latest draw did not show — see columns, and this operation's description, which states in full how such a list builds up and what ends it type: boolean notYetExtractableReason: description: >- Why this table cannot be extracted from yet; absent when it can. COLUMNS_NOT_ENUMERATED means the source named the table but no columns for it, which is indistinguishable between a source with no columns to give and columns the connection's credential cannot read enum: - COLUMNS_NOT_ENUMERATED examples: - COLUMNS_NOT_ENUMERATED type: string retirementCause: description: >- What was observed when this table's row stopped being the live truth; absent on a live row. ABSENT_FROM_CATALOG means the source's catalog no longer listed the table, which does NOT distinguish a dropped table from one this connection's credential can no longer see. COLUMN_SET_SUPERSEDED means the catalog still listed it with a different non-empty column set, the same ambiguity one level down; it is recorded only for a report that ENUMERATED the source's catalog, because a report whose field list was sampled from the source's data retires no column set when a draw differs — so a sampled table reaches this cause when its connection is retyped to a connector that enumerates and the catalog list supersedes the accumulated union. CONNECTION_RETIRED means an operator retired the connection, the one cause that is genuinely known. UNKNOWN_LEGACY means the row was archived by an earlier release that recorded no cause enum: - ABSENT_FROM_CATALOG - COLUMN_SET_SUPERSEDED - CONNECTION_RETIRED - UNKNOWN_LEGACY examples: - ABSENT_FROM_CATALOG type: string tableName: description: Name of the discovered table examples: - transactions type: string required: - tableName - columns type: object SchemaColumnResponse: additionalProperties: false properties: name: description: Column name examples: - amount type: string nullable: description: Historical nullability flag; omitted when unknown type: boolean type: description: Historical column data type; omitted when unknown examples: - numeric type: string required: - name type: object securitySchemes: BearerAuth: bearerFormat: JWT description: 'Bearer token authentication (format: "Bearer {token}")' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.