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

# Replace exact advertiser access for a buyer agent



## OpenAPI

````yaml /openapi/v3.yaml put /api/v2/buyer-agent-principals/{principalId}/access
openapi: 3.1.0
info:
  title: Semicola Exchange platform API
  version: 3.0.0-preview
  description: >-
    Platform endpoints of Semicola: sign-in, signup and OAuth for MCP clients,
    accounts, members and keys, billing, notifications, the Semi assistant (chat
    stream, confirmations, conversations), the MCP App widget host and realtime
    feeds. Typed agent tools live on the MCP server at /mcp/v3.
servers:
  - url: https://api.semicola.com
security:
  - bearerAuth: []
  - sessionCookie: []
tags:
  - name: Auth
  - name: Signup
  - name: OAuth
  - name: Accounts
  - name: Members
  - name: API Keys
  - name: Buyer Agent Principals
  - name: Asks
  - name: Connected Apps
  - name: Onboarding
  - name: Billing
  - name: AI Usage
  - name: Notifications
  - name: Assistant
  - name: MCP Apps
  - name: Realtime
  - name: Demo
paths:
  /api/v2/buyer-agent-principals/{principalId}/access:
    put:
      tags:
        - Buyer Agent Principals
      summary: Replace exact advertiser access for a buyer agent
      operationId: putBuyerAgentPrincipalsByPrincipalIdAccess
      parameters:
        - name: principalId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                expectedAccessRevision:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                advertisers:
                  maxItems: 500
                  type: array
                  items:
                    type: object
                    properties:
                      advertiserId:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          - type: string
                            pattern: ^\d+$
                      role:
                        type: string
                        enum:
                          - READ
                          - READ_WRITE
                    required:
                      - advertiserId
                      - role
                    additionalProperties: false
              required:
                - expectedAccessRevision
                - advertisers
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                      - type: object
                        properties:
                          access:
                            type: object
                            properties:
                              revision:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                              advertisers:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    advertiserId:
                                      type: integer
                                      minimum: -9007199254740991
                                      maximum: 9007199254740991
                                    advertiserName:
                                      type: string
                                    role:
                                      type: string
                                      enum:
                                        - READ
                                        - READ_WRITE
                                  required:
                                    - advertiserId
                                    - advertiserName
                                    - role
                                  additionalProperties: false
                            required:
                              - revision
                              - advertisers
                            additionalProperties: false
                        required:
                          - access
                        additionalProperties: false
                      - type: 'null'
                  error:
                    anyOf:
                      - type: object
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                          field:
                            type: string
                          details: {}
                        required:
                          - code
                          - message
                        additionalProperties: false
                      - type: 'null'
                required:
                  - data
                  - error
                additionalProperties: false
        default:
          description: >-
            Error envelope `{data: null, error: {code, message, field?,
            details?}}`.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth access token.
    sessionCookie:
      type: apiKey
      in: cookie
      name: sc_session

````