> ## 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.

# PATCH /v1/blocks/{id}

> Rename a block or change its archived flag. Content is edited elsewhere.

Changes a block's name or archives it. These are the only two mutable fields on a block document — `type` and `family` are fixed at creation, and the content lives in versions.

To change what the block says, use [`PUT /v1/blocks/{id}/content`](/dev/endpoints/blocks-content-save).

## Endpoint

```
PATCH https://api.keebai.com/v1/blocks/{id}
```

## Required scope

`assistants:write`

## Headers

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

## Path parameters

| Parameter | Type     | Description              |
| --------- | -------- | ------------------------ |
| `id`      | `string` | `ObjectId` of the block. |

## Body

Both fields are optional; send at least one.

| Field         | Type      | Description                                                 |
| ------------- | --------- | ----------------------------------------------------------- |
| `name`        | `string`  | Up to 150 characters, non-empty.                            |
| `is_archived` | `boolean` | `true` hides it from the catalogue, `false` brings it back. |

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Reserva de turnos" }'
  ```

  ```js JavaScript theme={null}
  // Unarchive a block so it shows up in the catalogue again.
  const resp = await fetch(
    "https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd",
    {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ is_archived: false }),
    },
  );
  const { block } = await resp.json();
  ```

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

  resp = requests.patch(
      "https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd",
      headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
      json={"name": "Reserva de turnos"},
      timeout=10,
  )
  resp.raise_for_status()
  block = resp.json()["block"]
  ```
</CodeGroup>

## Response

### 200 OK

The block, same shape as [`GET /v1/blocks/{id}`](/dev/endpoints/blocks-get).

### 400 Bad Request

An empty or over-long `name`, or a property the endpoint does not accept — including `type`, `family` and `content`.

### 401 Unauthorized

Missing, invalid, revoked, or expired token.

### 403 Forbidden

The token does not have the `assistants:write` scope.

### 404 Not Found

No block with that id in the token's company and project.

### 502 Bad Gateway

The assistant service is unreachable.

## Operational notes

* **This works on all twelve types, including the read-only five.** Renaming and archiving do not touch content, so `product_info` and friends are editable here even though [saving their content](/dev/endpoints/blocks-content-save) is not.
* **`is_archived: false` is the undo for [`DELETE /v1/blocks/{id}`](/dev/endpoints/blocks-archive).** They write the same field.
* **Archiving does not detach.** Assistants referencing the block keep using it, and its content keeps rendering into their prompts. [Detach it](/dev/endpoints/assistants-block-detach) if that is what you meant.
* **`type` cannot be changed.** A block created as `steps` is a `steps` block forever; create a new one of the right type and move the content across.


## OpenAPI

````yaml PATCH /v1/blocks/{id}
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/blocks/{id}:
    patch:
      tags:
        - blocks
      summary: Renombrar o archivar un bloque
      description: Solo el nombre y el flag de archivado. El contenido no se edita por aca.
      operationId: PublicBlocksController_update
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicBlockUpdateDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicBlockEnvelopeDto'
      security:
        - PAT: []
components:
  schemas:
    PublicBlockUpdateDto:
      type: object
      properties:
        name:
          type: string
          maxLength: 150
        is_archived:
          type: boolean
          description: >-
            Archiva o desarchiva el bloque. Archivar no lo borra ni lo saca de
            los asistentes que lo tienen adjunto.
    PublicBlockEnvelopeDto:
      type: object
      properties:
        block:
          $ref: '#/components/schemas/PublicBlockDto'
      required:
        - block
    PublicBlockDto:
      type: object
      properties:
        _id:
          type: string
        type:
          type: string
          enum:
            - personification
            - objective
            - response_format
            - steps
            - cases_possible
            - do_not
            - product_info
            - store_info
            - reservation_info
            - tables_info
            - tags
            - response_policy
        family:
          type: string
          enum:
            - identity
            - instructions
            - information
          description: >-
            Se deriva del tipo y determina en que seccion del prompt entra el
            bloque. Es de solo lectura.
        name:
          type: string
        current_version_id:
          type: string
          nullable: true
          description: >-
            Version vigente del bloque. Su contenido se lee en GET
            /v1/blocks/{id}/content.
        is_archived:
          type: boolean
        content_writable:
          type: boolean
          description: >-
            Si el contenido de este bloque se puede editar por API. Los tipos de
            catalogo son de solo lectura porque su escritura depende de una
            sincronizacion de funciones que vive en el portal.
        created_at:
          type: string
        updated_at:
          type: string
      required:
        - _id
        - type
        - family
        - name
        - current_version_id
        - is_archived
        - content_writable
        - created_at
        - updated_at
  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`.

````