> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dados.rio/llms.txt
> Use this file to discover all available pages before exploring further.

# Update endpoint mapping

> Update an existing endpoint-to-action mapping.

**Authorization**: Requires admin privileges to update mappings.

**Partial Updates**: You can update individual fields (path_pattern, method, action_id, description)
without affecting others. Provide only the fields you want to change.

**Validation**: The new path pattern and method combination must not conflict
with existing mappings (unless it's the same mapping being updated).

**Action Reference**: If updating action_id, the new action must exist.

**Use Cases**:
- Update endpoint patterns when API paths change
- Change the action associated with an endpoint
- Update descriptions for better documentation
- Administrative maintenance of authorization configuration



## OpenAPI

````yaml https://raw.githubusercontent.com/prefeitura-rio/heimdall/main/docs/api/openapi.json put /api/v1/mappings/{mapping_id}
openapi: 3.1.0
info:
  title: Heimdall Admin Service
  description: >-
    # Heimdall Admin Service API


    A comprehensive admin service for user and group management with
    authorization powered by Cerbos.


    ## Features


    - **User Management**: Automatic user creation from JWT tokens with
    role-based access control

    - **Group Management**: Create, manage, and assign users to groups with
    hierarchical permissions

    - **Role Management**: Define and assign roles to users and groups

    - **Mapping Management**: Configure API endpoint to action mappings for
    authorization

    - **Action Management**: Define available actions for fine-grained
    permission control

    - **Cerbos Integration**: Policy-based authorization with external Cerbos
    service

    - **Audit Logging**: Comprehensive audit trail for all administrative
    operations

    - **Redis Caching**: High-performance caching for frequently accessed data
  version: 1.0.0
servers:
  - url: https://services.pref.rio/heimdall-admin
    description: Production server
  - url: https://services.staging.app.dados.rio/heimdall-admin
    description: Staging server
security: []
tags:
  - name: health
    description: Service health and readiness checks
  - name: users
    description: >-
      User management operations. Users are automatically created from JWT
      tokens.
  - name: groups
    description: >-
      Group management operations. Groups organize users and can have roles
      assigned.
  - name: memberships
    description: Group membership management. Assign and remove users from groups.
  - name: roles
    description: >-
      Role management operations. Roles define permissions that can be assigned
      to users or groups.
  - name: actions
    description: >-
      Action management operations. Actions define the granular permissions
      available in the system.
  - name: mappings
    description: >-
      API endpoint to action mapping configuration. Maps HTTP endpoints to
      authorization actions.
paths:
  /api/v1/mappings/{mapping_id}:
    put:
      tags:
        - mappings
      summary: Update endpoint mapping
      description: >-
        Update an existing endpoint-to-action mapping.


        **Authorization**: Requires admin privileges to update mappings.


        **Partial Updates**: You can update individual fields (path_pattern,
        method, action_id, description)

        without affecting others. Provide only the fields you want to change.


        **Validation**: The new path pattern and method combination must not
        conflict

        with existing mappings (unless it's the same mapping being updated).


        **Action Reference**: If updating action_id, the new action must exist.


        **Use Cases**:

        - Update endpoint patterns when API paths change

        - Change the action associated with an endpoint

        - Update descriptions for better documentation

        - Administrative maintenance of authorization configuration
      operationId: update_mapping_api_v1_mappings__mapping_id__put
      parameters:
        - name: mapping_id
          in: path
          required: true
          schema:
            type: integer
            title: Mapping Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingUpdateRequest'
      responses:
        '200':
          description: Mapping updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingDetailResponse'
              example:
                id: 1
                path_pattern: /api/v1/users/{user_id}/profile
                method: GET
                action: user:read
                description: Get detailed user profile information
                created_by: '12345678901'
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-16T14:20:00Z'
        '400':
          description: Bad request - Invalid action ID or conflicting mapping
          content:
            application/json:
              example:
                detail: Action with ID 999 does not exist
        '401':
          description: Unauthorized - Invalid or missing JWT token
          content:
            application/json:
              example:
                detail: Could not validate credentials
        '403':
          description: Forbidden - Insufficient permissions to update mappings
          content:
            application/json:
              example:
                detail: Permission denied to update mapping 1
        '404':
          description: Mapping not found
          content:
            application/json:
              example:
                detail: Mapping with ID 999 not found
        '422':
          description: Validation error - Invalid request data
          content:
            application/json:
              example:
                detail: Validation error
                errors:
                  - loc:
                      - body
                      - method
                    msg: string does not match regex
                    type: value_error.regex
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                detail: 'Failed to update mapping: Database connection error'
      security:
        - HTTPBearer: []
components:
  schemas:
    MappingUpdateRequest:
      properties:
        path_pattern:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: 'null'
          title: Path Pattern
          description: Updated URL path pattern
          example: /api/v1/users/{user_id}
        method:
          anyOf:
            - type: string
              pattern: ^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$
            - type: 'null'
          title: Method
          description: Updated HTTP method
          example: GET
        action_id:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: 'null'
          title: Action Id
          description: Updated action ID
          example: 2
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
          description: Updated description
          example: Get detailed user profile information
      type: object
      title: MappingUpdateRequest
      description: Request model for updating an existing endpoint-to-action mapping.
      example:
        description: Get detailed user profile information
        path_pattern: /api/v1/users/{user_id}/profile
    MappingDetailResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Unique identifier of the mapping
          example: 1
        path_pattern:
          type: string
          title: Path Pattern
          description: URL path pattern
          example: /api/v1/users/{user_id}
        method:
          type: string
          title: Method
          description: HTTP method
          example: GET
        action:
          type: string
          title: Action
          description: Action name
          example: user:read
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Mapping description
          example: Get user profile information
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: CPF of the user who created this mapping
          example: '12345678901'
        created_at:
          type: string
          title: Created At
          description: ISO timestamp when the mapping was created
          example: '2024-01-15T10:30:00Z'
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: ISO timestamp when the mapping was last updated
          example: '2024-01-16T14:20:00Z'
      type: object
      required:
        - id
        - path_pattern
        - method
        - action
        - created_at
      title: MappingDetailResponse
      description: Detailed response model for mapping information.
      example:
        action: user:read
        created_at: '2024-01-15T10:30:00Z'
        created_by: '12345678901'
        description: Get user profile information
        id: 1
        method: GET
        path_pattern: /api/v1/users/{user_id}
        updated_at: '2024-01-16T14:20:00Z'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````