> ## Documentation Index > Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a subtask > Appends one subtask to a Task group at the next position with status `todo`. Works in any group status except `completed` and `cancelled` (`tasks.group_closed`). `deliverables` is a list of at most five typed items the subtask must deliver, each with a unique slug `id`, a `type`, and a `description`: `file` adds `path` (a path or glob) and `change` (`created`, `modified`, or `any`); `command` adds `command`, an optional `directory` (default `.`), an optional boolean `fails_on_base`, and optional `paths` (workspace-relative file paths, not globs). Only `command` accepts `fails_on_base` and `paths`. With `fails_on_base: true`, `paths` must contain at least one file, and the command must fail on the start commit before it passes on the working tree; omitted `fails_on_base` is stored as false. `review` adds nothing. Orbit verifies file and command deliverables at handoff, and the reviewer confirms review deliverables. Outside `backlog`, a subtask needs at least one deliverable (`tasks.subtask_deliverables_missing`). Served by the Node that holds the group's Instance, or by the Gateway for a group without one. Returns `extension.disabled` while the extension is off. ## OpenAPI ````yaml /openapi.json post /api/v1/task-groups/{group}/tasks openapi: 3.1.0 info: title: Orbit Gateway API version: v1 description: >- The HTTP API of the active Orbit Gateway. The CLI and the PHP SDK send every fleet command through these endpoints over WireGuard. See [Using the API](/api/overview) for transport, authentication, envelopes, and errors. servers: - url: https://gateway.orbit description: >- The active Gateway on the private WireGuard network, resolved by Orbit private DNS. security: [] tags: - name: Gateway description: >- Status and trust of the active Gateway, and the releases of the Gateway itself. - name: Nodes description: Machines in the fleet, their roles, access grants, and storage settings. - name: Clusters description: Groups of Nodes with one Router and one development TLD. - name: Firewall description: Named UFW rules on one Node. - name: Fleet rollout description: >- The rollout of each verified Gateway release to the managed Nodes, and its catch-up. - name: Tools description: Packages that Orbit installs on a Node through a Tool Manager. - name: Metrics description: The Prometheus and Grafana role and its exporters. - name: GitHub App description: The Gateway's own read-only GitHub App and the accounts that installed it. - name: Analytics description: >- The analytics role, its Plausible version, and the Stats API key the Gateway uses to read visits. - name: Projects description: Repository records with one type, default branch, and web root each. - name: Instances description: Development checkouts and production releases of a Project on one Node. - name: Environment description: Stored Instance environment configuration and its .env projection. - name: Routes description: Domains that reach an Instance. - name: Database connections description: The registry of mysql, pgsql, and sqlite connections. - name: Processes description: >- systemd services and Docker containers owned by an Instance, a Node, or a Project definition. - name: Schedules description: Recurring commands run by native systemd timers. - name: Annotations description: Instance annotations, T3 delivery, and replayable status events. - name: Tasks description: Commander feature groups and ordered subtasks. - name: Extensions description: Gateway-owned extension switches. - name: Doctor description: Verify-only drift checks across the fleet. - name: Activities description: The Gateway log of authorized commands. - name: Operations description: >- Long operations, such as an Instance deploy, that run on the Gateway queue as named steps. - name: proxycli description: CLIProxyAPI quota snapshots, provider pools, and account controls. - name: Vaultwarden description: The copy of database credentials into a Vaultwarden collection. - name: Conn description: >- Profiles, shared workspace settings, registered T3 servers, and the pairing links the Gateway mints on them for each Node. - name: Realtime description: >- The record-change event feed broadcast to Reverb, its channel authorization, and Reverb connection discovery. - name: Node callbacks description: Endpoints that managed Nodes and Caddy call; operators do not call them. paths: /api/v1/task-groups/{group}/tasks: post: tags: - Tasks summary: Create a subtask description: >- Appends one subtask to a Task group at the next position with status `todo`. Works in any group status except `completed` and `cancelled` (`tasks.group_closed`). `deliverables` is a list of at most five typed items the subtask must deliver, each with a unique slug `id`, a `type`, and a `description`: `file` adds `path` (a path or glob) and `change` (`created`, `modified`, or `any`); `command` adds `command`, an optional `directory` (default `.`), an optional boolean `fails_on_base`, and optional `paths` (workspace-relative file paths, not globs). Only `command` accepts `fails_on_base` and `paths`. With `fails_on_base: true`, `paths` must contain at least one file, and the command must fail on the start commit before it passes on the working tree; omitted `fails_on_base` is stored as false. `review` adds nothing. Orbit verifies file and command deliverables at handoff, and the reviewer confirms review deliverables. Outside `backlog`, a subtask needs at least one deliverable (`tasks.subtask_deliverables_missing`). Served by the Node that holds the group's Instance, or by the Gateway for a group without one. Returns `extension.disabled` while the extension is off. operationId: tasks-subtask-create parameters: - name: group in: path required: true schema: type: integer minimum: 1 description: Numeric Task group ID. requestBody: required: true content: application/json: schema: type: object properties: title: type: string maxLength: 160 description: Short name of the step brief: type: string maxLength: 8000 description: Goal and acceptance of the step topology: type: array maxItems: 2 items: type: string pattern: ^(?:app-dev|app-prod|app-prod-2)(?:\+ingress)?$(?![\s\S]) maxLength: 64 description: >- JSON array of required workload nodes; [] removes declarations deliverables: type: array maxItems: 5 items: type: object additionalProperties: false properties: id: type: string pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$(?![\s\S]) maxLength: 64 type: type: string enum: - file - command - review description: type: string maxLength: 500 path: type: string maxLength: 500 description: Conditionally required. change: type: string enum: - created - modified - any description: Conditionally required. fails_on_base: type: boolean command: type: string maxLength: 1000 description: Conditionally required. directory: type: string maxLength: 500 paths: type: array maxItems: 100 items: type: string maxLength: 500 required: - id - type - description description: JSON file with an array of typed deliverables for the step required: - title - brief additionalProperties: false responses: '200': description: The request succeeded; an exact retry returned the existing record. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Task' meta: $ref: '#/components/schemas/Meta' required: - data - meta '201': description: Created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Task' meta: $ref: '#/components/schemas/Meta' required: - data - meta '403': description: >- The caller is not an active WireGuard peer (`peer.identity_unknown`) or lacks Node access to the target (`node_access.required`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No record matches the path parameters. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- A guard refused the change and the Gateway changed nothing; `error.code` names the guard. A disabled extension returns HTTP 409 (`extension.disabled`). content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The JSON body is not an object, has duplicate or unknown members, or fails validation (`validation.failed`). content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: curl source: > curl -sS -X POST "https://gateway.orbit/api/v1/task-groups/1/tasks" \ --cacert /path/to/orbit-root-ca.pem \ -H 'Accept: application/json' \ -H 'X-Orbit-Request-Id: 9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81' \ -H 'Content-Type: application/json' \ -d '{"title": "Absorb Commander", "brief": "Persist groups. Accept when create and list work.", "topology": ["example"], "deliverables": [{"id": "example", "type": "file", "description": "example"}]}' - lang: php label: PHP SDK source: > send(new CreateSubtaskRequest(groupId: 1, title: 'value', brief: 'value'))->dto(); components: schemas: Task: type: object properties: id: type: integer task_group_id: type: integer position: type: integer title: type: string brief: type: string deliverables: type: array items: type: object topology: type: array items: type: string status: type: string enum: - todo - reserved - running - reviewing - completed - failed - cancelled implementer_agent_thread_id: type: - integer - 'null' tokens: type: - integer - 'null' line_diff: type: - integer - 'null' lines_added: type: - integer - 'null' lines_deleted: type: - integer - 'null' duration_ms: type: - integer - 'null' questions: type: integer escalations: type: integer type: type: string enum: - implementation - annotation - final_review target_thread_id: type: - string - 'null' completion_summary: type: - string - 'null' check: oneOf: - $ref: '#/components/schemas/TaskCheck' - type: 'null' assistance_requested: type: boolean assistance_kind: type: - string - 'null' enum: - direction - failure - null assistance_question: type: - string - 'null' assistance_reason: type: - string - 'null' fixup_problem: type: - string - 'null' Meta: type: object properties: request_id: type: string format: uuid description: >- The request ID the Gateway assigned or accepted; the same value is in the `X-Orbit-Request-Id` response header and in the Activity record. required: - request_id Error: type: object properties: error: type: object properties: code: type: string description: >- Stable error code, namespaced by family, such as `node.not_active` or `route.target_conflict`. message: type: string description: >- Safe message without credentials, environment values, or remote output. details: type: object additionalProperties: true description: >- Bounded, redacted details such as the conflicting record IDs or the failed validation rule. request_id: type: string format: uuid required: - code - message required: - error TaskCheck: type: object properties: id: type: integer kind: type: string enum: - baseline - handoff - base_merge status: type: string enum: - running - passed - failed - changed - lost - cancelled started_at: type: string finished_at: type: - string - 'null' exit_code: type: - integer - 'null' changed_paths: type: array items: type: string failed_step: type: - string - 'null' output: type: - string - 'null' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.