REST API Overview

The DevTeam Orchestrator exposes a RESTful HTTP API for managing tasks, plans, templates, and HITL approvals. All endpoints are available at https://devteam.marsala.dev/api/.

Base URL

https://devteam.marsala.dev/api

All endpoints are prefixed with /api. For self-hosted instances, replace the domain with your server address.

Authentication

All requests must include either an API key or a JWT token:

# API Key (header)
curl -H "Authorization: Bearer dtk_live_abc123" \
  https://devteam.marsala.dev/api/tasks
 
# API Key (query parameter)
curl "https://devteam.marsala.dev/api/tasks?api_key=dtk_live_abc123"

See Authentication for full details.

Content Type

All request and response bodies use JSON:

Content-Type: application/json
Accept: application/json

Endpoint Summary

Tasks

Method	Endpoint	Description
`POST`	`/api/tasks`	Create a new task
`GET`	`/api/tasks`	List tasks
`GET`	`/api/tasks/:id`	Get task details
`DELETE`	`/api/tasks/:id`	Cancel a task
`POST`	`/api/tasks/batch`	Create multiple tasks

Plans

Method	Endpoint	Description
`POST`	`/api/plans`	Create a plan
`GET`	`/api/plans`	List plans
`GET`	`/api/plans/:id`	Get plan details
`POST`	`/api/plans/:id/execute`	Execute a plan
`GET`	`/api/plans/executions/:id`	Get execution status
`DELETE`	`/api/plans/executions/:id`	Cancel execution

Templates

Method	Endpoint	Description
`GET`	`/api/templates`	List templates
`GET`	`/api/templates/:id`	Get template details
`POST`	`/api/templates`	Create a template
`POST`	`/api/templates/:id/deploy`	Deploy a template

HITL

Method	Endpoint	Description
`GET`	`/api/hitl/pending`	List pending approvals
`POST`	`/api/hitl/:taskId/approve`	Approve a task
`POST`	`/api/hitl/:taskId/reject`	Reject a task
`GET`	`/api/hitl/:taskId/history`	Get approval history

System

Method	Endpoint	Description
`GET`	`/api/health`	Health check
`GET`	`/api/workers`	List workers
`GET`	`/api/metrics`	Prometheus metrics

Request Format

curl -X POST https://devteam.marsala.dev/api/tasks \
  -H "Authorization: Bearer dtk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize this document",
    "model": "sonnet",
    "queue": "default"
  }'

Response Format

All responses follow a consistent envelope format:

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-20T10:00:00Z",
    "duration": 42
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'prompt' is required",
    "details": {
      "field": "prompt",
      "rule": "required"
    }
  },
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2026-02-20T10:00:01Z"
  }
}

Pagination

List endpoints support cursor-based pagination:

# First page
curl "https://devteam.marsala.dev/api/tasks?limit=20"
 
# Next page
curl "https://devteam.marsala.dev/api/tasks?limit=20&offset=20"

Response includes pagination metadata:

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

Rate Limiting

Plan	Requests/min	Concurrent Tasks
Free	60	5
Pro	300	50
Enterprise	1000	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1708420860

When rate limited, the API returns HTTP 429 with a Retry-After header. The SDK handles this automatically with exponential backoff.

Next Steps

Authentication -- JWT auth and RBAC
Tasks API -- Task management endpoints

Guides Authentication