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

# HTTP API / API HTTP

> OpenAgno runtime endpoints, including tenant provisioning, knowledge operations, admin routes, and AgentOS-native routes.

Typical base URL: `http://localhost:8000` (adjust host and port in deployment).

## English

### OpenAgno custom routes

| Metodo | Ruta                       | Descripcion                                              |
| ------ | -------------------------- | -------------------------------------------------------- |
| `GET`  | `/admin/health`            | Estado del runtime, agentes, canales, modelo y scheduler |
| `POST` | `/admin/reload`            | Solicitar reload al supervisor                           |
| `POST` | `/admin/fallback/activate` | Activar fallback manualmente                             |
| `POST` | `/admin/fallback/restore`  | Restaurar modelo principal                               |

These routes are rate-limited. If you expose them in production, protect them behind private networking or a reverse proxy.

### Knowledge routes

| Metodo   | Ruta                     | Descripcion        |
| -------- | ------------------------ | ------------------ |
| `POST`   | `/knowledge/upload`      | Subir documento    |
| `POST`   | `/knowledge/ingest-urls` | Ingestar URLs      |
| `GET`    | `/knowledge/list`        | Listar documentos  |
| `DELETE` | `/knowledge/{doc_name}`  | Eliminar documento |
| `POST`   | `/knowledge/search`      | Busqueda semantica |

If you send `X-Tenant-ID`, these routes become tenant-aware and use Agno-native knowledge isolation.

If you define `OPENAGNO_API_KEY`, these routes require the `X-API-Key` header.

### Tenant provisioning routes

| Method   | Path                                          | Description                                         |
| -------- | --------------------------------------------- | --------------------------------------------------- |
| `GET`    | `/tenants`                                    | List tenants                                        |
| `POST`   | `/tenants`                                    | Create a tenant and provision its workspace         |
| `GET`    | `/tenants/{tenant_id}`                        | Read tenant metadata                                |
| `PATCH`  | `/tenants/{tenant_id}`                        | Update plan, limits, slug, or workspace config      |
| `DELETE` | `/tenants/{tenant_id}`                        | Soft-deactivate a tenant                            |
| `GET`    | `/tenants/{tenant_id}/workspace`              | Read the tenant workspace config                    |
| `PUT`    | `/tenants/{tenant_id}/workspace`              | Update the tenant workspace config                  |
| `POST`   | `/tenants/{tenant_id}/agents/{agent_id}/runs` | Run an agent with tenant-scoped `knowledge_filters` |

### WhatsApp QR

| Metodo | Ruta                     | Descripcion                      |
| ------ | ------------------------ | -------------------------------- |
| `GET`  | `/whatsapp-qr/status`    | Estado del bridge QR             |
| `GET`  | `/whatsapp-qr/code`      | Pagina HTML con QR               |
| `GET`  | `/whatsapp-qr/code/json` | QR como JSON                     |
| `POST` | `/whatsapp-qr/incoming`  | Mensajes entrantes del bridge QR |

### WhatsApp Cloud API

| Metodo | Ruta                | Descripcion                                |
| ------ | ------------------- | ------------------------------------------ |
| `GET`  | `/whatsapp/webhook` | Verificacion de webhook con Meta           |
| `POST` | `/whatsapp/webhook` | Recepcion de eventos de WhatsApp Cloud API |

### AgentOS-native routes

The runtime also exposes native AgentOS routes. The most relevant operational groups are:

| Grupo             | Rutas principales                                                            |
| ----------------- | ---------------------------------------------------------------------------- |
| Agentes           | `/agents`, `/agents/{agent_id}/runs`                                         |
| Teams             | `/teams`, `/teams/{team_id}/runs`                                            |
| Sesiones          | `/sessions`, `/sessions/{session_id}`, `/sessions/{session_id}/runs`         |
| Memorias          | `/memories`, `/memory_topics`, `/optimize-memories`                          |
| Schedules         | `/schedules`, `/schedules/{schedule_id}`, `/schedules/{schedule_id}/trigger` |
| Registry / config | `/registry`, `/config`, `/components`, `/models`                             |
| Observabilidad    | `/health`, `/metrics`, `/traces`, `/eval-runs`                               |

### Generated documentation

* `/docs`
* `/redoc`
* `/openapi.json`

### Example

Health check:

```bash theme={null}
curl http://127.0.0.1:8000/admin/health
```

Busqueda custom de knowledge:

```bash theme={null}
curl -X POST http://127.0.0.1:8000/knowledge/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"OpenAgno","max_results":3}'
```

Tenant-aware run:

```bash theme={null}
curl -X POST http://127.0.0.1:8000/tenants/acme/agents/agnobot-main/runs \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: change-me' \
  -d '{"message":"Summarize my tenant docs","user_id":"demo"}'
```

## Español

El runtime también expone rutas custom y rutas nativas de AgentOS. La principal novedad de esta fase es la capa `/tenants/*`, que aprovisiona workspaces por tenant y ejecuta agentes con `knowledge_filters` tenant-aware sobre Agno.

Para seguridad, rate limit y firma de WhatsApp, revisa [Seguridad](/security).