---
title: "Create a new task"
method: POST
path: "/api/tasks"
tags: ["Tasks"]
---

# Create a new task

`POST /api/tasks`

## Request body

- object
  - `task` string, required
  - `agentId` string
  - `taskType` string
  - `tags` string[]
  - `priority` integer
  - `dependsOn` string[]
  - `offeredTo` string
  - `dir` string
  - `parentTaskId` string
  - `key` string — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
  - `source` 'mcp' | 'slack' | 'api' | 'ui' | 'github' | 'gitlab' | 'agentmail' | 'system' | 'schedule' | 'workflow' | 'linear' | 'jira'
  - `outputSchema` object
  - `contextKey` string
  - `requestedByUserId` string
  - `model` string
  - `modelTier` 'smol' | 'regular' | 'smart' | 'ultra'
  - `effort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

## Response `201`

Task created

## Other responses

- `400` — Validation error

## Changes

- **2026-07-11** `f1022d5edb0d` — 1 info
  - added the new optional request property `key`
- **2026-07-10** `5b7df66bb887` — 1 info
  - added the new `max` enum value to the request property `effort`
- **2026-07-02** `0c910612f9ac` — 1 breaking, 1 warning
  - removed the enum value `max` of the request property `effort`
  - removed the request property `key`

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/tasks/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/92a1dcbd2fc7/schema)