DevTeam Orchestrator v1.0 is live. Read the changelog →
REST API
Tasks

Tasks API

Create Task

POST /api/tasks

Create a new task for execution.

Request Body

{
  "prompt": "Analyze this contract for liability risks",
  "model": "sonnet",
  "queue": "default",
  "systemPrompt": "You are a senior legal analyst.",
  "context": {
    "contractText": "...",
    "jurisdiction": "New York"
  },
  "priority": 8,
  "timeoutMs": 60000,
  "tags": ["legal", "contract-review"],
  "maxTokens": 4096,
  "temperature": 0.3,
  "callbackUrl": "https://your-app.com/webhook",
  "idempotencyKey": "unique-request-id-123",
  "hitl": {
    "required": true,
    "confidenceThreshold": 0.85,
    "timeoutMs": 3600000
  }
}
FieldTypeRequiredDescription
promptstringYesThe prompt to send to the model
modelstringNoModel identifier. Default: sonnet
queuestringNoTask queue. Default: default
systemPromptstringNoSystem instructions for the model
contextobjectNoAdditional context key-value pairs
prioritynumberNoPriority 1-10. Default: 5
timeoutMsnumberNoTimeout in ms. Default: 300000
tagsstring[]NoTags for filtering
maxTokensnumberNoMaximum response tokens
temperaturenumberNoSampling temperature (0-1)
callbackUrlstringNoWebhook URL for completion notification
idempotencyKeystringNoPrevents duplicate submissions
hitlobjectNoHITL configuration

Response

{
  "success": true,
  "data": {
    "id": "dt_task_abc123",
    "status": "pending",
    "model": "sonnet",
    "queue": "default",
    "priority": 8,
    "tags": ["legal", "contract-review"],
    "createdAt": "2026-02-20T10:00:00Z"
  }
}

Status Code: 201 Created

Get Task

GET /api/tasks/:id

Retrieve details of a specific task.

Response

{
  "success": true,
  "data": {
    "id": "dt_task_abc123",
    "status": "completed",
    "model": "sonnet",
    "queue": "default",
    "priority": 8,
    "prompt": "Analyze this contract...",
    "tags": ["legal", "contract-review"],
    "createdAt": "2026-02-20T10:00:00Z",
    "startedAt": "2026-02-20T10:00:01Z",
    "completedAt": "2026-02-20T10:00:04Z",
    "output": "Based on the analysis of the contract...",
    "usage": {
      "input": 1200,
      "output": 856,
      "total": 2056,
      "totalCost": 0.012
    },
    "workerId": "worker-asus-gpu",
    "retryCount": 0
  }
}

List Tasks

GET /api/tasks

List tasks with optional filtering.

Query Parameters

ParameterTypeDescription
statusstringFilter by status (comma-separated for multiple)
modelstringFilter by model
queuestringFilter by queue
tagsstringFilter by tags (comma-separated)
createdAfterstringISO 8601 date
createdBeforestringISO 8601 date
limitnumberMax results (default: 20, max: 100)
offsetnumberPagination offset
orderBystringcreatedAt, completedAt, priority
orderstringasc or desc

Example

curl "https://devteam.marsala.dev/api/tasks?status=completed,failed&tags=legal&limit=50&orderBy=createdAt&order=desc" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Cancel Task

DELETE /api/tasks/:id

Cancel a pending or running task.

Response

{
  "success": true,
  "data": {
    "id": "dt_task_abc123",
    "status": "cancelled",
    "cancelledAt": "2026-02-20T10:00:05Z"
  }
}
⚠️

Cancellation is best-effort for running tasks. The DELETE method returns immediately, but the worker may take a few seconds to stop processing.

Create Batch

POST /api/tasks/batch

Create multiple tasks in a single request.

Request Body

{
  "tasks": [
    { "prompt": "Summarize document A", "model": "sonnet" },
    { "prompt": "Summarize document B", "model": "sonnet" },
    { "prompt": "Summarize document C", "model": "sonnet" }
  ]
}

Response

{
  "success": true,
  "data": {
    "batchId": "dt_batch_xyz789",
    "tasks": [
      { "id": "dt_task_001", "status": "pending" },
      { "id": "dt_task_002", "status": "pending" },
      { "id": "dt_task_003", "status": "pending" }
    ],
    "total": 3
  }
}

Webhook Callback

When a task with callbackUrl completes, the API sends a POST request:

{
  "event": "task.completed",
  "taskId": "dt_task_abc123",
  "status": "completed",
  "output": "...",
  "usage": { "input": 1200, "output": 856 },
  "completedAt": "2026-02-20T10:00:04Z",
  "signature": "sha256=abc123..."
}

Verify the webhook signature:

import { createHmac } from 'crypto';
 
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(payload).digest('hex');
  return expected === signature;
}

Next Steps

AuthenticationPlans