# Proposed contract, version 1: endpoints, errors, paging, idempotency, security and the capability of every
# operation. Resource schemas were initialized from the data model (docs/06-data) and are kept aligned with it; input
# schemas (*Input, *Request) and views are specific to this contract. Status: proposal for review, not confirmed design.
# Conventions: docs/05-interfaces/choosing-an-interface.md. Vendor extensions: x-moonitoring-audience (who calls),
# x-moonitoring-capability (the capability checked), x-moonitoring-entitlement (the entitlement feature checked),
# x-moonitoring-requirements (the requirements of 1.requisiti-raffinati.txt the operation serves).
openapi: 3.1.0
info:
  title: MooChat Agents API
  version: 1.0.0
  description: 'The configuration of the agents: definitions, the model profiles the AI gateway calls, the tools
    published by the systems'' MCP servers and which tools each agent may use. Managed by staff in the Console;
    every change is a PlatformAuditEvent. Organization users read the agents they may use.'
servers:
- url: https://moochat.moonitoring.com/agents/v1
  description: Prod
- url: https://stage-moochat.moonitoring.com/agents/v1
  description: Stage, through IAP
security:
- bearer: []
tags:
- name: Agents
  description: Configured assistants
- name: Tools
  description: What the model can call
- name: Model profiles
  description: Models and their settings
- name: Connectors
  description: External systems, future work
paths:
  /agents:
    get:
      summary: List agents
      operationId: listAgents
      description: Staff see every agent; an Organization user sees the Organization-audience agents whose feature
        their Organization holds.
      tags:
      - Agents
      parameters:
      - name: audience
        in: query
        required: false
        schema:
          type: string
          enum:
          - organization
          - staff
        description: Only this audience.
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - paused
          - archived
        description: Only this status.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentDefinition'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: any
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '120'
      - '120.4'
      - '120.5'
    post:
      summary: Create an agent
      operationId: createAgent
      tags:
      - Agents
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentDefinitionInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDefinition'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '120'
      - '1006.26'
  /agents/{agent_id}:
    get:
      summary: Read an agent
      operationId: getAgent
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDefinition'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: any
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '120'
    patch:
      summary: Update an agent
      operationId: updateAgent
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentDefinitionInput'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDefinition'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '120.3'
      - '120.5'
      - '120.6'
      - '120.7'
      - '1006.26'
  /agents/{agent_id}/status:
    post:
      summary: Pause, resume or archive an agent
      operationId: setAgentStatus
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - active
                  - paused
                  - archived
              required:
              - status
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDefinition'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '120.8'
      - '1006.26'
  /agents/{agent_id}/tools:
    get:
      summary: List an agent's tool bindings
      operationId: listAgentTools
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentToolBinding'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: any
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '123'
    post:
      summary: Bind a tool to an agent
      operationId: bindAgentTool
      tags:
      - Agents
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentToolBindingInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentToolBinding'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '123'
      - '1006.26'
  /agents/{agent_id}/tools/{binding_id}:
    patch:
      summary: Change a binding
      operationId: updateAgentToolBinding
      description: A binding can only make confirmation stricter than the tool's risk.
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: binding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentToolBindingInput'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentToolBinding'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '123.4'
      - '123.5'
      - '1006.26'
    delete:
      summary: Unbind a tool
      operationId: unbindAgentTool
      tags:
      - Agents
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: binding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Done.
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '123'
      - '1006.26'
  /tools:
    get:
      summary: List tools
      operationId: listTools
      tags:
      - Tools
      parameters:
      - name: system
        in: query
        required: false
        schema:
          type: string
        description: Only tools of this system's MCP server.
      - name: risk
        in: query
        required: false
        schema:
          type: string
          enum:
          - read
          - write
          - dangerous
        description: Only this risk.
      - name: data_class
        in: query
        required: false
        schema:
          type: string
          enum:
          - public
          - personal
        description: Only this data class.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentTool'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '122'
      - '122.2'
    post:
      summary: Register a tool
      operationId: createTool
      tags:
      - Tools
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentToolInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTool'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '122'
      - '122.4'
      - '122.5'
      - '1006.26'
  /tools/{tool_id}:
    patch:
      summary: Update a tool
      operationId: updateTool
      tags:
      - Tools
      parameters:
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentToolInput'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTool'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '122'
      - '1006.26'
  /model-profiles:
    get:
      summary: List model profiles
      operationId: listModelProfiles
      description: Staff see all; an Organization user sees the profiles of the tiers their plan allows, to choose
        one when the plan permits it.
      tags:
      - Model profiles
      parameters:
      - name: tier
        in: query
        required: false
        schema:
          type: string
          enum:
          - lite
          - standard
          - pro
        description: Only this tier.
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - retired
        description: Only this status.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentModelProfile'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: any
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '121'
      - '121.7'
    post:
      summary: Create a model profile
      operationId: createModelProfile
      tags:
      - Model profiles
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentModelProfileInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentModelProfile'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agent_models.manage
      x-moonitoring-requirements:
      - '121'
      - '121.6'
      - '1006.27'
  /model-profiles/{profile_id}:
    patch:
      summary: Update a model profile
      operationId: updateModelProfile
      tags:
      - Model profiles
      parameters:
      - name: profile_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentModelProfileInput'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentModelProfile'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agent_models.manage
      x-moonitoring-requirements:
      - '121'
      - '121.9'
      - '121.10'
      - '1006.27'
  /model-profiles/{profile_id}/retire:
    post:
      summary: Retire a model profile
      operationId: retireModelProfile
      description: Agents that used it by default are served by the active profile of the same tier.
      tags:
      - Model profiles
      parameters:
      - name: profile_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentModelProfile'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agent_models.manage
      x-moonitoring-requirements:
      - '121.11'
      - '1006.27'
  /connectors:
    get:
      summary: List connectors
      operationId: listConnectors
      description: FUTURE WORK.
      tags:
      - Connectors
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentConnector'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: staff
      x-moonitoring-capability: moochat.agents.manage
      x-moonitoring-requirements:
      - '127'
  /organizations/{organization_id}/connector-instances:
    get:
      summary: List an Organization's connections
      operationId: listConnectorInstances
      description: FUTURE WORK.
      tags:
      - Connectors
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The Organization.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentConnectorInstance'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: organization
      x-moonitoring-capability: moochat.moochat.access
      x-moonitoring-requirements:
      - '128'
    post:
      summary: Connect an external system
      operationId: createConnectorInstance
      description: FUTURE WORK.
      tags:
      - Connectors
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The Organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorInstanceInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConnectorInstance'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: organization
      x-moonitoring-capability: moochat.connectors.manage
      x-moonitoring-requirements:
      - '128'
      - '128.5'
  /connector-instances/{instance_id}/revoke:
    post:
      summary: Revoke a connection
      operationId: revokeConnectorInstance
      description: FUTURE WORK.
      tags:
      - Connectors
      parameters:
      - name: instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConnectorInstance'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      x-moonitoring-audience: organization
      x-moonitoring-capability: moochat.connectors.manage
      x-moonitoring-requirements:
      - '128.6'
components:
  schemas:
    AgentDefinition:
      description: 'A configured assistant: its purpose, who may use it (Organizations or staff), the entitlement
        feature it needs, the tools bound to it and the model profile it uses by default. MooChat and the assistant
        in the Console are two rows run by one agent runtime; a third assistant is a new row, not a new system.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        slug:
          type: string
          description: Unique. e.g. moochat, console-assistant.
        name:
          type: string
        audience:
          type: string
          enum:
          - organization
          - staff
        feature:
          type: string
          description: The entitlement feature an Organization needs, e.g. `moochat.chat` (see Entitlement); empty
            for staff agents.
        prompt_version:
          type: string
          description: Version of the system prompt in the runtime's code; prompts are code, not data.
        default_model_profile:
          type: string
          format: uuid
          description: ID of the AgentModelProfile.
        status:
          type: string
          enum:
          - active
          - paused
          - archived
          default: active
        system_version:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/SystemVersion
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - slug
      - name
      - audience
      - prompt_version
      - default_model_profile
      - status
      - system_version
      - created_at
      - updated_at
    AgentModelProfile:
      description: 'A model and its settings as the AI gateway calls it: provider, model id, region, the data classes
        it may receive, its tier and parameters. Profiles are created, edited and retired from the Console; the
        choice of model behind an agent is a configuration change with an audit event, never a deploy.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        slug:
          type: string
          description: Unique. e.g. gemini-flash-eu, gemini-pro-eu, openrouter-public.
        provider:
          type: string
          enum:
          - vertex_ai
          - openrouter
        model:
          type: string
          description: The provider's model id, e.g. gemini-3.8-flash.
        region:
          type: string
          description: e.g. europe-west8; empty for a provider that does not pin a region.
        data_classes:
          type: array
          items:
            type: string
            enum:
            - public
            - personal
          minItems: 1
          description: Which data the profile may receive. personal requires an EU region and zero data retention.
        tier:
          type: string
          enum:
          - lite
          - standard
          - pro
          description: What a plan's `model_tier` (see Entitlement, `Entitlement.limits`) maps to.
        parameters:
          type: string
          description: Temperature, output cap, context cap, thinking budget.
        cost_input_micros:
          type: integer
        cost_output_micros:
          type: integer
          description: Provider list price per 1M tokens in millionths of a euro, for the ledger; updated when the
            provider changes it.
        status:
          type: string
          enum:
          - active
          - retired
          default: active
        system_version:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/SystemVersion
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - slug
      - provider
      - model
      - data_classes
      - tier
      - parameters
      - cost_input_micros
      - cost_output_micros
      - status
      - system_version
      - created_at
      - updated_at
    AgentTool:
      description: One callable the model can see, published by a product together with its capabilities. It names
        the MCP server that implements it, the capability a caller must hold, the data class of what it returns
        and its risk, which decides whether the user must confirm it.
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        name:
          type: string
          description: 'Unique. Namespaced like a capability: <system>.<tool>, e.g. `farm.animals.search`,
            `grant.calls.search`, `ingestion.failed_jobs.list`.'
        mcp_server:
          type: string
          description: The product's MCP server and tool name that implement it.
        required_capabilities:
          type: array
          items:
            type: string
          description: 'Capabilities of OrganizationRoleCapabilityEnum or MoonitoringCapabilityEnum, all of which
            the caller must hold for the tool to be offered and run. Empty: any sender of an agent bound to the
            tool. Each name must exist in a system''s catalog.'
        required_features:
          type: array
          items:
            type: string
          description: 'Entitlement features of Entitlement the sender''s Organization must hold, all of them, active
            at the time of the message: e.g. `farm.models.mastitis` for a tool that calls that model. Empty: only
            the agent''s `AgentDefinition.feature` is needed. Not evaluated for staff agents, which have no Organization.'
        data_class:
          type: string
          enum:
          - public
          - personal
          description: What the tool returns; a personal tool can only be used with a profile that allows personal
            data.
        risk:
          type: string
          enum:
          - read
          - write
          - dangerous
          description: '`read`: no confirmation; write: the user confirms; dangerous: the user confirms and the
            call is logged as an audit event.'
        description:
          type: string
          description: What the model reads to decide when to call it; versioned with the product.
        connector:
          type: string
          format: uuid
          description: ID of the AgentConnector.
        version:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
      - mcp_server
      - data_class
      - risk
      - description
      - version
      - created_at
      - updated_at
    AgentToolBinding:
      description: Which tools an agent may use. A binding can make a tool stricter for one agent (require confirmation)
        but never looser.
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        agent:
          type: string
          format: uuid
          description: ID of the AgentDefinition.
        tool:
          type: string
          format: uuid
          description: ID of the AgentTool.
        enabled:
          type: boolean
          default: true
        requires_confirmation:
          type: boolean
          description: Overrides the tool's risk for this agent; can only make it stricter.
        system_version:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/SystemVersion
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - agent
      - tool
      - enabled
      - system_version
      - created_at
      - updated_at
    AgentConnector:
      description: 'Future work. A kind of external system a tool may need per-Organization credentials for: a vendor
        cloud, a calendar, e-mail. It names the scopes an instance asks for.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        name:
          type: string
          description: Unique.
        scopes:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
      - scopes
      - created_at
      - updated_at
    AgentConnectorInstance:
      description: 'Future work. One Organization''s connection to a connector: who consented, where the credential
        lives (the secret manager, never the database) and whether it was revoked.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        connector:
          type: string
          format: uuid
          description: ID of the AgentConnector.
        organization:
          type: string
          format: uuid
          description: ID of the Organization.
        credential_ref:
          type: string
        consented_by:
          type: string
          format: uuid
          description: ID of the User.
        revoked_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - connector
      - organization
      - credential_ref
      - consented_by
      - created_at
      - updated_at
    AgentDefinitionInput:
      type: object
      description: Input to create or change a AgentDefinition; server-managed fields are left out.
      properties:
        slug:
          type: string
          description: Unique. e.g. moochat, console-assistant.
        name:
          type: string
        audience:
          type: string
          enum:
          - organization
          - staff
        feature:
          type: string
          description: The entitlement feature an Organization needs, e.g. `moochat.chat` (see Entitlement); empty
            for staff agents.
        prompt_version:
          type: string
          description: Version of the system prompt in the runtime's code; prompts are code, not data.
        default_model_profile:
          type: string
          format: uuid
          description: ID of the AgentModelProfile.
      required:
      - slug
      - name
      - audience
      - prompt_version
      - default_model_profile
      additionalProperties: false
    AgentToolBindingInput:
      type: object
      description: Input to create or change a AgentToolBinding; server-managed fields are left out.
      properties:
        tool:
          type: string
          format: uuid
          description: ID of the AgentTool.
        enabled:
          type: boolean
          default: true
        requires_confirmation:
          type: boolean
          description: Overrides the tool's risk for this agent; can only make it stricter.
      required:
      - tool
      - enabled
      additionalProperties: false
    AgentToolInput:
      type: object
      description: Names a tool of a system's MCP server. Each required capability must exist in a system's catalog.
      properties:
        name:
          type: string
          description: 'Unique. Namespaced like a capability: <system>.<tool>, e.g. `farm.animals.search`,
            `grant.calls.search`, `ingestion.failed_jobs.list`.'
        mcp_server:
          type: string
          description: The product's MCP server and tool name that implement it.
        required_capabilities:
          type: array
          items:
            type: string
          description: 'Capabilities of OrganizationRoleCapabilityEnum or MoonitoringCapabilityEnum, all of which
            the caller must hold for the tool to be offered and run. Empty: any sender of an agent bound to the
            tool. Each name must exist in a system''s catalog.'
        required_features:
          type: array
          items:
            type: string
          description: 'Entitlement features of Entitlement the sender''s Organization must hold, all of them, active
            at the time of the message: e.g. `farm.models.mastitis` for a tool that calls that model. Empty: only
            the agent''s `AgentDefinition.feature` is needed. Not evaluated for staff agents, which have no Organization.'
        data_class:
          type: string
          enum:
          - public
          - personal
          description: What the tool returns; a personal tool can only be used with a profile that allows personal
            data.
        risk:
          type: string
          enum:
          - read
          - write
          - dangerous
          description: '`read`: no confirmation; write: the user confirms; dangerous: the user confirms and the
            call is logged as an audit event.'
        description:
          type: string
          description: What the model reads to decide when to call it; versioned with the product.
        connector:
          type: string
          format: uuid
          description: ID of the AgentConnector.
        version:
          type: string
      required:
      - name
      - mcp_server
      - data_class
      - risk
      - description
      - version
      additionalProperties: false
    AgentModelProfileInput:
      type: object
      description: A model and its settings. A profile that accepts personal data must pin an EU region and zero
        data retention.
      properties:
        slug:
          type: string
          description: Unique. e.g. gemini-flash-eu, gemini-pro-eu, openrouter-public.
        provider:
          type: string
          enum:
          - vertex_ai
          - openrouter
        model:
          type: string
          description: The provider's model id, e.g. gemini-3.8-flash.
        region:
          type: string
          description: e.g. europe-west8; empty for a provider that does not pin a region.
        data_classes:
          type: array
          items:
            type: string
            enum:
            - public
            - personal
          minItems: 1
          description: Which data the profile may receive. personal requires an EU region and zero data retention.
        tier:
          type: string
          enum:
          - lite
          - standard
          - pro
          description: What a plan's `model_tier` (see Entitlement, `Entitlement.limits`) maps to.
        parameters:
          type: string
          description: Temperature, output cap, context cap, thinking budget.
        cost_input_micros:
          type: integer
        cost_output_micros:
          type: integer
          description: Provider list price per 1M tokens in millionths of a euro, for the ledger; updated when the
            provider changes it.
      required:
      - slug
      - provider
      - model
      - data_classes
      - tier
      - parameters
      - cost_input_micros
      - cost_output_micros
      additionalProperties: false
    ConnectorInstanceInput:
      type: object
      description: 'FUTURE WORK: one Organization''s connection to a connector, with the consent of the user who
        creates it. The credential goes to Secret Manager.'
      properties:
        connector:
          type: string
          format: uuid
        credential:
          type: object
          additionalProperties:
            type: string
      required:
      - connector
      - credential
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The short-lived token signed by `access`: an Organization user token, a staff token or a client
        token, as the operation''s audience says.'