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

# Attach or scope an agent knowledge source

> Attach a Brain source to the agent, or change its scope if it is already attached. Idempotent: sending the same scope twice reports `already_present`.

`config: null` attaches the whole source. To narrow it, send `exclusions` (everything except these), or `mode: include_only` with `inclusions` (only these). Item IDs come from `GET /brain/sources/{connector_id}/files`.

The source must be readable by the caller and live in the agent's workspace (personal sources on personal agents, team sources on team agents).




## OpenAPI

````yaml put /agents/{agent_id}/knowledge-sources/{connector_id}
openapi: 3.0.0
info:
  title: Public API
  version: 1.0.0
servers:
  - url: https://api.gumloop.com/api/v1
security: []
paths:
  /agents/{agent_id}/knowledge-sources/{connector_id}:
    put:
      tags:
        - Agents
      summary: Attach or scope an agent knowledge source
      description: >
        Attach a Brain source to the agent, or change its scope if it is already
        attached. Idempotent: sending the same scope twice reports
        `already_present`.


        `config: null` attaches the whole source. To narrow it, send
        `exclusions` (everything except these), or `mode: include_only` with
        `inclusions` (only these). Item IDs come from `GET
        /brain/sources/{connector_id}/files`.


        The source must be readable by the caller and live in the agent's
        workspace (personal sources on personal agents, team sources on team
        agents).
      operationId: attachAgentKnowledgeSource
      parameters:
        - in: path
          name: agent_id
          required: true
          schema:
            type: string
          description: ID of a custom agent.
        - in: path
          name: connector_id
          required: true
          schema:
            type: string
          description: Brain source ID from `GET /brain/sources`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  $ref: '#/components/schemas/KnowledgeSourceScope'
            examples:
              whole:
                summary: Whole source
                value:
                  config: null
              folder:
                summary: One folder only
                value:
                  config:
                    mode: include_only
                    inclusions:
                      - type: container
                        id: folder_91ab
      responses:
        '200':
          description: The attachment after the change.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                  knowledge_source:
                    $ref: '#/components/schemas/AgentKnowledgeSource'
                  outcome:
                    type: string
                    enum:
                      - attached
                      - updated
                      - already_present
        '400':
          description: >-
            Invalid scope (`knowledge_source_invalid_config`), source in another
            workspace (`knowledge_source_scope_mismatch`), or a platform agent
            (`agent_not_customizable`).
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: >-
            Forbidden — the caller lacks update access, cannot read the source,
            or Brain is restricted for their role.
        '404':
          description: Agent or source not found (`knowledge_source_not_found`).
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            curl -X PUT
            'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/knowledge-sources/PFqdAMir8PA2Xc6qcszSN9'
            \
              -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"config": {"mode": "include_only", "inclusions": [{"type": "container", "id": "folder_91ab"}]}}'
        - lang: python
          label: Python
          source: >
            from gumloop import Gumloop


            client = Gumloop(access_token="YOUR_ACCESS_TOKEN")


            # Whole source

            client.agents.attach_knowledge_source("abc123DEFghiJKL",
            "PFqdAMir8PA2Xc6qcszSN9")


            # One folder only

            client.agents.attach_knowledge_source(
                "abc123DEFghiJKL",
                "PFqdAMir8PA2Xc6qcszSN9",
                config={"mode": "include_only", "inclusions": [{"type": "container", "id": "folder_91ab"}]},
            )
components:
  schemas:
    KnowledgeSourceScope:
      type: object
      nullable: true
      description: >-
        Which part of a Brain source the agent reads. `null` is the whole
        source. Without `mode`, everything except `exclusions`; with
        `include_only`, only `inclusions`.
      properties:
        mode:
          type: string
          enum:
            - denylist
            - include_only
        inclusions:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeScopeRule'
        exclusions:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeScopeRule'
    AgentKnowledgeSource:
      type: object
      properties:
        connector_id:
          type: string
          description: Brain source ID, as returned by `GET /brain/sources`.
          example: PFqdAMir8PA2Xc6qcszSN9
        config:
          $ref: '#/components/schemas/KnowledgeSourceScope'
    KnowledgeScopeRule:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - container
            - document
          description: '`container` is a folder, channel or similar; `document` is one file.'
        id:
          type: string
          description: >-
            The item's ID in the source, as returned by `GET
            /brain/sources/{connector_id}/files`.
        name:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A personal API key or an [OAuth 2.0](/api-reference/oauth) access token.
        Personal API keys also require the `x-auth-key` header with your user
        ID.

````