Task Orchestration API - Quick Reference

One-page reference for common operations.

---

Minimal Task Manifest

version: "1"
kind: Task
metadata:
  name: "My Task"
repository:
  url: "https://github.com/org/repo.git"
  branch: "main"
claude:
  prompt: "Your instructions here"

---

REST API Endpoints

Method	Endpoint	Description
POST	`/api/v1/tasks`	Submit task
GET	`/api/v1/tasks`	List tasks
GET	`/api/v1/tasks/{id}`	Get task status
DELETE	`/api/v1/tasks/{id}`	Cancel task
GET	`/api/v1/tasks/{id}/logs`	Stream logs
GET	`/api/v1/tasks/{id}/artifacts`	List artifacts
GET	`/api/v1/tasks/{id}/artifacts/{name}`	Download artifact

---

CLI Commands

# Submit task
sandbox task submit task.yaml

# List tasks
sandbox task list
sandbox task list --state running
sandbox task list --label team=platform

# Get status
sandbox task status <task-id>
sandbox task status <task-id> --watch

# Stream logs
sandbox task logs <task-id> --follow

# Cancel task
sandbox task cancel <task-id>

# List artifacts
sandbox task artifacts <task-id>

# Download artifact
sandbox task download <task-id> <artifact-name>

---

Task States

pending → staging → provisioning → ready → running → completing → completed
    ↓         ↓          ↓           ↓        ↓           ↓
cancelled  cancelled  cancelled   cancelled failed   failed/failed_preserved

Terminal States: `completed`, `failed`, `failed_preserved`, `cancelled`

---

Common curl Examples

Submit Task

curl -X POST http://localhost:8122/api/v1/tasks \
  -H "Content-Type: application/yaml" \
  --data-binary @task.yaml

List Tasks

# All tasks
curl http://localhost:8122/api/v1/tasks

# Running tasks
curl http://localhost:8122/api/v1/tasks?state=running

# With pagination
curl http://localhost:8122/api/v1/tasks?limit=50&offset=0

Get Task Status

curl http://localhost:8122/api/v1/tasks/task-001

Cancel Task

curl -X DELETE http://localhost:8122/api/v1/tasks/task-001

Stream Logs

# All logs
curl http://localhost:8122/api/v1/tasks/task-001/logs

# Follow logs (requires SSE client)
curl -N http://localhost:8122/api/v1/tasks/task-001/logs?follow=true

# Last 100 lines
curl http://localhost:8122/api/v1/tasks/task-001/logs?tail=100

List Artifacts

curl http://localhost:8122/api/v1/tasks/task-001/artifacts

Download Artifact

curl http://localhost:8122/api/v1/tasks/task-001/artifacts/report.md \
  -o report.md

---

WebSocket Connection

const ws = new WebSocket('ws://localhost:8121/api/v1/tasks/stream?task_id=task-001');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data);
};

Event Types: `state_change`, `output`, `progress`, `metrics`, `error`

---

Python Example

import requests
import yaml

# Submit task
with open('task.yaml') as f:
    manifest = yaml.safe_load(f)

response = requests.post(
    'http://localhost:8122/api/v1/tasks',
    json=manifest
)
task_id = response.json()['task_id']

# Wait for completion
import time
while True:
    status = requests.get(f'http://localhost:8122/api/v1/tasks/{task_id}').json()
    print(f"State: {status['state']}")
    if status['state'] in ['completed', 'failed', 'cancelled']:
        break
    time.sleep(5)

# Download artifacts
artifacts = requests.get(f'http://localhost:8122/api/v1/tasks/{task_id}/artifacts').json()
for artifact in artifacts['artifacts']:
    print(f"Downloading {artifact['name']}...")
    data = requests.get(f"http://localhost:8122{artifact['download_url']}").content
    with open(artifact['name'], 'wb') as f:
        f.write(data)

---

Common Manifest Patterns

Bug Fix with GitHub

version: "1"
kind: Task
metadata:
  name: "Fix bug #42"
repository:
  url: "https://github.com/org/app.git"
  branch: "main"
claude:
  prompt: "Fix the bug in GitHub issue #42"
  mcp_config:
    mcpServers:
      github:
        command: "npx"
        args: ["-y", "@modelcontextprotocol/server-github"]
        # GitHub auth is supplied by a session credential lease.
vm:
  network_mode: "outbound"
  allowed_hosts: ["api.github.com"]
startup_profile:
  id: "startup-gh-42"
  trigger: "on_instance_ready"
  session:
    launcher: "agentic-claude-automation"
    workdir: "/workspace"
  credential_refs:
    - id: "cred_github_repo_push"
      mount: "github_token"
lifecycle:
  artifact_patterns: ["*.patch"]

Security Audit

version: "1"
kind: Task
metadata:
  name: "Security Audit"
repository:
  url: "https://github.com/org/app.git"
  branch: "production"
claude:
  prompt: |
    Perform security audit:
    1. Run static analysis
    2. Check dependencies
    3. Generate report
  allowed_tools: ["Read", "Bash", "Grep", "Write"]
vm:
  network_mode: "isolated"  # No network for security
lifecycle:
  timeout: "8h"
  artifact_patterns: ["security-report.md"]

Large VM Task

version: "1"
kind: Task
metadata:
  name: "Heavy Processing"
repository:
  url: "https://github.com/org/app.git"
  branch: "main"
claude:
  prompt: "Process large dataset"
vm:
  cpus: 16
  memory: "32G"
  disk: "100G"
  profile: "agentic-dev"
lifecycle:
  timeout: "24h"

---

Error Codes

Code	Error Type	Description
400	`invalid_manifest`	Manifest validation failed
404	`task_not_found`	Task doesn't exist
409	`duplicate_task_id`	Task ID already exists
409	`task_already_terminal`	Task is completed/failed
507	`insufficient_resources`	Not enough resources

---

Tips and Best Practices

1. Always specify a unique `metadata.id` to avoid duplicates 2. Use `lifecycle.failure_action: preserve` for debugging failed tasks 3. Specify `lifecycle.artifact_patterns` to collect outputs 4. Use `network_mode: outbound` with allowlist for internet access 5. Reference secrets, don't embed them in manifests 6. Set reasonable timeouts - default is 24h 7. Use labels for organization: `label.team=platform` 8. Follow logs to see real-time progress

---

Health Checks

# Basic health
curl http://localhost:8122/api/health

# Detailed health
curl http://localhost:8122/api/v1/health

# Readiness probe
curl http://localhost:8122/api/v1/health/ready

# Liveness probe
curl http://localhost:8122/api/v1/health/live

# Prometheus metrics
curl http://localhost:8122/metrics

---

Default Values

Field	Default
`vm.profile`	`agentic-dev`
`vm.cpus`	`4`
`vm.memory`	`8G`
`vm.disk`	`40G`
`vm.network_mode`	`isolated`
`claude.headless`	`true`
`claude.skip_permissions`	`true`
`claude.output_format`	`stream-json`
`claude.model`	`claude-sonnet-4-5-20250929`
`lifecycle.timeout`	`24h`
`lifecycle.failure_action`	`destroy`

---

Quick Reference v1.0.0 | 2026-01-29