API de Computadora Agente

Pruébalo en el API Playground.

Base URL

https://api.rebyte.ai/v1

Authentication

Cada solicitud requiere un encabezado API_KEY. Obtén tu clave en Configuración > Claves API.

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

El nombre del encabezado no distingue entre mayúsculas y minúsculas. API_KEY, api-key y x-api-key funcionan.

---

Endpoints

Método	Ruta	Descripción
POST	/tasks	Crear una tarea
GET	/tasks	Listar tareas
GET	/tasks/:id	Obtener tarea con estado e historial de prompts
POST	/tasks/:id/prompts	Enviar un prompt de seguimiento
PATCH	/tasks/:id/visibility	Cambiar visibilidad de la tarea
DELETE	/tasks/:id	Eliminar una tarea (borrado suave)
GET	/tasks/:id/events	Flujo SSE de eventos de ejecución
POST	/files	Obtener una URL firmada para subir archivos
POST	/webhooks	Registrar un webhook
GET	/webhooks	Listar webhooks
GET	/webhooks/:id	Obtener detalles del webhook
DELETE	/webhooks/:id	Eliminar un webhook
Todas las rutas son relativas a la URL base (https://api.rebyte.ai/v1).

---

Tasks

Create Task

POST /tasks

Crea una nueva tarea. Por defecto, provisiona una nueva VM (Computadora Agente). Pasa workspaceId para ejecutar la tarea en un espacio de trabajo existente en su lugar — esto omite el aprovisionamiento y es significativamente más rápido.

La llamada se bloquea hasta que la VM es provisionada y el primer prompt es enviado.

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
prompt	string	Sí	Descripción de la tarea (máx. 100.000 caracteres)
executor	string	No	claude (por defecto), gemini, codex, opencode
model	string	No	Nivel de modelo para el ejecutor. Ver Modelos.
workspaceId	string	No	UUID de un espacio de trabajo existente para reutilizar
files	object[]	No	Archivos de POST /files. Cada uno: {"id": "...", "filename": "..."}
skills	string[]	No	Slugs de habilidades (ej., ["deep-research", "pdf"])
githubUrl	string	No	Repositorio de GitHub en formato propietario/repositorio
branchName	string	No	Nombre de la rama (por defecto: 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"
  }'

Respuesta (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"
}

Guarda el workspaceId de la respuesta para crear tareas de seguimiento en la misma Computadora Agente:

# First task -- provisions a new 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')

# Second task -- reuses the same VM (much faster)
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\"}"

Models

Los modelos disponibles dependen del ejecutor:

Ejecutor	Modelos Disponibles	Por Defecto
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

Con BYOK (trae tu propia clave API), solo los modelos del proveedor nativo del ejecutor están disponibles (ej., el ejecutor claude con BYOK solo obtiene claude-sonnet-4.6 y claude-opus-4.6).

List Tasks

GET /tasks?limit=50&offset=0

Devuelve las tareas creadas a través de la API, ordenadas por fecha de creación (las más recientes primero).

Parámetro	Tipo	Por Defecto	Descripción
limit	number	50	Resultados por página (máx. 100)
offset	number	0	Desplazamiento de paginación

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

Respuesta:

{
  "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
}

Get Task

GET /tasks/:id

Devuelve los detalles completos de la tarea, incluyendo el historial de prompts y el estado derivado.

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

Respuesta:

{
  "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"
    }
  ]
}

El estado de la tarea se deriva de los estados de los prompts:

Estado	Condición
running	Cualquier prompt está pending o running
completed	Todos los prompts son terminales, el último es succeeded
failed	Todos los prompts son terminales, el último es failed
canceled	Todos los prompts son terminales, el último es canceled

Send Follow-Up

POST /tasks/:id/prompts

Envía un prompt de seguimiento a una tarea en ejecución o completada. Si la VM está detenida, se reanuda automáticamente.

Campo	Tipo	Requerido	Descripción
prompt	string	Sí	Prompt de seguimiento (máx. 100.000 caracteres)
skills	string[]	No	Slugs de habilidades adicionales 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"}'

Respuesta (201):

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

Stream Events (SSE)

GET /tasks/:id/events

Abre un flujo de Eventos Enviados por el Servidor (Server-Sent Events) para el último prompt de la tarea. Los eventos incluyen la salida del agente (stdout, stderr), llamadas a herramientas y señales de finalización.

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

El flujo emite dos tipos de eventos:

• event — eventos de ejecución (salida del agente, llamadas a herramientas)
• done — evento final con estado de finalización, luego el flujo se cierra

Change Visibility

PATCH /tasks/:id/visibility

Campo	Tipo	Requerido	Descripción
visibility	string	Sí	private, shared o public

Nivel	Quién puede ver
private	Solo el propietario de la clave API
shared	Todos los miembros de la organización (por defecto)
public	Cualquiera con el enlace (solo lectura)

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

Cuando se establece en public, la respuesta incluye una shareUrl para acceso no autenticado.

Delete Task

DELETE /tasks/:id

Elimina la tarea (borrado suave). Devuelve 204 No Content.

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

---

Files

Sube archivos para adjuntarlos a las tareas. Utiliza un flujo de URL firmada de dos pasos.

Step 1: Get Upload URL

POST /files

Campo	Tipo	Requerido	Descripción
filename	string	Sí	Nombre del archivo (máx. 255 caracteres)
contentType	string	No	Tipo MIME (por defecto: application/octet-stream)

Respuesta (201):

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

La URL de subida expira en 1 hora.

Step 2: Upload the File

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

Step 3: Attach to Task

Pasa id y filename del Paso 1 al crear una tarea:

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

Los archivos se copian automáticamente en la VM de la tarea cuando comienza la ejecución.

---

Webhooks

Recibe notificaciones HTTP POST cuando ocurren eventos de tareas. Los webhooks son universales — se activan para todas las tareas de tu organización, ya sean creadas a través de la API, la UI o cualquier otro canal.

Events

Evento	Se activa cuando
task.created	Se crea una nueva tarea
task.running	El agente comienza a ejecutarse
task.completed	La tarea finaliza con éxito
task.failed	La tarea falla
task.canceled	La tarea es cancelada por el usuario

Create Webhook

POST /webhooks

Campo	Tipo	Requerido	Descripción
url	string	Sí	URL del endpoint HTTPS
events	string[]	Sí	Eventos a los que suscribirse
description	string	No	Etiqueta legible por humanos (máx. 500 caracteres)
secret	string	No	Secreto pre-compartido (máx. 500 caracteres). Cuando se establece, se incluye como encabezado X-Webhook-Secret en cada entrega.

# Webhook without secret
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 with pre-shared secret
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"
  }'

Respuesta (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 comportamiento:

• URLs duplicadas: registrar la misma URL dos veces devuelve el webhook existente (idempotente)
• Límite: máximo 3 webhooks por organización. El 4º devuelve limit_exceeded.
• Almacenamiento del secreto: el valor del secreto nunca se devuelve en ninguna respuesta. Solo se expone hasSecret: true/false.

List Webhooks

GET /webhooks

Devuelve todos los webhooks de tu organización con información de estado (lastTriggeredAt, failureCount, isActive). Los secretos nunca se exponen.

Get Webhook

GET /webhooks/:id

Delete Webhook

DELETE /webhooks/:id

Devuelve 204 No Content. Los webhooks eliminados dejan de recibir entregas inmediatamente.

Delivery

Cuando un evento de tarea coincide con los eventos suscritos de un webhook, Rebyte envía un HTTP POST a la URL del webhook.

Carga útil:

{
  "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 — estado del prompt: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
• taskUrl — enlace directo a la tarea en la UI de Rebyte (siempre presente)
• result — texto de salida final de la IA (presente en eventos terminales: task.completed, task.failed, task.canceled; ausente en task.created y task.running)

Llama a GET /tasks/:id para obtener los detalles completos de la tarea, incluyendo el historial de prompts.

Encabezados de entrega:

Encabezado	Siempre presente	Descripción
Content-Type	Sí	application/json
X-Webhook-Signature	Sí	Firma RSA-SHA256 codificada en Base64
X-Webhook-Timestamp	Sí	Marca de tiempo Unix (segundos)
X-Webhook-Secret	Solo si el secreto está configurado	El valor del secreto pre-compartido que configuraste al crear

Tiempo de espera: las entregas expiran después de 10 segundos.

Manejo de fallos:

• La entrega es fire-and-forget — no hay reintentos automáticos en caso de fallo
• Las respuestas que no son 2xx incrementan failureCount
• Después de 10 fallos consecutivos, el webhook se deshabilita automáticamente (isActive: false)
• Las entregas exitosas restablecen failureCount a 0

Signature Verification

Cada entrega se firma con el par de claves RSA-2048 de tu organización, independientemente de si se ha configurado un secreto pre-compartido.

Cómo funciona:

1. Rebyte concatena {timestamp}.{body} (ej., 1706443200.{"event":"task.completed",...})
2. Firma la cadena con RSA-SHA256 usando la clave privada de tu organización
3. Envía la firma codificada en base64 en X-Webhook-Signature

Obtén tu clave pública: contacta con soporte o recupérala desde el panel de Rebyte. El par de claves RSA-2048 se genera automáticamente en la primera creación de webhook y persiste para la organización.

Ejemplo de verificación (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');
});

Ejemplo de verificación (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

Two-layer security

Los webhooks admiten dos métodos de verificación independientes que se pueden usar juntos:

Método	Encabezado	Cómo funciona	Caso de uso
Firma RSA	X-Webhook-Signature	Prueba criptográfica de que la carga útil proviene de Rebyte	Verificación a prueba de manipulaciones
Secreto pre-compartido	X-Webhook-Secret	Cadena estática que estableces al crear, devuelta en cada entrega	Verificación simple de secreto compartido

Las firmas RSA siempre están presentes. El secreto pre-compartido es opcional — configúralo al crear el webhook si deseas una ruta de verificación más sencilla.

---

Polling Example

Ejemplo completo: crea una tarea, consulta su estado hasta que se complete y luego envía un seguimiento.

# Create task
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"

# Poll until done
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

# Send a follow-up
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"}'

---

Error Format

Todos los errores siguen esta estructura:

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

Código	Estado HTTP	Descripción
missing_api_key	401	Encabezado API_KEY no proporcionado
invalid_api_key	401	Clave API inválida o expirada
validation_error	400	El cuerpo de la solicitud falló la validación
not_found	404	El recurso no existe o no es accesible
limit_exceeded	400	Límite de la organización alcanzado (ej., máximo de webhooks)
agent_disabled	403	El ejecutor solicitado está deshabilitado para esta organización
internal_error	500	Fallo del lado del servidor

Rate Limiting

Actualmente, la API no impone límites de tasa por clave. Cada POST /tasks provisiona una VM real, por lo que los costos escalan con el uso. Utiliza webhooks en lugar de un sondeo agresivo para reducir las solicitudes innecesarias.