> ## 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.

# Adopt another version of the subscribed document

> Moves the subscription's pin to another catalog version — a DELIBERATE act: a release published upstream changes nothing here until somebody adopts it. The new version is fetched from the origin, verified and materialized BESIDE the old copy, never over it, so every report already generated stays explainable by its provenance. The answer carries what the new version does to the EXISTING mapping: its readiness against the adopted contract, the exact reason when it no longer plans at all (as information — the adoption stands), and how much of the new reference mapping it already agrees with. Omitting version adopts the newest the origin has; adopting the version already in force re-materializes the copy and leaves the history untouched.



## OpenAPI

````yaml /es/openapi/v3-current/reporter.yaml post /v1/regulatory/subscriptions/{subscriptionId}/adopt
openapi: 3.1.0
info:
  contact:
    name: Discord community
    url: https://discord.gg/DnhqKwkGv3
  description: >-
    This is OpenAPI documentation for Reporter. The unified reporter binary
    serves the REST API (RUN_MODE=api) and/or the RabbitMQ report-generation
    worker (RUN_MODE=worker); RUN_MODE=all runs both in one process for local
    development. All REST endpoints documented here serve only when RUN_MODE=api
    or all (port :4005); the worker (port :4006) exposes health/readyz/version
    only.
  license:
    name: Lerian Studio General License
  title: Midaz Reporter API
  version: 4.0.0
servers:
  - url: http://localhost:4005
  - url: https://localhost:4005
security:
  - BearerAuth: []
tags:
  - description: Generated report instances and their lifecycle.
    name: Reports
  - description: Reusable report definitions.
    name: Templates
  - description: Interactive construction of report templates.
    name: Template Builder
  - description: Scheduled report due-date tracking.
    name: Deadlines
  - description: Configured inputs that feed report data.
    name: Data Sources
  - description: Aggregated reporting metrics.
    name: Metrics
  - description: Published business event catalog and delivery policies.
    name: Streaming
paths:
  /v1/regulatory/subscriptions/{subscriptionId}/adopt:
    post:
      tags:
        - Regulatory Subscriptions
      summary: Adopt another version of the subscribed document
      description: >-
        Moves the subscription's pin to another catalog version — a DELIBERATE
        act: a release published upstream changes nothing here until somebody
        adopts it. The new version is fetched from the origin, verified and
        materialized BESIDE the old copy, never over it, so every report already
        generated stays explainable by its provenance. The answer carries what
        the new version does to the EXISTING mapping: its readiness against the
        adopted contract, the exact reason when it no longer plans at all (as
        information — the adoption stands), and how much of the new reference
        mapping it already agrees with. Omitting version adopts the newest the
        origin has; adopting the version already in force re-materializes the
        copy and leaves the history untouched.
      operationId: adoptRegulatoryVersion
      parameters:
        - description: Subscription whose pin moves.
          example: 00000000-0000-0000-0000-000000000000
          in: path
          name: subscriptionId
          required: true
          schema:
            description: Subscription whose pin moves.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdoptRegulatoryVersionHumaInputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionAdoption'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Not Found
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Internal Server Error
components:
  schemas:
    AdoptRegulatoryVersionHumaInputBody:
      additionalProperties: false
      properties:
        version:
          description: Catalog version to adopt. Omitted, the newest the origin has.
          examples:
            - 1.1.0
          type: string
      type: object
    VersionAdoption:
      additionalProperties: false
      properties:
        adjustment:
          $ref: '#/components/schemas/Adjustment'
        mappingBroken:
          description: >-
            Why the existing mapping no longer plans against the adopted
            contract, when it does not.
          examples:
            - 'dataset ''saldos'': field ''novoCampo'' is not a field...'
          type: string
        readiness:
          $ref: '#/components/schemas/Readiness'
        subscription:
          $ref: '#/components/schemas/Subscription'
      required:
        - subscription
      type: object
    Detail:
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          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
          examples:
            - - location: body.templateId
                message: expected string to match 'uuid' format
                value: not-a-uuid
          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
    Adjustment:
      additionalProperties: false
      properties:
        added:
          items:
            type: string
          type:
            - array
            - 'null'
        compared:
          type: boolean
        rebound:
          items:
            type: string
          type:
            - array
            - 'null'
        removed:
          items:
            type: string
          type:
            - array
            - 'null'
        retargeted:
          items:
            type: string
          type:
            - array
            - 'null'
        total:
          format: int64
          type: integer
        untouched:
          format: int64
          type: integer
      required:
        - compared
        - untouched
        - total
      type: object
    Readiness:
      additionalProperties: false
      properties:
        contractVersion:
          type: string
        document:
          type: string
        gaps:
          items:
            $ref: '#/components/schemas/Gap'
          type:
            - array
            - 'null'
        queries:
          items:
            $ref: '#/components/schemas/QueryReadiness'
          type:
            - array
            - 'null'
        startedFrom:
          type: string
        unsupported:
          items:
            type: string
          type:
            - array
            - 'null'
      required:
        - document
        - contractVersion
        - queries
      type: object
    Subscription:
      additionalProperties: false
      properties:
        adoptedVersion:
          description: Version of the document this tenant generates against
          examples:
            - 1.0.0
          type: string
        adoptionHistory:
          description: Append-only record of which version was adopted, by whom and when
          items:
            $ref: '#/components/schemas/Adoption'
          type:
            - array
            - 'null'
        bindingVersion:
          description: >-
            Version of the mapping in force, the one its ETag carries; 0 when
            none was written
          examples:
            - 3
          format: int64
          type: integer
        createdAt:
          description: Creation timestamp in UTC
          examples:
            - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
        deactivatedAt:
          description: When the subscription was last deactivated, in UTC; absent if never
          examples:
            - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
        deactivatedBy:
          description: >-
            Authenticated subject that last deactivated it; absent if never, or
            if that request identified nobody
          examples:
            - acme/00000000-0000-0000-0000-000000000000
          type: string
        documentId:
          description: Curated document this subscription files
          examples:
            - br.bcb.cadoc-4010
          type: string
        id:
          description: Unique subscription identifier
          examples:
            - 00000000-0000-0000-0000-000000000000
          type: string
        institutionId:
          description: >-
            Institution that files the document. Absent on a subscription made
            before filings named an institution: it generates for the tenant's
            only institution, and with none or several it waits until one is
            set.
          examples:
            - 00000000-0000-0000-0000-000000000000
          type: string
        reactivatedAt:
          description: When the subscription was last reactivated, in UTC; absent if never
          examples:
            - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
        reactivatedBy:
          description: Authenticated subject that last reactivated it; absent if never
          examples:
            - acme/00000000-0000-0000-0000-000000000000
          type: string
        status:
          description: active or inactive
          examples:
            - active
          type: string
        updatedAt:
          description: Most recent update timestamp in UTC
          examples:
            - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
        version:
          description: >-
            Version of the subscription; setting its institution presents it as
            If-Match. 0 on a subscription never written since versions were
            counted.
          examples:
            - 1
          format: int64
          type: integer
      required:
        - id
        - documentId
        - version
        - adoptedVersion
        - status
        - adoptionHistory
        - bindingVersion
        - createdAt
        - updatedAt
      type: object
    ErrorDetail:
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          examples:
            - body.templateId
          type: string
        message:
          description: Error message text
          examples:
            - expected string to match 'uuid' format
          type: string
        value:
          description: The value at the given location
          examples:
            - not-a-uuid
      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
    Gap:
      additionalProperties: false
      properties:
        field:
          description: Position in the contract the draft cannot fill, as "dataset.field".
          examples:
            - saldos_cosif.valor
          type: string
        reason:
          description: What the person completing the draft is told about this position.
          examples:
            - a consulta mapeada não devolve esta coluna
          type: string
        required:
          description: >-
            True when the document requires this position, which is what stops
            the draft being approved or downloaded.
          type: boolean
      required:
        - field
        - reason
        - required
      type: object
    QueryReadiness:
      additionalProperties: false
      properties:
        columns:
          items:
            $ref: '#/components/schemas/ColumnReadiness'
          type:
            - array
            - 'null'
        columnsChecked:
          type: boolean
        composedOver:
          type: string
        dataSource:
          type: string
        detail:
          type: string
        query:
          type: string
        resolvedTable:
          type: string
        status:
          type: string
        table:
          type: string
      required:
        - query
        - status
        - columnsChecked
      type: object
    Adoption:
      additionalProperties: false
      properties:
        adoptedAt:
          description: When it was adopted
          examples:
            - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
        adoptedBy:
          description: Who adopted it
          examples:
            - operator@bank.example
          type: string
        supersedes:
          description: Version it replaced, absent on the first adoption
          examples:
            - 1.0.0
          type: string
        version:
          description: Document version adopted
          examples:
            - 1.1.0
          type: string
      required:
        - version
        - adoptedAt
        - adoptedBy
      type: object
    ColumnReadiness:
      additionalProperties: false
      properties:
        column:
          type: string
        found:
          type: boolean
      required:
        - column
        - found
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````