---
title: "REST API do OpenClaw — Documentação"
url: "https://openclaw.ia.br/api/rest/"
markdown_url: "https://openclaw.ia.br/api/rest.MD"
description: "Documentação completa da API REST do OpenClaw. Envie mensagens, consulte status e integre com qualquer linguagem via HTTP."
date: ""
author: ""
---

# REST API do OpenClaw — Documentação

Documentação completa da API REST do OpenClaw. Envie mensagens, consulte status e integre com qualquer linguagem via HTTP.


# REST API do OpenClaw

A API REST permite integrar o OpenClaw com qualquer sistema que faça requisições HTTP. Ideal para backends, scripts e automações.

##  Base URL

```
http://localhost:18789
```

**Nota:** A porta pode ser diferente se você alterou em [config](/api/config/).

##  Autenticação

Se configurado, envie o token no header:

```http
Authorization: Bearer seu_token_aqui
```

Para configurar autenticação, adicione em `config.yaml`:

```yaml
gateway:
  auth:
    token: "seu_token_secreto"
```

##  Endpoints

### POST /api/message — Enviar Mensagem

Envia uma mensagem para um canal específico.

**Request:**

```http
POST /api/message
Content-Type: application/json

{
  "channel": "telegram",
  "to": "123456789",
  "message": "Olá! Esta é uma mensagem via API."
}
```

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `channel` | string | Sim | Canal de destino (telegram, whatsapp, discord) |
| `to` | string | Sim | ID do destinatário |
| `message` | string | Sim | Conteúdo da mensagem |

**Response (200 OK):**

```json
{
  "success": true,
  "messageId": "abc123"
}
```

**Exemplo com cURL:**

```bash
curl -X POST http://localhost:18789/api/message \
  -H "Content-Type: application/json" \
  -d '{"channel": "telegram", "to": "123456789", "message": "Teste!"}'
```

### GET /api/status — Status do Sistema

Retorna o status geral do gateway e canais.

**Request:**

```http
GET /api/status
```

**Response:**

```json
{
  "status": "running",
  "uptime": 3600,
  "channels": {
    "telegram": { "status": "connected", "lastMessage": "2025-01-15T10:30:00Z" },
    "whatsapp": { "status": "connected", "lastMessage": "2025-01-15T09:15:00Z" }
  },
  "memory": {
    "used": 156000000,
    "total": 512000000
  }
}
```

**Útil para:** Monitoramento, health checks, dashboards.

### GET /api/sessions — Listar Sessões

Lista todas as sessões de conversa ativas.

**Request:**

```http
GET /api/sessions
```

**Response:**

```json
{
  "sessions": [
    {
      "key": "telegram:123456789",
      "lastActivity": "2025-01-15T10:30:00Z",
      "messageCount": 42
    }
  ]
}
```

### GET /api/sessions/:key/history — Histórico de Sessão

Retorna o histórico de uma sessão específica.

**Request:**

```http
GET /api/sessions/telegram:123456789/history
```

**Query Parameters:**

| Param | Tipo | Padrão | Descrição |
|-------|------|--------|-----------|
| `limit` | number | 50 | Quantidade de mensagens |
| `offset` | number | 0 | Pular N mensagens |

**Response:**

```json
{
  "messages": [
    { "role": "user", "content": "Olá!", "timestamp": "..." },
    { "role": "assistant", "content": "Oi! Como posso ajudar?", "timestamp": "..." }
  ]
}
```

### GET /health — Health Check

Endpoint simples para verificar se o gateway está ativo.

**Request:**

```http
GET /health
```

**Response (200 OK):**

```json
{
  "status": "ok"
}
```

**Útil para:** Load balancers, Kubernetes probes, monitoramento.

##  Webhooks (Receber Eventos)

Configure endpoints para receber eventos externos (ex: GitHub, Stripe).

**Configuração em config.yaml:**

```yaml
webhooks:
  - path: "/webhook/github"
    handler: "github-events"
    secret: "seu_webhook_secret"
```

**Como funciona:**

1. Serviço externo envia POST para `http://seu-servidor:18789/webhook/github`
2. OpenClaw valida o payload
3. Handler processa e pode notificar você

##  Exemplos de Integração

### Python

```python
import requests

response = requests.post(
    "http://localhost:18789/api/message",
    json={
        "channel": "telegram",
        "to": "123456789",
        "message": "Mensagem via Python!"
    }
)
print(response.json())
```

### Node.js

```javascript
const response = await fetch("http://localhost:18789/api/message", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    channel: "telegram",
    to: "123456789",
    message: "Mensagem via Node.js!"
  })
});
console.log(await response.json());
```

### Bash (cURL)

```bash
curl -X GET http://localhost:18789/api/status | jq
```

##  Próximos Passos

- [WebSocket API](/api/websocket/) — Para streaming em tempo real
- [CLI Reference](/api/cli/) — Alternativa via linha de comando
- [Configuração](/api/config/) — Customize a API