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

# DELETE /v1/blocks/{id}

> Archive a block. Nothing is destroyed, and assistants that reference it keep using it.

Archives the block. Despite the verb, **nothing is deleted**: the block, its whole version history and every assistant reference to it survive. It is the same write as [`PATCH`ing `is_archived: true`](/dev/endpoints/blocks-update), and it is undone the same way.

<Warning>
  **Archiving does not stop a block from working.** An archived block that is still attached to an assistant keeps rendering into that assistant's prompt. Archiving hides it from [the catalogue](/dev/endpoints/blocks-list); it does not switch it off. To take it out of an assistant, [detach it](/dev/endpoints/assistants-block-detach).
</Warning>

## Endpoint

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

## Required scope

`assistants:write`

## Headers

| Header          | Required | Value                    |
| --------------- | -------- | ------------------------ |
| `Authorization` | Yes      | `Bearer kbai_pk_<token>` |

## Path parameters

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

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js JavaScript theme={null}
  const base = "https://api.keebai.com/v1";
  const auth = { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` };

  // Retiring a block properly is two calls: detach, then archive.
  await fetch(`${base}/assistants/6650a1b2c3d4e5f6a7b8c9d0/blocks/6650bbbb2222cccc3333dddd`, {
    method: "DELETE",
    headers: auth,
  });
  await fetch(`${base}/blocks/6650bbbb2222cccc3333dddd`, {
    method: "DELETE",
    headers: auth,
  });
  ```

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

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

## Response

### 204 No Content

Archived. No body.

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

* **Retiring a block is two calls.** [Detach it from each assistant](/dev/endpoints/assistants-block-detach), then archive it. Archiving alone changes nothing about what the assistants say.
* **Archiving an already-archived block succeeds**, so a retry is safe.
* **Undo with [`PATCH`](/dev/endpoints/blocks-update) and `is_archived: false`.** There is no separate unarchive endpoint.
* **There is no hard delete in this API.** Neither blocks nor versions can be destroyed through the public surface; the worst you can do is archive.
* **Archived blocks are still readable by id** with [`GET /v1/blocks/{id}`](/dev/endpoints/blocks-get) and appear in the catalogue when you pass `include_archived=true`.


## OpenAPI

````yaml DELETE /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}:
    delete:
      tags:
        - blocks
      summary: Archivar un bloque
      description: >-
        Archiva el bloque, no lo borra: su historial sobrevive y se puede
        desarchivar. Los asistentes que lo tengan adjunto lo siguen usando.
      operationId: PublicBlocksController_archive
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '204':
          description: ''
      security:
        - PAT: []
components:
  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`.

````