Tasks API

Create, schedule, and manage agent tasks. Tasks are units of work assigned to agents -- they can be one-time, scheduled (cron), or triggered by events.

Base path: /api/v1/tasks

Endpoints

List Tasks

GET /api/v1/tasks

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)
`agentId`	string	Filter by assigned agent
`teamId`	string	Filter by team
`status`	string	`pending`, `running`, `completed`, `failed`, `cancelled`
`type`	string	`one_time`, `scheduled`, `triggered`

Response:

{
  "tasks": [
    {
      "id": "task_abc123",
      "name": "Daily Pipeline Briefing",
      "description": "Generate a summary of pipeline changes",
      "agentId": "agent_456",
      "teamId": "team_789",
      "type": "scheduled",
      "schedule": "0 9 * * 1-5",
      "status": "completed",
      "lastRunAt": "2026-04-12T09:00:00Z",
      "nextRunAt": "2026-04-13T09:00:00Z",
      "createdAt": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 15
}

Create Task

POST /api/v1/tasks

Field	Type	Required	Description
`name`	string	Yes	Task name
`description`	string	Yes	What the agent should do
`agentId`	string	Yes	Assigned agent
`teamId`	string	No	Team context
`appId`	string	No	Workspace scope
`type`	string	No	`one_time` (default), `scheduled`, `triggered`
`schedule`	string	No	Cron expression (required for `scheduled` type)
`priority`	string	No	`low`, `medium` (default), `high`, `critical`
`dueAt`	string	No	ISO deadline for one-time tasks
`input`	object	No	Additional context for the agent

Example -- Scheduled Task:

{
  "name": "Weekly Compliance Report",
  "description": "Audit all agent actions from the past week and generate a compliance summary",
  "agentId": "agent_compliance",
  "type": "scheduled",
  "schedule": "0 8 * * 1",
  "priority": "high"
}

Response (201):

{
  "id": "task_new456",
  "name": "Weekly Compliance Report",
  "status": "pending",
  "type": "scheduled",
  "schedule": "0 8 * * 1",
  "nextRunAt": "2026-04-14T08:00:00Z",
  "createdAt": "2026-04-12T15:00:00Z"
}

Get Task

GET /api/v1/tasks/:id

Returns full task details including run history and output.

Run Task

POST /api/v1/tasks/:id/run

Manually trigger a task execution (even for scheduled tasks). The agent executes the task description as a message.

Field	Type	Description
`input`	object	Optional override context

Response:

{
  "runId": "run_789",
  "status": "running",
  "startedAt": "2026-04-12T15:30:00Z"
}

Cancel Task

POST /api/v1/tasks/:id/cancel

Cancels a running task. If the agent is mid-execution, it stops at the next tool boundary.

Retry Task

POST /api/v1/tasks/:id/retry

Re-runs a failed task with the same configuration.

Delete Task

DELETE /api/v1/tasks/:id

Removes the task. Scheduled tasks stop recurring. Run history is preserved in audit logs.

Task Runs

GET /api/v1/tasks/:id/runs

Returns execution history for a task.

Response:

{
  "runs": [
    {
      "id": "run_001",
      "status": "completed",
      "output": "Weekly compliance report generated. 3 policy violations flagged.",
      "cost": 0.012,
      "duration": 8500,
      "tokenUsage": { "inputTokens": 3200, "outputTokens": 890 },
      "startedAt": "2026-04-07T08:00:00Z",
      "completedAt": "2026-04-07T08:00:08Z"
    }
  ]
}

Get Run Details

GET /api/v1/tasks/runs/:runId

Returns full details for a specific run including tool calls and intermediate steps.

Approval Queue

GET /api/v1/tasks/pending-approval

Returns tasks waiting for human approval before execution.

POST /api/v1/tasks/:id/approve
POST /api/v1/tasks/:id/reject

Approve or reject a pending task. Rejected tasks are marked as cancelled.

Common Cron Patterns

Pattern	Schedule
`0 9 * * 1-5`	Weekdays at 9:00 AM
`0 /2 * *`	Every 2 hours
`0 8 * * 1`	Mondays at 8:00 AM
`0 0 1 * *`	First of every month at midnight
`/30 * * *`	Every 30 minutes

Common Patterns

Create a Daily Briefing

curl -X POST https://app.meetloyd.com/api/v1/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Pipeline Briefing",
    "description": "Summarize new leads, deal updates, and upcoming meetings for today. Post the briefing to the #sales Slack channel.",
    "agentId": "agent_sales_lead",
    "type": "scheduled",
    "schedule": "0 8 * * 1-5",
    "priority": "high"
  }'

One-Time Research Task

curl -X POST https://app.meetloyd.com/api/v1/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor Analysis: Acme Corp",
    "description": "Research Acme Corp recent announcements, product changes, and market positioning. Create a 1-page summary document.",
    "agentId": "agent_research",
    "type": "one_time",
    "priority": "medium",
    "dueAt": "2026-04-15T17:00:00Z"
  }'