API Reference

Jetty exposes two main APIs for workflow management and execution.

Base URLs

Service	URL	Purpose
flows-api	https://flows-api.jetty.io	Run workflows, view logs, trajectories
dock	https://dock.jetty.io	Manage collections, tasks, datasets

Authentication

All requests require a Bearer token:

curl -H "Authorization: Bearer $JETTY_API_TOKEN" ...

Important: API tokens are scoped to specific collections. Ensure your token has access to the collection you're targeting.

---

Workflow Execution

Run Workflow (Async)

Starts a workflow and returns immediately with a tracking ID.

Endpoint: POST /api/v1/run/{collection}/{task}

Request:

curl -X POST "https://flows-api.jetty.io/api/v1/run/my-collection/my-task" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -F "bakery_host=https://dock.jetty.io" \
  -F 'init_params={"prompt": "Hello world"}'

Response:

{
  "workflow_id": "wf_abc123xyz",
  "trajectory_id": "traj_def456",
  "status": "running"
}

Run Workflow (Sync)

Starts a workflow and waits for completion.

Endpoint: POST /api/v1/run-sync/{collection}/{task}

Request:

curl -X POST "https://flows-api.jetty.io/api/v1/run-sync/my-collection/my-task" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -F "bakery_host=https://dock.jetty.io" \
  -F 'init_params={"prompt": "Hello world"}'

Response:

{
  "workflow_id": "wf_abc123xyz",
  "trajectory_id": "traj_def456",
  "status": "completed",
  "result": {
    "steps": {
      "my_step": {
        "inputs": {...},
        "outputs": {...}
      }
    }
  }
}

Run with File Upload

Endpoint: POST /api/v1/run/{collection}/{task}

curl -X POST "https://flows-api.jetty.io/api/v1/run/my-collection/doc-processor" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -F "bakery_host=https://dock.jetty.io" \
  -F 'init_params={"instruction": "Summarize this document"}' \
  -F "files=@/path/to/document.pdf"

Files are accessible in the workflow via init_params.file_paths[0].

---

Monitoring & Logs

Get Workflow Logs

Endpoint: GET /api/v1/workflows-logs/{workflow_id}

curl "https://flows-api.jetty.io/api/v1/workflows-logs/wf_abc123xyz" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

List Trajectories

Endpoint: GET /api/v1/db/trajectories/{collection}/{task}?limit=20

curl "https://flows-api.jetty.io/api/v1/db/trajectories/my-collection/my-task?limit=20" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

Get Trajectory Details

Endpoint: GET /api/v1/db/trajectory/{collection}/{task}/{trajectory_id}

curl "https://flows-api.jetty.io/api/v1/db/trajectory/my-collection/my-task/traj_def456" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

Get Workflow Statistics

Endpoint: GET /api/v1/db/stats/{collection}/{task}

curl "https://flows-api.jetty.io/api/v1/db/stats/my-collection/my-task" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

---

Task Management (Dock API)

List Tasks

Endpoint: GET /api/v1/tasks/{collection}/

curl "https://dock.jetty.io/api/v1/tasks/my-collection/" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

Get Task

Endpoint: GET /api/v1/tasks/{collection}/{task}

curl "https://dock.jetty.io/api/v1/tasks/my-collection/my-task" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

Create Task

Endpoint: POST /api/v1/tasks/{collection}

curl -X POST "https://dock.jetty.io/api/v1/tasks/my-collection" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-task",
    "description": "A workflow that processes text",
    "workflow": {
      "init_params": {"text": "default"},
      "step_configs": {
        "echo": {
          "activity": "text_echo",
          "text_path": "init_params.text"
        }
      },
      "steps": ["echo"]
    }
  }'

Update Task

Endpoint: PUT /api/v1/tasks/{collection}/{task}

Delete Task

Endpoint: DELETE /api/v1/tasks/{collection}/{task}

---

List Step Templates

Endpoint: GET /api/v1/step-templates

curl "https://flows-api.jetty.io/api/v1/step-templates" | jq

Get Step Template Details

curl "https://flows-api.jetty.io/api/v1/step-templates/{activity_name}" | jq

---

Error Codes

Code	Meaning	Resolution
401	Invalid/expired token	Regenerate API token
403	Access denied	Check collection permissions
404	Not found	Verify collection/task names
422	Validation error	Check request body format
429	Rate limited	Reduce request frequency
500	Internal error	Retry with exponential backoff