Tasks API

Legacy compatibility API: Existing Tasks integrations remain supported. New integrations should use the Agent, Session, and Message API, which separates reusable configuration from isolated execution and provides an authoritative asynchronous transcript.

Create Task

POST /v1/tasks

Creates a new task. By default, provisions a new VM (workspace). Pass workspaceId to run the task on an existing workspace instead -- this skips provisioning and is significantly faster.

Request body:

Field	Type	Required	Description
prompt	string	Yes	Task description (max 100,000 chars)
workspaceId	string	No	UUID of an existing workspace to reuse
agentProfileId	string	No	UUID of the organization Agent Profile to copy when creating a new workspace
files	object[]	No	Files from POST /v1/files. Each: {"id": "...", "filename": "..."}
skills	string[]	No	Skill identifiers to install in the VM. See Skills.
githubUrl	string	No	GitHub repo in owner/repo format for a new workspace
branchName	string	No	Branch name for a new workspace (default: 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",
    "skills": ["deep-research"],
    "githubUrl": "your-org/your-repo"
  }'

Response (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",
  "promptId": "770e8400-e29b-41d4-a716-446655440002",
  "agentMessageId": "msg_123",
  "warnings": []
}

agentMessageId is present when the initial manager message starts immediately. warnings contains non-fatal setup warnings; the task was still accepted.

Save the workspaceId from the response to create follow-on tasks on the same workspace:

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

Skills

Skills are reusable capability packages installed into the VM when the task starts (or when a follow-up prompt is sent). The agent reads each skill's SKILL.md and uses it as needed.

There are two sources you can pull skills from:

1. Official Rebyte AI skills — pass the slug directly:

{ "skills": ["pdf", "deep-research", "image-generation"] }

2. Your organization's private skills — pass the full path org/<org_id>/<slug>:

{ "skills": ["org/org_31Tej1nsxnEwwetlwhReHc9jRA7/internal-runbook"] }

Organization skills are private to your organization. Create and publish them via Skill Manager in the dashboard, then reference them by their full org/<org_id>/<slug> path.

Available Official Skills

Documents & Files

Slug	Description
pdf	Create, edit, and extract content from PDF documents
docx	Read, create, and edit Microsoft Word documents
xlsx	Read, create, and edit Excel spreadsheets
pptx	Generate PowerPoint (.pptx) files
slide	Create HTML slide decks rendered live in chat
super-extract	Extract structured entities from unstructured text

Web & Research

Slug	Description
internet-search	Search the web for current information
deep-research	Multi-source research with citation tracking and verification
financial-deep-research	Financial research with market data and regulatory tracking
data-scraper	Scrape web pages with anti-bot bypass (Cloudflare Turnstile, stealth)
repo-hunter	Discover and analyze GitHub repositories
stock-analysis	Stock and company analysis with real market data

Images, Audio & Video

Slug	Description
image-generation	Generate and edit images via Google Nano Banana (Gemini 3.1)
speech-to-text	Transcribe audio with OpenAI Whisper
text-to-speech	Generate voiceovers and narration with OpenAI TTS
podcast-producer	Produce broadcast-ready podcast audio from a script

Build & Deploy

Slug	Description
rebyte-app-builder	Deploy web applications to Rebyte Cloud (*.rebyte.pro)

Skills are reinstalled on every prompt, so you can change the skills array between follow-ups on the same task.

---

List Tasks

GET /v1/tasks?limit=50&offset=0

Returns tasks created via the API, sorted by creation time (newest first).

Param	Type	Default	Description
limit	number	50	Results per page (max 100)
offset	number	0	Pagination offset

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

Response:

{
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://app.rebyte.ai/run/550e8400-...",
      "title": "Build REST API with Express",
      "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 /v1/tasks/:id

Returns full task details including prompt history and derived status.

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

Response:

{
  "id": "550e8400-...",
  "url": "https://app.rebyte.ai/run/550e8400-...",
  "status": "running",
  "title": "Build REST API with Express",
  "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"
    }
  ]
}

Task status is derived from prompt states:

Status	Condition
running	Any prompt is pending, running, or paused for human input
completed	All prompts terminal, latest is succeeded
failed	All prompts terminal, latest is failed
canceled	All prompts terminal, latest is canceled

---

Get Task Content

GET /v1/tasks/:id/content

Returns the authoritative top-level transcript: each user prompt and the manager's current or final response. Add ?include=events to include the normalized manager event array for every prompt.

curl "https://api.rebyte.ai/v1/tasks/550e8400-.../content?include=events" \
  -H "API_KEY: rbk_xxx"

Response:

{
  "id": "550e8400-...",
  "status": "completed",
  "prompts": [
    {
      "id": "770e8400-...",
      "status": "succeeded",
      "userPrompt": "Build a REST API with Express",
      "response": "Implemented the API and added tests.",
      "submittedAt": "2026-01-28T12:00:01.000Z",
      "completedAt": "2026-01-28T12:05:00.000Z",
      "events": []
    }
  ]
}

Without include=events, the events field is omitted. Delegated sub-prompts are not top-level conversation turns; retrieve their structured events through the sub-prompt events endpoint.

---

Send Follow-Up

POST /v1/tasks/:id/prompts

Send a follow-up prompt to a running or completed task. If the VM is stopped, it is automatically resumed.

Field	Type	Required	Description
prompt	string	Yes	Follow-up prompt (max 100,000 chars)
skills	string[]	No	Skill identifiers to install for this prompt. See Skills.
files	object[]	No	Files from POST /v1/files. Each: {"id": "...", "filename": "..."}

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

Response (201):

{
  "promptId": "770f9500-...",
  "visibility": "visible",
  "agentMessageId": "msg_456",
  "workflowId": "agent-loop-...",
  "warnings": []
}

visibility is visible when the follow-up starts as a conversation turn and pending when it is queued. Depending on that state, execution identifiers such as agentMessageId, workflowId, or steeringSignaledMessageId may be omitted.

---

Cancel Task

POST /v1/tasks/:id/cancel

Cancels active manager messages, pending prompts, and active delegated sandbox prompts for the task.

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

Response:

{
  "id": "550e8400-...",
  "status": "canceled",
  "canceledPrompts": 1,
  "canceledSandboxPrompts": 1
}

---

Stream Events (SSE)

GET /v1/tasks/:id/events

Opens a Server-Sent Events stream for the task's latest visible, top-level prompt. Events include manager output, reasoning, tool calls, tool results, human-input requests, and completion signals.

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

The stream emits two SSE event names:

• event -- a normalized execution event. Use its stable eventKey for deduplication; seq is local to the current connection.
• done -- the current status, lastSeq, and finalResult, after which the stream closes.

The connection runs for at most 15 minutes. If the prompt is still running then, done has status: "running"; reconnect to continue. A prompt paused on ask_user_question remains nonterminal until you answer it or the connection reaches this limit.

---

Get Sub-Prompt Events

GET /v1/tasks/:id/prompts/:promptId/events?afterSeq=-1

Delegated sandbox prompts do not appear as top-level turns. Parent tool_use and tool_result events expose a subPromptId; use it here to retrieve that sub-prompt's full normalized events, including structured tool results.

This endpoint returns JSON, not SSE. Pass afterSeq to fetch only events whose seq is greater than that value.

curl "https://api.rebyte.ai/v1/tasks/550e8400-.../prompts/880e8400-.../events?afterSeq=12" \
  -H "API_KEY: rbk_xxx"

Response:

{
  "promptId": "880e8400-...",
  "events": [
    {
      "seq": 13,
      "eventType": "tool_result",
      "payload": {"name": "flight_search", "content": "..."},
      "timestamp": 1760000000000,
      "promptId": "880e8400-..."
    }
  ]
}

---

Answer a Human-Input Request

POST /v1/tasks/:id/answer

When an ask_user_question event pauses a turn, send its messageId and numeric actionId back with the answer. The event payload currently serializes actionId as a string, so convert it to a JSON number for this request. The answer field accepts any JSON value.

curl -X POST https://api.rebyte.ai/v1/tasks/550e8400-.../answer \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "msg_456",
    "actionId": 3,
    "answer": {"selectedOptions": [0]}
  }'

Response:

{
  "ok": true,
  "workflowId": "agent-loop-..."
}

If the identified action no longer exists or is no longer blocked, the endpoint returns 409 no_blocked_action.

---

Change Visibility

PATCH /v1/tasks/:id/visibility

Field	Type	Required	Description
visibility	string	Yes	private, shared, or public

Level	Who can view
private	Only the API key owner
shared	All organization members (default)
public	Anyone with the link (read-only)

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

When set to public, the response includes a shareUrl for unauthenticated access.

---

Delete Task

DELETE /v1/tasks/:id

Soft-deletes the task. Returns 204 No Content.

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

---

Files

Upload files to attach to tasks. Uses a two-step signed-URL flow.

Step 1: Get Upload URL

POST /v1/files

Field	Type	Required	Description
filename	string	Yes	File name (max 255 chars)
contentType	string	No	MIME type (default: application/octet-stream)

Response (201):

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

The upload URL expires in 1 hour. The maximum file size is 200 MiB (209715200 bytes).

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

Pass id and filename from Step 1 when creating a task:

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

Files are automatically copied into the task's VM when execution begins.

---

Workspace Artifacts

Read or delete files produced by tasks (reports, generated exports, media, etc.). Each workspace has its own artifact store. Workspace artifacts are output-only in the public API; agents create them inside their VMs, and there is no public /v1/workspaces artifact upload endpoint.

Allowed file types: .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .csv, .tsv, .rtf, .epub, .html, .htm, .zip, .gz, .tar, .tgz, .png, .jpg, .jpeg, .gif, .webp, .svg, .tiff, .tif, .bmp, .avif, .mp4, .webm, .mov, .avi, .mkv, .mp3, .wav, .ogg, .aac, .flac, .m4a.

List Artifacts

GET /v1/workspaces/:id/artifacts

Lists all artifact files in a workspace.

curl https://api.rebyte.ai/v1/workspaces/660e8400-.../artifacts \
  -H "API_KEY: rbk_xxx"

Response:

{
  "data": [
    {
      "name": "report.pdf",
      "size": 245120,
      "contentType": "application/pdf",
      "downloadUrl": "https://usercontent.rebyte.space/uc/signed/.../report.pdf"
    }
  ]
}

Download Artifact

GET /v1/workspaces/:id/artifacts/:filename

Downloads a single artifact file. Returns the file as a binary stream with Content-Disposition: attachment.

curl -o report.pdf \
  https://api.rebyte.ai/v1/workspaces/660e8400-.../artifacts/report.pdf \
  -H "API_KEY: rbk_xxx"

Delete Artifact

DELETE /v1/workspaces/:id/artifacts/:filename

Deletes a single artifact file. Returns 204 No Content.

curl -X DELETE \
  https://api.rebyte.ai/v1/workspaces/660e8400-.../artifacts/report.pdf \
  -H "API_KEY: rbk_xxx"

Delete All Artifacts

DELETE /v1/workspaces/:id/artifacts

Deletes all artifact files in a workspace. Returns 204 No Content.

---

Polling Example

Complete example: create a task, poll until completion, then send a 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" || "$STATUS" == "canceled" ]] && 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"}'