API de Computador Agente

Experimente no API Playground.

Base URL

https://api.rebyte.ai/v1

Autenticação

Cada requisição requer um cabeçalho API_KEY. Obtenha sua chave em Configurações > Chaves de API.

curl https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_your_key_here"

O nome do cabeçalho não diferencia maiúsculas de minúsculas. API_KEY, api-key e x-api-key funcionam.

---

Endpoints

Método	Caminho	Descrição
POST	/tasks	Criar uma tarefa
GET	/tasks	Listar tarefas
GET	/tasks/:id	Obter tarefa com status e histórico de prompts
POST	/tasks/:id/prompts	Enviar um prompt de acompanhamento
PATCH	/tasks/:id/visibility	Alterar visibilidade da tarefa
DELETE	/tasks/:id	Excluir (soft-delete) uma tarefa
GET	/tasks/:id/events	Stream SSE de eventos de execução
POST	/files	Obter uma URL de upload de arquivo assinado
POST	/webhooks	Registrar um webhook
GET	/webhooks	Listar webhooks
GET	/webhooks/:id	Obter detalhes do webhook
DELETE	/webhooks/:id	Excluir um webhook
Todos os caminhos são relativos à URL base (https://api.rebyte.ai/v1).

---

Tarefas

Criar Tarefa

POST /tasks

Cria uma nova tarefa. Por padrão, provisiona uma nova VM (Computador Agente). Passe workspaceId para executar a tarefa em um workspace existente — isso ignora o provisionamento e é significativamente mais rápido.

A chamada bloqueia até que a VM seja provisionada e o primeiro prompt seja enviado.

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Descrição da tarefa (máx. 100.000 caracteres)
executor	string	Não	claude (padrão), gemini, codex, opencode
model	string	Não	Nível do modelo para o executor. Veja Modelos.
workspaceId	string	Não	UUID de um workspace existente para reutilizar
files	object[]	Não	Arquivos de POST /files. Cada: {"id": "...", "filename": "..."}
skills	string[]	Não	Slugs de habilidades (ex: ["deep-research", "pdf"])
githubUrl	string	Não	Repositório GitHub no formato owner/repo
branchName	string	Não	Nome da branch (padrão: main)

curl -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a REST API with Express and add tests",
    "executor": "claude",
    "skills": ["deep-research"],
    "githubUrl": "your-org/your-repo"
  }'

Resposta (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "url": "https://app.rebyte.ai/run/550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "createdAt": "2026-01-28T12:00:00.000Z"
}

Salve o workspaceId da resposta para criar tarefas de acompanhamento no mesmo Computador Agente:

# Primeira tarefa -- provisiona uma nova VM
RESP=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d '{"prompt": "Set up the project"}')
WS_ID=$(echo $RESP | jq -r '.workspaceId')

# Segunda tarefa -- reutiliza a mesma VM (muito mais rápido)
curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Now add tests\", \"workspaceId\": \"$WS_ID\"}"

Modelos

Os modelos disponíveis dependem do executor:

Executor	Modelos Disponíveis	Padrão
claude	claude-sonnet-4.6, claude-opus-4.6, gemini-3.1-pro, gpt-5.3-codex, gpt-5.4, minimax-m2.7, kimi-k2.5, glm-5, gemini-3-flash	claude-sonnet-4.6
codex	gpt-5.4, gpt-5.3-codex	gpt-5.4
gemini	auto-gemini-3 (auto-routes between flash and pro)	auto-gemini-3
opencode	Same as claude	gemini-3.1-pro

Com BYOK (traga sua própria chave de API), apenas os modelos do provedor nativo do executor estão disponíveis (ex: executor claude com BYOK só obtém claude-sonnet-4.6 e claude-opus-4.6).

Listar Tarefas

GET /tasks?limit=50&offset=0

Retorna as tarefas criadas via API, ordenadas pela data de criação (mais recentes primeiro).

Parâmetro	Tipo	Padrão	Descrição
limit	number	50	Resultados por página (máx. 100)
offset	number	0	Offset de paginação

curl "https://api.rebyte.ai/v1/tasks?limit=10" \
  -H "API_KEY: rbk_xxx"

Resposta:

{
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://app.rebyte.ai/run/550e8400-...",
      "title": "Build REST API with Express",
      "executor": "claude",
      "model": "claude-sonnet-4.6",
      "createdAt": "2026-01-28T12:00:00.000000+00:00",
      "completedAt": "2026-01-28T12:05:00.000000+00:00"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Obter Tarefa

GET /tasks/:id

Retorna os detalhes completos da tarefa, incluindo histórico de prompts e status derivado.

curl https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

Resposta:

{
  "id": "550e8400-...",
  "url": "https://app.rebyte.ai/run/550e8400-...",
  "status": "running",
  "title": "Build REST API with Express",
  "executor": "claude",
  "model": "claude-sonnet-4.6",
  "createdAt": "2026-01-28T12:00:00.000000+00:00",
  "completedAt": null,
  "prompts": [
    {
      "id": "660e8400-...",
      "status": "running",
      "submittedAt": "2026-01-28T12:05:00.000000+00:00",
      "completedAt": null
    },
    {
      "id": "550e8400-...",
      "status": "succeeded",
      "submittedAt": "2026-01-28T12:00:01.000000+00:00",
      "completedAt": "2026-01-28T12:03:00.000000+00:00"
    }
  ]
}

O status da tarefa é derivado dos estados dos prompts:

Status	Condição
running	Qualquer prompt está pending ou running
completed	Todos os prompts são terminais, o último é succeeded
failed	Todos os prompts são terminais, o último é failed
canceled	Todos os prompts são terminais, o último é canceled

Enviar Acompanhamento

POST /tasks/:id/prompts

Envie um prompt de acompanhamento para uma tarefa em execução ou concluída. Se a VM estiver parada, ela é automaticamente retomada.

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Prompt de acompanhamento (máx. 100.000 caracteres)
skills	string[]	Não	Slugs de habilidades adicionais para este prompt

curl -X POST https://api.rebyte.ai/v1/tasks/550e8400-.../prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add authentication with JWT"}'

Resposta (201):

{
  "promptId": "770f9500-..."
}

Stream de Eventos (SSE)

GET /tasks/:id/events

Abre um stream de Server-Sent Events para o prompt mais recente da tarefa. Os eventos incluem saída do agente (stdout, stderr), chamadas de ferramentas e sinais de conclusão.

curl -N https://api.rebyte.ai/v1/tasks/550e8400-.../events \
  -H "API_KEY: rbk_xxx"

O stream emite dois tipos de evento:

• event — eventos de execução (saída do agente, chamadas de ferramentas)
• done — evento final com status de conclusão, então o stream se fecha

Alterar Visibilidade

PATCH /tasks/:id/visibility

Campo	Tipo	Obrigatório	Descrição
visibility	string	Sim	private, shared ou public

Nível	Quem pode visualizar
private	Apenas o proprietário da chave de API
shared	Todos os membros da organização (padrão)
public	Qualquer pessoa com o link (somente leitura)

curl -X PATCH https://api.rebyte.ai/v1/tasks/550e8400-.../visibility \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}'

Quando definido como public, a resposta inclui uma shareUrl para acesso não autenticado.

Excluir Tarefa

DELETE /tasks/:id

Exclui (soft-delete) a tarefa. Retorna 204 No Content.

curl -X DELETE https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

---

Arquivos

Faça upload de arquivos para anexar a tarefas. Usa um fluxo de URL assinado em duas etapas.

Passo 1: Obter URL de Upload

POST /files

Campo	Tipo	Obrigatório	Descrição
filename	string	Sim	Nome do arquivo (máx. 255 caracteres)
contentType	string	Não	Tipo MIME (padrão: application/octet-stream)

Resposta (201):

{
  "id": "550e8400-...",
  "filename": "data.csv",
  "uploadUrl": "https://storage.googleapis.com/...",
  "maxFileSize": 52428800
}

A URL de upload expira em 1 hora.

Passo 2: Fazer Upload do Arquivo

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv

Passo 3: Anexar à Tarefa

Passe id e filename do Passo 1 ao criar uma tarefa:

{
  "prompt": "Analyze the uploaded data",
  "files": [
    {"id": "550e8400-...", "filename": "data.csv"}
  ]
}

Os arquivos são automaticamente copiados para a VM da tarefa quando a execução começa.

---

Webhooks

Receba notificações HTTP POST quando eventos de tarefa ocorrerem. Webhooks são universais — eles são acionados para todas as tarefas em sua organização, sejam criadas via API, UI ou qualquer outro canal.

Eventos

Evento	Dispara quando
task.created	Uma nova tarefa é criada
task.running	O agente começa a executar
task.completed	A tarefa termina com sucesso
task.failed	A tarefa falha
task.canceled	A tarefa é cancelada pelo usuário

Criar Webhook

POST /webhooks

Campo	Tipo	Obrigatório	Descrição
url	string	Sim	URL do endpoint HTTPS
events	string[]	Sim	Eventos para assinar
description	string	Não	Rótulo legível por humanos (máx. 500 caracteres)
secret	string	Não	Segredo pré-compartilhado (máx. 500 caracteres). Quando definido, incluído como cabeçalho X-Webhook-Secret em cada entrega.

# Webhook sem segredo
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"]
  }'

# Webhook com segredo pré-compartilhado
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "my-shared-secret-value"
  }'

Resposta (201):

{
  "id": "880e8400-...",
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "task.failed"],
  "description": null,
  "hasSecret": true,
  "isActive": true,
  "createdAt": "2026-01-28T12:00:00.000Z",
  "lastTriggeredAt": null,
  "failureCount": 0
}

Notas de comportamento:

• URLs Duplicadas: registrar a mesma URL duas vezes retorna o webhook existente (idempotente)
• Limite: máximo de 3 webhooks por organização. O 4º retorna limit_exceeded.
• Armazenamento de Segredo: o valor do segredo nunca é retornado em nenhuma resposta. Apenas hasSecret: true/false é exposto.

Listar Webhooks

GET /webhooks

Retorna todos os webhooks da sua organização com informações de status (lastTriggeredAt, failureCount, isActive). Segredos nunca são expostos.

Obter Webhook

GET /webhooks/:id

Excluir Webhook

DELETE /webhooks/:id

Retorna 204 No Content. Webhooks excluídos param imediatamente de receber entregas.

Entrega

Quando um evento de tarefa corresponde aos eventos assinados de um webhook, Rebyte envia um HTTP POST para a URL do webhook.

Payload:

{
  "event": "task.completed",
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1706443200,
  "data": {
    "status": "succeeded",
    "taskUrl": "https://app.rebyte.ai/run/550e8400-...",
    "result": "Created CSV file with 10 Hacker News posts..."
  }
}

• status — status do prompt: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
• taskUrl — link direto para a tarefa na UI do Rebyte (sempre presente)
• result — texto de saída final da IA (presente em eventos terminais: task.completed, task.failed, task.canceled; ausente em task.created e task.running)

Chame GET /tasks/:id para obter os detalhes completos da tarefa, incluindo o histórico de prompts.

Cabeçalhos de entrega:

Cabeçalho	Sempre presente	Descrição
Content-Type	Sim	application/json
X-Webhook-Signature	Sim	Assinatura RSA-SHA256 codificada em Base64
X-Webhook-Timestamp	Sim	Timestamp Unix (segundos)
X-Webhook-Secret	Somente se o segredo estiver configurado	O valor do segredo pré-compartilhado que você definiu na criação

Timeout: as entregas expiram após 10 segundos.

Tratamento de falhas:

• A entrega é fire-and-forget — sem novas tentativas automáticas em caso de falha
• Respostas não-2xx incrementam failureCount
• Após 10 falhas consecutivas, o webhook é automaticamente desativado (isActive: false)
• Entregas bem-sucedidas redefinem failureCount para 0

Verificação de Assinatura

Cada entrega é assinada com o par de chaves RSA-2048 da sua organização, independentemente de um segredo pré-compartilhado estar configurado.

Como funciona:

1. Rebyte concatena {timestamp}.{body} (ex: 1706443200.{"event":"task.completed",...})
2. Assina a string com RSA-SHA256 usando a chave privada da sua organização
3. Envia a assinatura codificada em base64 em X-Webhook-Signature

Obtenha sua chave pública: entre em contato com o suporte ou recupere-a do painel do Rebyte. O par de chaves RSA-2048 é gerado automaticamente na primeira criação de webhook e persiste para a organização.

Exemplo de verificação (Node.js):

const crypto = require('crypto');

function verifyWebhook(rawBody, timestamp, signature, publicKey) {
  const payload = `${timestamp}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(payload);
  return verifier.verify(publicKey, signature, 'base64');
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // must be raw string, not parsed JSON
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhook(rawBody, timestamp, signature, PUBLIC_KEY)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log(`Task ${event.taskId}: ${event.event}`);
  res.status(200).send('OK');
});

Exemplo de verificação (Python):

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def verify_webhook(raw_body: str, timestamp: str, signature: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    payload = f"{timestamp}.{raw_body}".encode()
    try:
        public_key.verify(
            base64.b64decode(signature),
            payload,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception:
        return False

Segurança em duas camadas

Webhooks suportam dois métodos de verificação independentes que podem ser usados juntos:

Método	Cabeçalho	Como funciona	Caso de uso
Assinatura RSA	X-Webhook-Signature	Prova criptográfica de que o payload veio do Rebyte	Verificação à prova de adulteração
Segredo pré-compartilhado	X-Webhook-Secret	String estática que você define na criação, ecoada em cada entrega	Verificação simples de segredo compartilhado

As assinaturas RSA estão sempre presentes. O segredo pré-compartilhado é opcional — defina-o ao criar o webhook se desejar um caminho de verificação mais simples.

---

Exemplo de Polling

Exemplo completo: crie uma tarefa, faça polling até a conclusão e, em seguida, envie um acompanhamento.

# Criar tarefa
TASK_ID=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a Python CLI that converts CSV to JSON"}' | jq -r '.id')

echo "Task: https://app.rebyte.ai/run/$TASK_ID"

# Polling até a conclusão
while true; do
  STATUS=$(curl -s https://api.rebyte.ai/v1/tasks/$TASK_ID \
    -H "API_KEY: rbk_xxx" | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 5
done

# Enviar um acompanhamento
curl -s -X POST https://api.rebyte.ai/v1/tasks/$TASK_ID/prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add support for nested JSON objects"}'

---

Formato de Erro

Todos os erros seguem esta estrutura:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

Código	Status HTTP	Descrição
missing_api_key	401	Cabeçalho API_KEY não fornecido
invalid_api_key	401	Chave de API inválida ou expirada
validation_error	400	O corpo da requisição falhou na validação
not_found	404	O recurso não existe ou não está acessível
limit_exceeded	400	Limite da organização atingido (ex: máximo de webhooks)
agent_disabled	403	O executor solicitado está desativado para esta organização
internal_error	500	Falha no lado do servidor

Limitação de Taxa

A API atualmente não impõe limites de taxa por chave. Cada POST /tasks provisiona uma VM real, então os custos escalam com o uso. Use webhooks em vez de polling agressivo para reduzir requisições desnecessárias.