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

# Get an Agent's effective control manifest

> Returns the authenticated workspace view of the Agent profile, ordered rules, knowledge readiness, handoff policy, automations, safe presentation metadata, and protocol differences. Requires `content:read` and remains tenant-scoped.



## OpenAPI

````yaml /openapi.yaml get /workspaces/{workspace}/agents/{agent}/controls
openapi: 3.1.0
info:
  title: Contact Button API
  version: 1.0.0-alpha.1
  description: >
    API-first management and public agent actions for Contact Buttons and
    button.contact pages.

    API v1 is the first public contract. Existing private legacy API and browser
    workflows remain supported.
  contact:
    name: Contact Button
    url: https://learn.contactbutton.com
servers:
  - url: https://api.contactbutton.com/v1
    description: Production (canonical)
  - url: https://app.contactbutton.com/v1
    description: Backwards-compatible application-domain alias
security:
  - bearerAuth: []
tags:
  - name: Onboarding
    description: Human-verified agent onboarding.
  - name: Workspaces
  - name: Team
  - name: Pages
  - name: Agents
    description: Workspace Agent profile and behavior configuration.
  - name: Domains
  - name: Buttons
  - name: Forms
  - name: Surveys
  - name: Apps
  - name: Knowledge
  - name: Booking
  - name: Telephony
    description: >-
      Bring-your-own-Telnyx setup, call flows, phone numbers, and voice
      interactions.
  - name: Reviews
    description: >-
      Send consented review requests through workspace-owned email, SMS, and
      WhatsApp channels.
  - name: Commerce
  - name: Conversations
    description: >-
      Contact-centric threads and messages across chat, email, WhatsApp, and
      forms.
  - name: Engagement inbox
  - name: Public actions
    description: Public, rate-limited actions that may require human confirmation.
paths:
  /workspaces/{workspace}/agents/{agent}/controls:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Agents
      summary: Get an Agent's effective control manifest
      description: >-
        Returns the authenticated workspace view of the Agent profile, ordered
        rules, knowledge readiness, handoff policy, automations, safe
        presentation metadata, and protocol differences. Requires `content:read`
        and remains tenant-scoped.
      operationId: getAgentControls
      responses:
        '200':
          description: Effective Agent controls and protocol contract.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/AgentControlManifest'
                  meta:
                    type: object
        '403':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
components:
  parameters:
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AgentId:
      name: agent
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    AgentControlManifest:
      type: object
      required:
        - id
        - type
        - name
        - status
        - profile
        - rules
        - knowledge
        - handoff
        - automations
        - presentation
        - protocol_contract
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - agent_control_manifest
        name:
          type: string
        status:
          type: string
        profile:
          type: object
          required:
            - enabled
            - value
          properties:
            enabled:
              type: boolean
            value:
              $ref: '#/components/schemas/AgentProfileInput'
        rules:
          type: object
          required:
            - feature_enabled
            - rule_set_version
            - configured_count
            - active_count
            - items
          properties:
            feature_enabled:
              type: boolean
            rule_set_version:
              type: integer
            configured_count:
              type: integer
            active_count:
              type: integer
            compiled_fingerprint:
              type:
                - string
                - 'null'
            items:
              type: array
              items:
                $ref: '#/components/schemas/AgentRule'
        knowledge:
          type: object
          required:
            - enabled
            - summary
            - warnings
          properties:
            enabled:
              type: boolean
            summary:
              type: object
              additionalProperties: true
            warnings:
              type: array
              items:
                type: string
        handoff:
          type: object
          required:
            - enabled
            - policy
          properties:
            enabled:
              type: boolean
            policy:
              $ref: '#/components/schemas/AgentHandoffPolicyInput'
        automations:
          type: object
          required:
            - enabled
            - version
            - items
            - supported_triggers
            - supported_outcomes
          properties:
            enabled:
              type: boolean
            version:
              type: integer
            items:
              type: array
              items:
                $ref: '#/components/schemas/AgentAutomationRule'
            supported_triggers:
              type: object
              additionalProperties:
                type: string
            supported_outcomes:
              type: object
              additionalProperties:
                type: string
        presentation:
          $ref: '#/components/schemas/PublicAgentPresentation'
        protocol_contract:
          $ref: '#/components/schemas/AgentProtocolCatalog'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    AgentProfileInput:
      type: object
      additionalProperties: false
      properties:
        business_name:
          type:
            - string
            - 'null'
          maxLength: 120
        industry:
          type:
            - string
            - 'null'
          maxLength: 120
        business_overview:
          type:
            - string
            - 'null'
          maxLength: 2000
          description: >-
            Stable business context. Put changing facts such as prices,
            policies, and products in Knowledge.
        role:
          type:
            - string
            - 'null'
          maxLength: 160
        tone:
          type: string
          enum:
            - default
            - friendly
            - professional
            - casual
            - direct
            - custom
        custom_tone:
          type:
            - string
            - 'null'
          maxLength: 500
        answer_length:
          type: string
          enum:
            - default
            - short
            - medium
            - detailed
    AgentRule:
      type: object
      additionalProperties: false
      required:
        - id
        - instruction
        - enabled
        - position
      properties:
        id:
          type: string
          format: uuid
        title:
          type:
            - string
            - 'null'
          maxLength: 120
        template_key:
          type:
            - string
            - 'null'
          enum:
            - unsupported_topics
            - sensitive_questions
            - commitments
            - escalation
            - promoted_services
            - null
        instruction:
          type: string
          maxLength: 4000
          description: Behavioral guidance only. Put factual business content in Knowledge.
        enabled:
          type: boolean
        position:
          type: integer
          minimum: 1
          maximum: 50
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    AgentHandoffPolicyInput:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        trigger_order:
          type: array
          minItems: 6
          maxItems: 6
          uniqueItems: true
          items:
            type: string
            enum:
              - explicit_request
              - unsupported_answer
              - keywords
              - negative_feedback
              - inactivity
              - custom
        triggers:
          type: object
          additionalProperties: false
          properties:
            explicit_request:
              $ref: '#/components/schemas/AgentHandoffTriggerToggle'
            unsupported_answer:
              $ref: '#/components/schemas/AgentHandoffTriggerToggle'
            negative_feedback:
              $ref: '#/components/schemas/AgentHandoffTriggerToggle'
            keywords:
              allOf:
                - $ref: '#/components/schemas/AgentHandoffTriggerToggle'
                - type: object
                  properties:
                    values:
                      type: array
                      maxItems: 20
                      uniqueItems: true
                      items:
                        type: string
                        maxLength: 80
            inactivity:
              allOf:
                - $ref: '#/components/schemas/AgentHandoffTriggerToggle'
                - type: object
                  properties:
                    minutes:
                      type: integer
                      minimum: 5
                      maximum: 1440
            custom:
              allOf:
                - $ref: '#/components/schemas/AgentHandoffTriggerToggle'
                - type: object
                  properties:
                    conditions:
                      type: array
                      maxItems: 20
                      items:
                        $ref: '#/components/schemas/AgentHandoffCondition'
        human_profile:
          type: object
          additionalProperties: false
          properties:
            name:
              type:
                - string
                - 'null'
              maxLength: 120
            role:
              type:
                - string
                - 'null'
              maxLength: 120
            bio:
              type:
                - string
                - 'null'
              maxLength: 500
        contact_app_ids:
          type: array
          maxItems: 10
          uniqueItems: true
          items:
            type: string
            format: uuid
    AgentAutomationRule:
      type: object
      additionalProperties: false
      required:
        - id
        - enabled
        - trigger_type
        - trigger_config
        - conditions
        - outcome_type
        - outcome_config
        - position
        - rate_limit_seconds
        - once_per_conversation
      properties:
        id:
          type: string
          format: uuid
        title:
          type:
            - string
            - 'null'
          maxLength: 120
        enabled:
          type: boolean
        trigger_type:
          type: string
          enum:
            - semantic_intent
            - keywords
            - unsupported_answer
            - handoff_state
            - conversation_stage
            - context
        trigger_config:
          type: object
          additionalProperties: true
        conditions:
          type: object
          additionalProperties: false
          properties:
            page_ids:
              type: array
              maxItems: 25
              uniqueItems: true
              items:
                type: string
                format: uuid
            button_ids:
              type: array
              maxItems: 25
              uniqueItems: true
              items:
                type: string
                format: uuid
            app_ids:
              type: array
              maxItems: 25
              uniqueItems: true
              items:
                type: string
                format: uuid
            stage:
              type: string
              enum:
                - any
                - first_message
                - engaged
                - returning
            handoff_state:
              type: string
              enum:
                - any
                - none
                - offered
                - waiting_for_human
                - human_joined
        outcome_type:
          type: string
          enum:
            - suggest_reply
            - open_app
            - show_popup
            - collect_contact
            - request_human
            - propose_capability
        outcome_config:
          type: object
          additionalProperties: true
          description: >-
            Outcome-specific, tenant-validated configuration. Proposal input
            fields must match the selected capability schema.
        position:
          type: integer
          minimum: 1
          maximum: 30
        rate_limit_seconds:
          type: integer
          minimum: 5
          maximum: 86400
        once_per_conversation:
          type: boolean
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    PublicAgentPresentation:
      type: object
      required:
        - welcome_message
        - suggested_replies
        - footer
        - appearance
        - sources
      properties:
        welcome_message:
          type: string
        suggested_replies:
          type: array
          maxItems: 6
          items:
            $ref: '#/components/schemas/PublicSuggestedReply'
        footer:
          type: object
          required:
            - enabled
            - html
            - text
          properties:
            enabled:
              type: boolean
            html:
              type:
                - string
                - 'null'
              description: Sanitized display HTML.
            text:
              type:
                - string
                - 'null'
              description: Plain-text equivalent for non-HTML clients.
        appearance:
          $ref: '#/components/schemas/PublicAgentAppearance'
        sources:
          type: object
          required:
            - welcome_message
            - suggested_replies
            - footer
            - appearance
          properties:
            welcome_message:
              type: string
              enum:
                - agent
                - assignment
            suggested_replies:
              type: string
              enum:
                - agent
                - assignment
            footer:
              type: string
              enum:
                - agent
                - assignment
            appearance:
              type: string
              enum:
                - legacy
                - agent
    AgentProtocolCatalog:
      type: object
      required:
        - version
        - states
        - protocols
        - differences
      properties:
        version:
          type: string
          enum:
            - '2026-08-05'
        states:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        protocols:
          type: object
          additionalProperties: true
        differences:
          type: object
          additionalProperties: true
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - code
        - detail
        - resolution
        - instance
        - request_id
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: Stable machine-readable error code.
        detail:
          type: string
        resolution:
          type: string
          description: Safe next step an agent or developer can take.
        instance:
          type: string
        request_id:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    AgentHandoffTriggerToggle:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
    AgentHandoffCondition:
      type: object
      additionalProperties: false
      required:
        - source
        - operator
        - value
      properties:
        id:
          type: string
          format: uuid
        label:
          type:
            - string
            - 'null'
          maxLength: 120
        source:
          type: string
          enum:
            - visitor_message
            - assistant_answer
        operator:
          type: string
          enum:
            - contains
            - equals
        value:
          type: string
          maxLength: 160
        enabled:
          type: boolean
          default: true
    PublicSuggestedReply:
      type: object
      description: >-
        Safe visitor-facing shortcut. The server-owned message and analytics
        label are intentionally omitted.
      required:
        - id
        - label
        - featured
        - operation
        - kind
        - action
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
          maxLength: 120
        featured:
          type: boolean
        operation:
          type: string
          enum:
            - message
            - request_human
        kind:
          type: string
        action:
          $ref: '#/components/schemas/SuggestedReplyAction'
    PublicAgentAppearance:
      type: object
      required:
        - theme
        - accent
        - avatar
        - caption
        - header_pattern
        - show_powered_by
        - tokens
        - source
      description: >-
        Presentation-only Agent defaults. Values are bounded presets and safe
        color tokens; placement and session policy remain canonical
        ContactButton settings.
      properties:
        theme:
          type: string
          enum:
            - light
            - light_accent
            - light_soft
            - dark
        accent:
          type: string
          enum:
            - inherit
            - indigo
            - blue
            - green
            - orange
            - rose
            - graphite
        avatar:
          type: string
          enum:
            - initials
            - sparkles
            - support
            - sales
        caption:
          type: string
          maxLength: 160
        header_pattern:
          type: boolean
        show_powered_by:
          type: boolean
        source:
          type: string
          enum:
            - legacy
            - agent
        tokens:
          type: object
          required:
            - primary
            - secondary
            - ink
            - muted
            - line
            - surface
            - panel
            - page_start
            - page_end
            - assistant
          additionalProperties: false
          properties:
            primary:
              $ref: '#/components/schemas/SafeHexColor'
            secondary:
              $ref: '#/components/schemas/SafeHexColor'
            ink:
              $ref: '#/components/schemas/SafeHexColor'
            muted:
              $ref: '#/components/schemas/SafeHexColor'
            line:
              $ref: '#/components/schemas/SafeHexColor'
            surface:
              $ref: '#/components/schemas/SafeHexColor'
            panel:
              $ref: '#/components/schemas/SafeHexColor'
            page_start:
              $ref: '#/components/schemas/SafeHexColor'
            page_end:
              $ref: '#/components/schemas/SafeHexColor'
            assistant:
              $ref: '#/components/schemas/SafeHexColor'
    SuggestedReplyAction:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - native_chat
            - request_human
            - url
            - app_widget
            - popup
        target:
          type:
            - string
            - 'null'
          description: >-
            An http(s), tel, or mailto URL; an installed app public ID; or a
            popup external ID, depending on type.
        new_tab:
          type: boolean
          default: false
          description: Applies only to http(s) URL actions.
    SafeHexColor:
      type: string
      pattern: ^#[0-9a-fA-F]{6}$
  responses:
    Problem:
      description: RFC 9457-style problem details.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum personal access token or OAuth 2.0 access token
      description: >
        A Contact Button scoped bearer key. Send `Authorization: Bearer
        <token>`.

        Token abilities are enforced independently of workspace membership; both
        checks must pass.

        Interactive MCP clients use registered OAuth applications, Authorization
        Code + PKCE,

        audience-bound tokens, and explicit workspace grants. Personal Sanctum
        tokens remain supported.
      x-contact-button-token-abilities:
        workspaces:read: Read workspaces, teams, domains, settings, and connections.
        workspaces:write: >-
          Create and manage workspaces, teams, domains, settings, and
          connections.
        content:read: Read buttons, forms, lists, pages, booking types, and knowledge.
        content:write: Create, update, publish, and remove content.
        engagements:read: >-
          Read submissions, subscribers, bookings, callbacks, calls, reviews,
          and conversations.
        engagements:manage: Reply to and manage engagement records.
        actions:request: Request protected actions that can still require human confirmation.

````