> ## 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/agents/{id}

> Get one agent whole: goal, prompt sections with their text, channels, tools and knowledge nodes.

Returns one agent with everything [the list endpoint](/dev/endpoints/agents-list) leaves out: its goal, the sections of its prompt **with their text**, the channels it answers on, the tools it may call and the knowledge nodes it can search.

One call is enough. In the block model this replaced, the text lived somewhere else and reading a prompt took three calls; a section belongs to its agent, so it comes back here.

## Endpoint

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

## Required scope

`agents:read`

## Headers

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

## Path parameters

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

## Example request

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0 \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

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

  ```python Python theme={"system"}
  import os, requests

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

## Response

### 200 OK

```json theme={"system"}
{
  "agent": {
    "_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "name": "Recepción",
    "description": "Atiende reservas y consultas de horario",
    "model": "gpt-5",
    "language": "es-CL",
    "timezone": "America/Santiago",
    "goal": { "type": "appointment_management", "instructions": null },
    "prompts": [
      {
        "section": "business_context",
        "label": null,
        "markdown": "# Quiénes somos\n\nBarbería en Providencia."
      },
      {
        "section": "agent_limits",
        "label": null,
        "markdown": "Los precios los das del catálogo."
      }
    ],
    "channels": ["whatsapp"],
    "reengagement": { "enabled": true, "max_attempts": 2 },
    "tools": ["6650cccc3333dddd4444eeee"],
    "knowledge_node_ids": ["6650dddd4444eeee5555ffff"],
    "voice_response_enabled": false,
    "is_active": true,
    "created_at": "2026-07-20T14:02:11.870Z",
    "updated_at": "2026-08-14T18:21:04.112Z"
  }
}
```

### 401 Unauthorized

Missing, invalid, revoked, or expired token.

### 403 Forbidden

The token does not have the `agents:read` scope.

### 404 Not Found

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

### 502 Bad Gateway

The agent service is unreachable.

## Operational notes

* **`prompts` carries the text.** What each section is for comes from [the catalogue](/dev/endpoints/prompt-types-list); the order is the order they take in the assembled prompt.
* **A section that was never written is absent**, not empty. There is no placeholder row per section type.
* **`goal.type` decides which tools the agent can actually use**, beyond the ids in `tools`. Changing it changes the agent's capabilities, not just a label.
* **`tools` and `knowledge_node_ids` are ids into company-level collections.** Deleting the agent leaves them alone.
* **This endpoint returns inactive agents too**, unlike the list. `is_active: false` means the agent does not answer, but its configuration is intact.
* **404 covers the cross-project case.** An agent that belongs to another project of the same company reads as not found, not as forbidden — the project of the token is part of its identity.
* **`company`, `project`, `metadata` and `created_by` are never returned.** The first two are implied by the token, the third has no published schema, and the fourth is an internal user id.


## OpenAPI

````yaml GET /v1/agents/{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/agents/{id}:
    get:
      tags:
        - agents
      summary: Obtener un agente
      description: >-
        Devuelve el agente con su modelo, sus nodos de conocimiento y las
        referencias ordenadas a los bloques que arman su prompt. Las referencias
        solo traen ids: la metadata de cada bloque se lee en GET
        /v1/agents/{id}/blocks.
      operationId: PublicAgentsController_get
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentEnvelopeDto'
      security:
        - PAT: []
components:
  schemas:
    PublicAgentEnvelopeDto:
      type: object
      properties:
        agent:
          $ref: '#/components/schemas/PublicAgentDto'
      required:
        - agent
    PublicAgentDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        avatar_url:
          type: string
        model:
          type: string
        voice_response_enabled:
          type: boolean
          description: Indica si la respuesta de voz está habilitada.
        created_at:
          type: string
      required:
        - id
        - name
        - model
        - voice_response_enabled
  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`.

````