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

# POST /v1/knowledge/assignments

> Assign knowledge base nodes to all of an assistant's workers.

Associates one or more knowledge base nodes with an assistant. The assignment propagates to **all of the assistant's workers** (except `supervisor` workers), adding the given `node_id` values to their list of accessible knowledge. The operation is idempotent: if a node was already assigned, it isn't duplicated.

To list available assistants use [`GET /v1/assistants`](/dev/endpoints/assistants-list). To get validated `node_id` values for your folders and documents use [`GET /v1/knowledge/tree`](/dev/endpoints/knowledge-tree).

After the assignment, a reindex is enqueued to refresh the workers' cached embeddings.

## Endpoint

```
POST https://api.keebai.com/v1/knowledge/assignments
```

## Required scope

`knowledge:assign`

## Headers

| Header          | Required | Value                    |
| --------------- | -------- | ------------------------ |
| `Authorization` | Yes      | `Bearer kbai_pk_<token>` |
| `Content-Type`  | Yes      | `application/json`       |

## Body

| Field          | Type       | Required | Description                                                       |
| -------------- | ---------- | -------- | ----------------------------------------------------------------- |
| `assistant_id` | `string`   | Yes      | `ObjectId` of the target assistant.                               |
| `node_ids`     | `string[]` | Yes      | `ObjectId` values of the nodes to assign. Minimum 1, maximum 200. |

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.keebai.com/v1/knowledge/assignments \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": "65f3a1b2c3d4e5f6a7b8c9aa",
      "node_ids": [
        "65f3a1b2c3d4e5f6a7b8c9d3",
        "65f3a1b2c3d4e5f6a7b8c9d4"
      ]
    }'
  ```

  ```js JavaScript theme={null}
  const resp = await fetch("https://api.keebai.com/v1/knowledge/assignments", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      assistant_id: "65f3a1b2c3d4e5f6a7b8c9aa",
      node_ids: ["65f3a1b2c3d4e5f6a7b8c9d3", "65f3a1b2c3d4e5f6a7b8c9d4"],
    }),
  });
  const { workers_updated } = await resp.json();
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      "https://api.keebai.com/v1/knowledge/assignments",
      headers={
          "Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}",
          "Content-Type": "application/json",
      },
      json={
          "assistant_id": "65f3a1b2c3d4e5f6a7b8c9aa",
          "node_ids": ["65f3a1b2c3d4e5f6a7b8c9d3", "65f3a1b2c3d4e5f6a7b8c9d4"],
      },
      timeout=15,
  )
  resp.raise_for_status()
  print(resp.json()["workers_updated"])
  ```
</CodeGroup>

## Response

### 200 OK

```json theme={null}
{
  "workers_updated": 3
}
```

| Field             | Type     | Description                                                                                                      |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `workers_updated` | `number` | Number of assistant workers that received the assignment. `0` means the assistant has no non-supervisor workers. |

### 400 / 401 / 403 / 404 / 429

* `400 BAD_REQUEST`: `assistant_id` or `node_ids` with invalid format, or `node_ids` empty.
* `403 FORBIDDEN` with `code: INSUFFICIENT_SCOPE`: the PAT doesn't have `knowledge:assign`.
* `404 NOT_FOUND`: the `assistant_id` doesn't exist, or one or more `node_ids` don't belong to your company.


## OpenAPI

````yaml POST /v1/knowledge/assignments
openapi: 3.0.0
info:
  title: Keebai Public API
  description: Superficie pública REST autenticada con Personal Access Tokens (PAT).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.keebai.com
    description: Production
security: []
tags: []
paths:
  /v1/knowledge/assignments:
    post:
      tags:
        - knowledge
      summary: >-
        Asignar nodos de la base de conocimientos a todos los workers de un
        asistente.
      operationId: PublicKnowledgeController_assign
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignKnowledgeDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignKnowledgeResponseDto'
      security:
        - PAT: []
components:
  schemas:
    AssignKnowledgeDto:
      type: object
      properties:
        assistant_id:
          type: string
          description: ObjectId del asistente destino.
        node_ids:
          description: ObjectIds de los nodos a asignar a todos los workers del asistente.
          type: array
          items:
            type: string
      required:
        - assistant_id
        - node_ids
    AssignKnowledgeResponseDto:
      type: object
      properties:
        workers_updated:
          type: number
      required:
        - workers_updated
  securitySchemes:
    PAT:
      scheme: bearer
      bearerFormat: kbai_pk_<hex>
      type: http
      description: >-
        Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal
        con permiso `developer.manage_tokens`.

````