API d'Ordinadors Agent

Prova-ho a l’API Playground.

Base URL

https://api.rebyte.ai/v1

Autenticació

Cada sol·licitud requereix una capçalera API_KEY. Obtén la teva clau des de Configuració > Claus API.

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

El nom de la capçalera no distingeix entre majúscules i minúscules. API_KEY, api-key i x-api-key funcionen tots.

---

Endpoints

Mètode	Ruta	Descripció
POST	/tasks	Crear una tasca
GET	/tasks	Llistar tasques
GET	/tasks/:id	Obtenir tasca amb estat i historial de prompts
POST	/tasks/:id/prompts	Enviar un prompt de seguiment
PATCH	/tasks/:id/visibility	Canviar la visibilitat de la tasca
DELETE	/tasks/:id	Eliminar una tasca (soft-delete)
GET	/tasks/:id/events	Flux SSE d’esdeveniments d’execució
POST	/files	Obtenir una URL de càrrega de fitxers signada
POST	/webhooks	Registrar un webhook
GET	/webhooks	Llistar webhooks
GET	/webhooks/:id	Obtenir detalls del webhook
DELETE	/webhooks/:id	Eliminar un webhook
Totes les rutes són relatives a la URL base (https://api.rebyte.ai/v1).

---

Tasques

Crear Tasca

POST /tasks

Crea una nova tasca. Per defecte, aprovisiona una nova VM (Ordinador Agent). Passa workspaceId per executar la tasca en un espai de treball existent en lloc d’això — això omet l’aprovisionament i és significativament més ràpid.

La crida es bloqueja fins que la VM s’aprovisiona i el primer prompt s’envia.

Cos de la sol·licitud:

Camp	Tipus	Requerit	Descripció
prompt	string	Sí	Descripció de la tasca (màx. 100.000 caràcters)
executor	string	No	claude (per defecte), gemini, codex, opencode
model	string	No	Nivell de model per a l’executor. Vegeu Models.
workspaceId	string	No	UUID d’un espai de treball existent per reutilitzar
files	object[]	No	Fitxers de POST /files. Cadascun: {"id": "...", "filename": "..."}
skills	string[]	No	Slugs d’habilitats (p. ex., ["deep-research", "pdf"])
githubUrl	string	No	Repositori de GitHub en format owner/repo
branchName	string	No	Nom de la branca (per defecte: 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"
}

Guarda el workspaceId de la resposta per crear tasques de seguiment al mateix Ordinador Agent:

# Primera tasca -- aprovisiona una 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')

# Segona tasca -- reutilitza la mateixa VM (molt més ràpid)
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

Els models disponibles depenen de l’executor:

Executor	Models disponibles	Per defecte
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	Igual que claude	gemini-3.1-pro

Amb BYOK (porta la teva pròpia clau API), només els models del proveïdor natiu de l’executor estan disponibles (p. ex., l’executor claude amb BYOK només obté claude-sonnet-4.6 i claude-opus-4.6).

Llistar Tasques

GET /tasks?limit=50&offset=0

Retorna les tasques creades mitjançant l’API, ordenades per hora de creació (les més noves primer).

Paràmetre	Tipus	Per defecte	Descripció
limit	number	50	Resultats per pàgina (màx. 100)
offset	number	0	Desplaçament de paginació

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
}

Obtenir Tasca

GET /tasks/:id

Retorna els detalls complets de la tasca, incloent l’historial de prompts i l’estat derivat.

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

L’estat de la tasca es deriva dels estats dels prompts:

Estat	Condició
running	Qualsevol prompt està pending o running
completed	Tots els prompts terminals, l’últim ha tingut succeeded
failed	Tots els prompts terminals, l’últim ha failed
canceled	Tots els prompts terminals, l’últim ha estat canceled

Enviar Seguiment

POST /tasks/:id/prompts

Envia un prompt de seguiment a una tasca en execució o completada. Si la VM està aturada, es reprèn automàticament.

Camp	Tipus	Requerit	Descripció
prompt	string	Sí	Prompt de seguiment (màx. 100.000 caràcters)
skills	string[]	No	Slugs d’habilitats addicionals per a aquest 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-..."
}

Flux d’Esdeveniments (SSE)

GET /tasks/:id/events

Obre un flux d’Esdeveniments Enviats pel Servidor (Server-Sent Events) per al darrer prompt de la tasca. Els esdeveniments inclouen la sortida de l’agent (stdout, stderr), les crides a eines i els senyals de finalització.

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

El flux emet dos tipus d’esdeveniments:

• event — esdeveniments d’execució (sortida de l’agent, crides a eines)
• done — esdeveniment final amb l’estat de finalització, després el flux es tanca

Canviar Visibilitat

PATCH /tasks/:id/visibility

Camp	Tipus	Requerit	Descripció
visibility	string	Sí	private, shared, o public

Nivell	Qui pot veure
private	Només el propietari de la clau API
shared	Tots els membres de l’organització (per defecte)
public	Qualsevol amb l’enllaç (només 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"}'

Quan s’estableix a public, la resposta inclou una shareUrl per a l’accés no autenticat.

Eliminar Tasca

DELETE /tasks/:id

Elimina la tasca de forma lògica (soft-delete). Retorna 204 No Content.

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

---

Fitxers

Puja fitxers per adjuntar a les tasques. Utilitza un flux d’URL signat en dos passos.

Pas 1: Obtenir URL de Càrrega

POST /files

Camp	Tipus	Requerit	Descripció
filename	string	Sí	Nom del fitxer (màx. 255 caràcters)
contentType	string	No	Tipus MIME (per defecte: application/octet-stream)

Resposta (201):

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

La URL de càrrega caduca en 1 hora.

Pas 2: Pujar el Fitxer

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

Pas 3: Adjuntar a la Tasca

Passa id i filename del Pas 1 en crear una tasca:

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

Els fitxers es copien automàticament a la VM de la tasca quan comença l’execució.

---

Webhooks

Rep notificacions HTTP POST quan es produeixen esdeveniments de tasca. Els webhooks són universals — s’activen per a totes les tasques de la teva organització, ja siguin creades mitjançant API, UI o qualsevol altre canal.

Esdeveniments

Esdeveniment	S’activa quan
task.created	Es crea una nova tasca
task.running	L’agent comença a executar-se
task.completed	La tasca finalitza amb èxit
task.failed	La tasca falla
task.canceled	La tasca és cancel·lada per l’usuari

Crear Webhook

POST /webhooks

Camp	Tipus	Requerit	Descripció
url	string	Sí	URL de l’endpoint HTTPS
events	string[]	Sí	Esdeveniments als quals subscriure’s
description	string	No	Etiqueta llegible per humans (màx. 500 caràcters)
secret	string	No	Secret precompartit (màx. 500 caràcters). Quan s’estableix, s’inclou com a capçalera X-Webhook-Secret en cada lliurament.

# Webhook sense 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 amb secret precompartit
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
}

Notes de comportament:

• URLs duplicades: registrar la mateixa URL dues vegades retorna el webhook existent (idempotent)
• Límit: màxim 3 webhooks per organització. El 4t retorna limit_exceeded.
• Emmagatzematge del secret: el valor del secret mai es retorna en cap resposta. Només s’exposa hasSecret: true/false.

Llistar Webhooks

GET /webhooks

Retorna tots els webhooks de la teva organització amb informació d’estat (lastTriggeredAt, failureCount, isActive). Els secrets mai s’exposen.

Obtenir Webhook

GET /webhooks/:id

Eliminar Webhook

DELETE /webhooks/:id

Retorna 204 No Content. Els webhooks eliminats deixen de rebre lliuraments immediatament.

Lliurament

Quan un esdeveniment de tasca coincideix amb els esdeveniments subscrits d’un webhook, Rebyte envia un HTTP POST a la URL del webhook.

Càrrega ú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 — estat del prompt: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
• taskUrl — enllaç directe a la tasca a la UI de Rebyte (sempre present)
• result — text de sortida final de l’IA (present en esdeveniments terminals: task.completed, task.failed, task.canceled; absent en task.created i task.running)

Crida GET /tasks/:id per obtenir els detalls complets de la tasca, incloent l’historial de prompts.

Capçaleres de lliurament:

Capçalera	Sempre present	Descripció
Content-Type	Sí	application/json
X-Webhook-Signature	Sí	Signatura RSA-SHA256 codificada en Base64
X-Webhook-Timestamp	Sí	Timestamp Unix (segons)
X-Webhook-Secret	Només si el secret està configurat	El valor del secret precompartit que vas establir en la creació

Temps d’espera: els lliuraments caduquen després de 10 segons.

Gestió d’errors:

• El lliurament és fire-and-forget — no hi ha reintents automàtics en cas d’error
• Les respostes que no són 2xx incrementen failureCount
• Després de 10 errors consecutius, el webhook es deshabilita automàticament (isActive: false)
• Els lliuraments exitosos reinicien failureCount a 0

Verificació de la Signatura

Cada lliurament està signat amb el parell de claus RSA-2048 de la teva organització, independentment de si s’ha configurat un secret precompartit.

Com funciona:

1. Rebyte concatena {timestamp}.{body} (p. ex., 1706443200.{"event":"task.completed",...})
2. Signa la cadena amb RSA-SHA256 utilitzant la clau privada de la teva organització
3. Envia la signatura codificada en base64 a X-Webhook-Signature

Obtén la teva clau pública: contacta amb el suport o recupera-la des del panell de control de Rebyte. El parell de claus RSA-2048 es genera automàticament en la primera creació del webhook i persisteix per a l’organització.

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

// Al teu gestor de webhook:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // ha de ser una cadena bruta, no JSON analitzat
  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');
});

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

Seguretat de dues capes

Els webhooks admeten dos mètodes de verificació independents que es poden utilitzar junts:

Mètode	Capçalera	Com funciona	Cas d’ús
Signatura RSA	X-Webhook-Signature	Prova criptogràfica que la càrrega útil prové de Rebyte	Verificació a prova de manipulacions
Secret precompartit	X-Webhook-Secret	Cadena estàtica que estableixes en la creació, retornada en cada lliurament	Comprovació simple de secret compartit

Les signatures RSA sempre estan presents. El secret precompartit és opcional — estableix-lo en crear el webhook si vols una ruta de verificació més senzilla.

---

Exemple de Polling

Exemple complet: crea una tasca, consulta l’estat fins a la finalització i després envia un seguiment.

# Crear tasca
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"

# Consultar fins que estigui fet
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 un seguiment
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"}'

---

Format d’Error

Tots els errors segueixen aquesta estructura:

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

Codi	Estat HTTP	Descripció
missing_api_key	401	Capçalera API_KEY no proporcionada
invalid_api_key	401	Clau API no vàlida o caducada
validation_error	400	El cos de la sol·licitud no ha superat la validació
not_found	404	El recurs no existeix o no és accessible
limit_exceeded	400	S’ha assolit el límit de l’organització (p. ex., màxim de webhooks)
agent_disabled	403	L’executor sol·licitat està deshabilitat per a aquesta organització
internal_error	500	Error del servidor

Límit de Taxa

Actualment, l’API no aplica límits de taxa per clau. Cada POST /tasks aprovisiona una VM real, de manera que els costos s’escalen amb l’ús. Utilitza webhooks en lloc de consultes agressives per reduir les sol·licituds innecessàries.