API del Computer Agente

Provalo nel API Playground.

Base URL

https://api.rebyte.ai/v1

Autenticazione

Ogni richiesta richiede un’intestazione API_KEY. Ottieni la tua chiave da Impostazioni > Chiavi API.

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

Il nome dell’intestazione non è sensibile alle maiuscole. API_KEY, api-key e x-api-key funzionano tutti.

---

Endpoints

Metodo	Percorso	Descrizione
POST	/tasks	Crea un’attività
GET	/tasks	Elenca attività
GET	/tasks/:id	Ottieni attività con stato e cronologia dei prompt
POST	/tasks/:id/prompts	Invia un prompt di follow-up
PATCH	/tasks/:id/visibility	Cambia visibilità attività
DELETE	/tasks/:id	Elimina (soft-delete) un’attività
GET	/tasks/:id/events	Stream SSE di eventi di esecuzione
POST	/files	Ottieni un URL di caricamento file firmato
POST	/webhooks	Registra un webhook
GET	/webhooks	Elenca webhook
GET	/webhooks/:id	Ottieni dettagli webhook
DELETE	/webhooks/:id	Elimina un webhook
Tutti i percorsi sono relativi all’URL base (https://api.rebyte.ai/v1).

---

Tasks

Create Task

POST /tasks

Crea una nuova attività. Per impostazione predefinita, effettua il provisioning di una nuova VM (Computer Agente). Passa workspaceId per eseguire l’attività su un workspace esistente invece — questo salta il provisioning ed è significativamente più veloce.

La chiamata si blocca finché la VM non è stata sottoposta a provisioning e il primo prompt non è stato inviato.

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Descrizione dell’attività (max 100.000 caratteri)
executor	string	No	claude (predefinito), gemini, codex, opencode
model	string	No	Livello del modello per l’executor. Vedi Modelli.
workspaceId	string	No	UUID di un workspace esistente da riutilizzare
files	object[]	No	File da POST /files. Ciascuno: {"id": "...", "filename": "..."}
skills	string[]	No	Slug delle skill (es. ["deep-research", "pdf"])
githubUrl	string	No	Repo GitHub nel formato owner/repo
branchName	string	No	Nome del branch (predefinito: 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"
  }'

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

Salva il workspaceId dalla risposta per creare attività successive sullo stesso Computer 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

I modelli disponibili dipendono dall’executor:

Executor	Modelli Disponibili	Predefinito
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 (bring your own API key), sono disponibili solo i modelli del provider nativo dell’executor (es. l’executor claude con BYOK ottiene solo claude-sonnet-4.6 e claude-opus-4.6).

List Tasks

GET /tasks?limit=50&offset=0

Restituisce le attività create tramite l’API, ordinate per data di creazione (le più recenti per prime).

Parametro	Tipo	Predefinito	Descrizione
limit	number	50	Risultati per pagina (max 100)
offset	number	0	Offset di paginazione

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

Risposta:

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

Restituisce i dettagli completi dell’attività, inclusa la cronologia dei prompt e lo stato derivato.

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

Risposta:

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

Lo stato dell’attività è derivato dagli stati dei prompt:

Stato	Condizione
running	Qualsiasi prompt è pending o running
completed	Tutti i prompt sono terminali, l’ultimo è succeeded
failed	Tutti i prompt sono terminali, l’ultimo è failed
canceled	Tutti i prompt sono terminali, l’ultimo è canceled

Send Follow-Up

POST /tasks/:id/prompts

Invia un prompt di follow-up a un’attività in esecuzione o completata. Se la VM è ferma, viene riavviata automaticamente.

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Prompt di follow-up (max 100.000 caratteri)
skills	string[]	No	Slug di skill aggiuntive per questo 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"}'

Risposta (201):

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

Stream Events (SSE)

GET /tasks/:id/events

Apre uno stream di Server-Sent Events per l’ultimo prompt dell’attività. Gli eventi includono l’output dell’agente (stdout, stderr), le chiamate agli strumenti e i segnali di completamento.

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

Lo stream emette due tipi di eventi:

• event — eventi di esecuzione (output dell’agente, chiamate agli strumenti)
• done — evento finale con stato di completamento, quindi lo stream si chiude

Change Visibility

PATCH /tasks/:id/visibility

Campo	Tipo	Obbligatorio	Descrizione
visibility	string	Sì	private, shared, o public

Livello	Chi può visualizzare
private	Solo il proprietario della chiave API
shared	Tutti i membri dell’organizzazione (predefinito)
public	Chiunque abbia il link (sola lettura)

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 impostato su public, la risposta include un shareUrl per l’accesso non autenticato.

Delete Task

DELETE /tasks/:id

Elimina (soft-delete) l’attività. Restituisce 204 No Content.

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

---

Files

Carica file da allegare alle attività. Utilizza un flusso di URL firmato in due passaggi.

Step 1: Get Upload URL

POST /files

Campo	Tipo	Obbligatorio	Descrizione
filename	string	Sì	Nome del file (max 255 caratteri)
contentType	string	No	Tipo MIME (predefinito: application/octet-stream)

Risposta (201):

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

L’URL di caricamento scade in 1 ora.

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

Passa id e filename dal Passaggio 1 quando crei un’attività:

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

I file vengono copiati automaticamente nella VM dell’attività all’inizio dell’esecuzione.

---

Webhooks

Ricevi notifiche HTTP POST quando si verificano eventi dell’attività. I webhook sono universali — si attivano per tutte le attività della tua organizzazione, sia che siano state create tramite API, UI o qualsiasi altro canale.

Events

Evento	Si attiva quando
task.created	Viene creata una nuova attività
task.running	L’agente inizia l’esecuzione
task.completed	L’attività termina con successo
task.failed	L’attività fallisce
task.canceled	L’attività viene annullata dall’utente

Create Webhook

POST /webhooks

Campo	Tipo	Obbligatorio	Descrizione
url	string	Sì	URL dell’endpoint HTTPS
events	string[]	Sì	Eventi a cui iscriversi
description	string	No	Etichetta leggibile dall’uomo (max 500 caratteri)
secret	string	No	Segreto pre-condiviso (max 500 caratteri). Se impostato, incluso come intestazione X-Webhook-Secret in ogni consegna.

# 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"
  }'

Risposta (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
}

Note sul comportamento:

• URL duplicati: la registrazione dello stesso URL due volte restituisce il webhook esistente (idempotente)
• Limite: massimo 3 webhook per organizzazione. Il 4° restituisce limit_exceeded.
• Archiviazione del segreto: il valore del segreto non viene mai restituito in nessuna risposta. Viene esposto solo hasSecret: true/false.

List Webhooks

GET /webhooks

Restituisce tutti i webhook per la tua organizzazione con informazioni sullo stato (lastTriggeredAt, failureCount, isActive). I segreti non vengono mai esposti.

Get Webhook

GET /webhooks/:id

Delete Webhook

DELETE /webhooks/:id

Restituisce 204 No Content. I webhook eliminati smettono immediatamente di ricevere consegne.

Delivery

Quando un evento dell’attività corrisponde agli eventi sottoscritti da un webhook, Rebyte invia una richiesta HTTP POST all’URL del 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 — stato del prompt: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
• taskUrl — link diretto all’attività nell’interfaccia utente di Rebyte (sempre presente)
• result — testo di output finale dell’IA (presente negli eventi terminali: task.completed, task.failed, task.canceled; assente su task.created e task.running)

Chiama GET /tasks/:id per i dettagli completi dell’attività, inclusa la cronologia dei prompt.

Intestazioni di consegna:

Intestazione	Sempre presente	Descrizione
Content-Type	Sì	application/json
X-Webhook-Signature	Sì	Firma RSA-SHA256 codificata in Base64
X-Webhook-Timestamp	Sì	Timestamp Unix (secondi)
X-Webhook-Secret	Solo se il segreto è configurato	Il valore del segreto pre-condiviso che hai impostato alla creazione

Timeout: le consegne vanno in timeout dopo 10 secondi.

Gestione dei fallimenti:

• La consegna è fire-and-forget — nessun tentativo automatico in caso di fallimento
• Le risposte non-2xx incrementano failureCount
• Dopo 10 fallimenti consecutivi, il webhook viene automaticamente disabilitato (isActive: false)
• Le consegne riuscite azzerano failureCount

Signature Verification

Ogni consegna è firmata con la coppia di chiavi RSA-2048 della tua organizzazione, indipendentemente dal fatto che sia configurato un segreto pre-condiviso.

Come funziona:

1. Rebyte concatena {timestamp}.{body} (es. 1706443200.{"event":"task.completed",...})
2. Firma la stringa con RSA-SHA256 utilizzando la chiave privata della tua organizzazione
3. Invia la firma codificata in base64 in X-Webhook-Signature

Ottieni la tua chiave pubblica: contatta il supporto o recuperala dalla dashboard di Rebyte. La coppia di chiavi RSA-2048 viene generata automaticamente alla prima creazione del webhook e persiste per l’organizzazione.

Esempio di verifica (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');
});

Esempio di verifica (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

I webhook supportano due metodi di verifica indipendenti che possono essere utilizzati insieme:

Metodo	Intestazione	Come funziona	Caso d’uso
Firma RSA	X-Webhook-Signature	Prova crittografica che il payload proviene da Rebyte	Verifica anti-manomissione
Segreto pre-condiviso	X-Webhook-Secret	Stringa statica impostata alla creazione, riprodotta in ogni consegna	Semplice controllo del segreto condiviso

Le firme RSA sono sempre presenti. Il segreto pre-condiviso è opzionale — impostalo quando crei il webhook se desideri un percorso di verifica più semplice.

---

Polling Example

Esempio completo: crea un’attività, esegui il polling fino al completamento, quindi invia un follow-up.

# 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

Tutti gli errori seguono questa struttura:

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

Codice	Stato HTTP	Descrizione
missing_api_key	401	Intestazione API_KEY non fornita
invalid_api_key	401	Chiave API non valida o scaduta
validation_error	400	Il corpo della richiesta non ha superato la convalida
not_found	404	La risorsa non esiste o non è accessibile
limit_exceeded	400	Limite dell’organizzazione raggiunto (es. max webhook)
agent_disabled	403	L’executor richiesto è disabilitato per questa organizzazione
internal_error	500	Errore lato server

Rate Limiting

L’API attualmente non impone limiti di frequenza per chiave. Ogni POST /tasks effettua il provisioning di una VM reale, quindi i costi aumentano con l’utilizzo. Utilizza i webhook invece di un polling aggressivo per ridurre le richieste non necessarie.