Tasks API — rebyte.ai docs

Create Task

POST /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)
`executor`	string	No	`claude` (default), `gemini`, `codex`, `opencode`
`model`	string	No	Model tier for the executor. See Models.
`workspaceId`	string	No	UUID of an existing workspace to reuse
`files`	object[]	No	Files from `POST /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
`branchName`	string	No	Branch name (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",
    "executor": "claude",
    "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"
}

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

Models

Available models depend on the executor. See Agent Harness for full details on executors and model routing.

Executor	Available Models	Default
`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.6`, `glm-5.1`, `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`

With BYOK (bring your own API key), only the executor's native provider models are available (e.g., claude executor with BYOK only gets claude-sonnet-4.6 and claude-opus-4.6).

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 /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",
      "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

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

Task status is derived from prompt states:

Status	Condition
`running`	Any prompt is `pending` or `running`
`completed`	All prompts terminal, latest is `succeeded`
`failed`	All prompts terminal, latest is `failed`
`canceled`	All prompts terminal, latest is `canceled`

Send Follow-Up

POST /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.

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

Cancel Task

POST /tasks/:id/cancel

Cancels all running and pending prompts for a task. Also sends a /cancel signal to the agent via gRPC (best-effort).

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

Response:

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

Stream Events (SSE)

GET /tasks/:id/events

Opens a Server-Sent Events stream for the task's latest prompt. Events include agent output (stdout, stderr), tool calls, and completion signals.

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

The stream emits two event types:

event -- execution events (agent output, tool calls)
done -- final event with completion status, then the stream closes

Change Visibility

PATCH /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 /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 /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": 52428800
}

The upload URL expires in 1 hour.

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

Manage files produced by tasks (reports, generated code, built binaries, etc.). Each workspace has its own artifact store.

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 /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://storage.googleapis.com/..."
    }
  ]
}

Download Artifact

GET /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"

Upload Artifacts (Direct)

POST /workspaces/:id/artifacts

Upload files directly as multipart/form-data. Max 10 files, 10 MB each. Uses merge semantics -- existing files with different names are preserved.

curl -X POST https://api.rebyte.ai/v1/workspaces/660e8400-.../artifacts \
  -H "API_KEY: rbk_xxx" \
  -F "files=@report.pdf" \
  -F "files=@data.csv"

Response (201):

{
  "uploaded": [
    {"name": "report.pdf", "size": 245120, "contentType": "application/pdf"},
    {"name": "data.csv", "size": 1024, "contentType": "text/csv"}
  ]
}

Upload Artifacts (Signed URL)

POST /workspaces/:id/artifacts/upload-url

For large files, request signed upload URLs and upload directly to cloud storage. Max 50 files per request.

Request body:

{
  "files": [
    {"name": "large-dataset.csv", "contentType": "text/csv"},
    {"name": "model.zip"}
  ]
}

Response:

{
  "files": [
    {
      "name": "large-dataset.csv",
      "uploadUrl": "https://storage.googleapis.com/...",
      "expiresAt": "2026-01-28T13:00:00.000Z"
    }
  ]
}

Upload URLs expire in 15 minutes. Upload via PUT:

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @large-dataset.csv

Delete Artifact

DELETE /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 /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" ]] && 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"}'