> ## 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. # Replace an institution > Replaces the institution's name, CNPJ and scope, IF If-Match carries the version the caller read. Without a readable If-Match the request is refused with 428; a stale version is refused with 409 naming both versions. The answer carries the new version in the ETag. ## OpenAPI ````yaml /es/openapi/v3-current/reporter.yaml put /v1/institutions/{institutionId} 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/institutions/{institutionId}: put: tags: - Institutions summary: Replace an institution description: >- Replaces the institution's name, CNPJ and scope, IF If-Match carries the version the caller read. Without a readable If-Match the request is refused with 428; a stale version is refused with 409 naming both versions. The answer carries the new version in the ETag. operationId: updateInstitution parameters: - description: Unique institution identifier. example: 00000000-0000-0000-0000-000000000000 in: path name: institutionId required: true schema: description: Unique institution identifier. type: string - description: Version the caller read, from the ETag of a previous read. Required. example: '"1"' in: header name: If-Match schema: description: >- Version the caller read, from the ETag of a previous read. Required. type: string requestBody: content: application/json: schema: additionalProperties: false properties: cnpj: description: >- CNPJ of the institution, numeric or alphanumeric, with or without punctuation. examples: - 12.ABC.345/01DE-35 type: string name: description: Name of the institution. examples: - Banco Exemplo S.A. type: string scope: additionalProperties: $ref: '#/components/schemas/DataSourceScope' description: >- The rows of each data source that belong to this institution, keyed by data source name. May be empty. type: object required: - name - cnpj - scope type: object description: JSON request payload. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Institution' description: OK headers: ETag: schema: description: >- Version of the institution; present it as If-Match to update on top of it. examples: - '"1"' type: string '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 '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Conflict '428': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Precondition Required '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error components: schemas: DataSourceScope: additionalProperties: false properties: tables: additionalProperties: $ref: '#/components/schemas/TableScope' description: >- The tables of the data source the institution reads, keyed by table name; empty when it owns the whole data source. type: object whole: description: The institution owns every table of the data source. examples: - false type: boolean required: - whole - tables type: object Institution: additionalProperties: false properties: cnpj: description: >- CNPJ of the institution, uppercase and without punctuation; numeric or alphanumeric. examples: - 12ABC34501DE35 type: string createdAt: description: Creation timestamp in UTC. examples: - '2026-01-01T00:00:00Z' format: date-time type: string id: description: Unique institution identifier. examples: - 00000000-0000-0000-0000-000000000000 type: string name: description: Name of the institution. examples: - Banco Exemplo S.A. type: string scope: additionalProperties: $ref: '#/components/schemas/DataSourceScope' description: The rows of each data source that belong to this institution. type: object updatedAt: description: Most recent update timestamp in UTC. examples: - '2026-01-01T00:00:00Z' format: date-time type: string version: description: Version of the institution; an update presents it as If-Match. examples: - 1 format: int64 type: integer required: - id - name - cnpj - scope - version - createdAt - updatedAt type: object Detail: properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -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 TableScope: additionalProperties: false properties: conditions: additionalProperties: $ref: '#/components/schemas/FilterCondition' description: >- Conditions a row must meet to belong to the institution, keyed by field, in the report filter vocabulary; at least one is eq or in, and the others may narrow with any operator. Empty on a shared table. examples: - organization_id: eq: - 00000000-0000-0000-0000-000000000000 type: object shared: description: The table is reference data every institution reads whole. examples: - false type: boolean required: - shared - conditions 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 FilterCondition: properties: between: description: Inclusive lower and upper bounds for a range match. examples: - - 100 - 1000 items: {} type: - array - 'null' eq: description: Values matched for equality; multiple values are combined with OR. examples: - - active - pending items: {} type: - array - 'null' gt: description: Single lower-bound value that the field must exceed. examples: - - 100 items: {} type: - array - 'null' gte: description: Single inclusive lower-bound value for the field. examples: - - '2025-06-01' items: {} type: - array - 'null' in: description: Values for which the field may match any member of the list. examples: - - active - pending - suspended items: {} type: - array - 'null' lt: description: Single upper-bound value that the field must remain below. examples: - - 1000 items: {} type: - array - 'null' lte: description: Single inclusive upper-bound value for the field. examples: - - '2025-06-30' items: {} type: - array - 'null' nin: description: Values excluded from matching records. examples: - - deleted - archived items: {} type: - array - 'null' type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````