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

# GET /v1/blocks/{id}

> Get one block's metadata: type, family, name, and which version is current.

Returns one block's metadata. **No content**: a block document holds none. The text lives in its versions, which is why [reading it](/dev/endpoints/blocks-content-get) is a separate call.

Use this when you have a `block_id` from an assistant's `blocks` array and want to know what it is before deciding whether to read or edit it.

## Endpoint

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

## Required scope

`assistants:read`

## 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 https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js JavaScript theme={null}
  const resp = await fetch(
    "https://api.keebai.com/v1/blocks/6650bbbb2222cccc3333dddd",
    { headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` } },
  );
  const { block } = await resp.json();

  if (!block.content_writable) {
    // Configure this one in the portal.
  }
  ```

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

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

## Response

### 200 OK

```json theme={null}
{
  "block": {
    "_id": "6650bbbb2222cccc3333dddd",
    "type": "steps",
    "family": "instructions",
    "name": "Reserva",
    "current_version_id": "6650ffff4444aaaa5555bbbb",
    "is_archived": false,
    "content_writable": true,
    "created_at": "2026-07-20T14:02:11.870Z",
    "updated_at": "2026-07-26T09:44:03.512Z"
  }
}
```

### 401 Unauthorized

Missing, invalid, revoked, or expired token.

### 403 Forbidden

The token does not have the `assistants:read` 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

* **`family` is derived from `type` and is read-only.** It decides which section of the composed prompt the block lands in — identity first, then instructions, then information — and is never accepted on a write.
* **`current_version_id` is the pointer to follow** for the content. `null` means the block has never been saved.
* **This endpoint returns archived blocks.** `is_archived: true` only means it is hidden from [the catalogue listing](/dev/endpoints/blocks-list); it can still be attached and still renders.
* **A block from another project of the same company is a `404`.** Project is part of a block's identity, so cross-project reads are indistinguishable from a missing id.
* **`company` and `project` are never returned.** Both are implied by the token.


## OpenAPI

````yaml GET /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}:
    get:
      tags:
        - blocks
      summary: Obtener la metadata de un bloque
      description: >-
        Tipo, familia, nombre y cual es su version vigente. Sin contenido: para
        eso esta GET /v1/blocks/{id}/content.
      operationId: PublicBlocksController_get
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicBlockEnvelopeDto'
      security:
        - PAT: []
components:
  schemas:
    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`.

````