> ## 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. # Complete a Task group > Completes a settling Task group or a VM group waiting for review without reading GitHub, or a running or reviewing group whose watched pull request has merged or closed. Stores the ended state in watched_pr_completion before cancelling open subtasks and completing the group in one transaction. Stops running agents and checks as subtask cancel does. Workspace and Route removal runs after the commit. Resume and completed-group cleanup retries do not read GitHub. A removal failure leaves the group completed with its Instance attached and asks for assistance. Idempotent. Requires Gateway access. Returns `extension.disabled` while the extension is off, `tasks.not_settling` when the group is not ready (including a missing, open, or unreadable watched PR without a completion receipt), and `tasks.subtask_interrupt_failed` when an agent or check cannot be stopped. ## OpenAPI ````yaml /openapi.json post /api/v1/task-groups/{group}/complete 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: 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}/complete: post: tags: - Tasks summary: Complete a Task group description: >- Completes a settling Task group or a VM group waiting for review without reading GitHub, or a running or reviewing group whose watched pull request has merged or closed. Stores the ended state in watched_pr_completion before cancelling open subtasks and completing the group in one transaction. Stops running agents and checks as subtask cancel does. Workspace and Route removal runs after the commit. Resume and completed-group cleanup retries do not read GitHub. A removal failure leaves the group completed with its Instance attached and asks for assistance. Idempotent. Requires Gateway access. Returns `extension.disabled` while the extension is off, `tasks.not_settling` when the group is not ready (including a missing, open, or unreadable watched PR without a completion receipt), and `tasks.subtask_interrupt_failed` when an agent or check cannot be stopped. operationId: tasks-complete parameters: - name: group in: path required: true schema: type: integer minimum: 1 description: Numeric Task group ID. requestBody: required: false content: application/json: schema: type: object additionalProperties: false responses: '200': description: The request succeeded. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TaskGroup' 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: >- The tasks extension is disabled (`extension.disabled`) or the Task group is not ready to complete (`tasks.not_settling`). Running or reviewing groups need an ended watched pull request or a stored completion receipt. 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' '502': description: >- A running agent or check could not be stopped (`tasks.subtask_interrupt_failed`). The completion receipt is kept for retry; the group and its open subtasks remain open. 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/complete" \ --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 '{}' - lang: php label: PHP SDK source: > send(new CompleteTaskGroupRequest(groupId: 1))->dto(); components: schemas: TaskGroup: type: object properties: id: type: integer project_id: type: integer project: type: string project_code: type: string taskable_type: type: - string - 'null' taskable_id: type: - integer - 'null' title: type: string brief: type: string status: type: string enum: - backlog - todo - reserved - running - reviewing - settling - waiting_for_review - completed - failed - cancelled reviewer_agent_thread_id: type: - integer - 'null' pr_url: type: - string - 'null' watched_pr_url: type: - string - 'null' watched_pr_number: type: - integer - 'null' watched_pr_state: type: - string - 'null' notify_coder: type: boolean assistance_requested: type: boolean assistance_kind: type: - string - 'null' enum: - direction - failure - null assistance_question: type: - string - 'null' assistance_reason: type: - string - 'null' implementer_model: type: string reviewer_model: type: string 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 tasks: type: array items: $ref: '#/components/schemas/Task' execution_mode: type: string enum: - managed - existing_thread capacity_wait_reason: type: - string - 'null' vm_power: type: - string - 'null' enum: - running - stopped - destroyed - null preview: type: boolean review_and_merge: oneOf: - $ref: '#/components/schemas/TaskReviewAndMerge' - type: '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 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' TaskReviewAndMerge: type: object properties: enabled: type: boolean pr_branch: type: - string - 'null' merge_status: type: - string - 'null' enum: - waiting - refused - merged - null merge_reason: type: - string - 'null' merged_sha: type: - string - 'null' reviewed_commits: type: array items: $ref: '#/components/schemas/TaskReviewedCommit' TaskCheck: type: object properties: id: type: integer kind: type: string enum: - baseline - handoff 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' TaskReviewedCommit: type: object properties: sha: type: string source: type: string enum: - orbit_push - pull_request_review review_task_id: type: - integer - 'null' pushed_at: type: - string - 'null' github_review_id: type: - integer - 'null' recorded_at: type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.