--- title: "Stop a factory task" method: POST path: "/factory/{uid}/tasks/{task_uid}/cancel" tags: ["Factories"] --- # Stop a factory task `POST /factory/{uid}/tasks/{task_uid}/cancel` ## Request - Base URL: `https://app.warp.dev/api/v1` - URL: `https://app.warp.dev/api/v1/factory/{uid}/tasks/{task_uid}/cancel` - Auth: HTTP bearer Cancel the task's current top-level run and move the task to CANCELLED. Every non-terminal descendant of the root run is cancelled as well. ## Path parameters - `uid` string, required - `task_uid` string, required ## Response `200` Task stopped. The response reflects the refreshed task, including its current run and stage. - FactoryTask: A factory task: the unit of work in a factory, bound to the agent conversation that owns it. - `config_source` FactoryConfigSource: Branch namespace and registered source-generation identity derived from the run's execution Agent and required root/Branch associations. Omitted for production or unavailable provenance; omission does not establish production scope. No historical configuration revision or retention guarantee is provided. - `branch` string, required: Case-sensitive named head, without refs/heads/. - `branch_uid` string, required: Immutable tracking namespace UID. - `source_generation` string, required: Fingerprint of the registered source generation. - `uid` string, required: Public UID of the task. - `factory_uid` string, required: Public UID of the factory the task belongs to. Fixed at creation. - `conversation_id` string, required: UUID of the agent conversation the task is bound to. - `run_id` string, required: ID of the bound conversation's most recent run at task creation. This is a provenance snapshot and is not updated afterward; consumers needing the conversation's live latest run should resolve it via the conversation. - `author` RunCreatorInfo - `type` 'user' | 'service_account': Type of the creator principal - `uid` string: Unique identifier of the creator - `display_name` string: Display name of the creator - `email` string: Email address of the creator - `photo_url` string, uri: URL to the creator's photo - `title` string, required: Human-readable title of the task. - `ticket_source` string: Canonical ticket source from the bound run. Present on list responses only when full_list=true and ticket metadata exists. - `ticket_id` string: Canonical ticket ID from the bound run. Present on list responses only when full_list=true and ticket metadata exists. - `description` string, nullable: Optional description of the task. - `stage` 'TRIAGE' | 'SPEC' | 'IMPLEMENT' | 'REVIEW' | 'COMPLETE' | 'CANCELLED', required: Lifecycle stage of a factory task, mirroring the seeded factory agent roles plus the terminal COMPLETE and CANCELLED states. COMPLETE and CANCELLED are terminal in intent but not enforced: any stage may be written explicitly at any time. CANCELLED is set automatically when the task's current top-level run is cancelled, regardless of that run's agent type. - `created_at` string, date-time, required: Time the task was created. - `updated_at` string, date-time, required: Time the task was last created, updated, or deleted. Artifact reporting does not bump this; new outputs appear on the next detail read. - `outputs` ArtifactItem[]: Derived outputs, newest-first: PULL_REQUEST, EXTERNAL_REFERENCE, SCREENSHOT, and FILE artifacts (video recordings are FILE artifacts). Present on single-task reads (by uid, by conversation, and by run), where outputs are derived from the task's whole run tree (every run bound to the conversation plus the runs dispatched under them). On list responses with full_list=true, outputs are derived from the bound conversation only, not the wider run tree. - union - PlanArtifact - `artifact_type` 'PLAN', required: Type of the artifact - `created_at` string, date-time, required: Timestamp when the artifact was created (RFC3339) - `data` PlanArtifactData, required - `artifact_uid` string: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint - `document_uid` string, required: Unique identifier for the plan document - `notebook_uid` string: Unique identifier for the associated notebook - `url` string, uri: URL to open the plan in Warp Drive - `title` string: Title of the plan - PullRequestArtifact - `artifact_type` 'PULL_REQUEST', required: Type of the artifact - `created_at` string, date-time, required: Timestamp when the artifact was created (RFC3339) - `data` PullRequestArtifactResponseData, required - `url` string, uri, required: URL of the pull request - `branch` string, required: Branch name for the pull request - `status` 'open' | 'draft' | 'merged' | 'closed' | 'unknown', required: Current state of the pull request as last reported by the code host's webhooks. `unknown` means Warp has no live provider record for this pull request (for example, the repository's code host integration is not connected to the run's team). - ScreenshotArtifact - `artifact_type` 'SCREENSHOT', required: Type of the artifact - `created_at` string, date-time, required: Timestamp when the artifact was created (RFC3339) - `data` ScreenshotArtifactData, required - `artifact_uid` string, required: Unique identifier for the screenshot artifact - `mime_type` string, required: MIME type of the screenshot image - `description` string: Optional description of the screenshot - FileArtifact - `artifact_type` 'FILE', required: Type of the artifact - `created_at` string, date-time, required: Timestamp when the artifact was created (RFC3339) - `data` FileArtifactData, required - `artifact_uid` string, required: Unique identifier for the file artifact - `filepath` string, required: Conversation-relative filepath for the uploaded file. Omitted on an anonymous read of a public file artifact. - `filename` string, required: Last path component of filepath - `title` string: Short, badge-visible label for the artifact. For recording artifacts, this is the agent-authored title shown in Warp web and blocklist badges. Distinct from description, which is longer and shown in detail views. - `description` string: Optional description of the file - `mime_type` string, required: MIME type of the uploaded file - `size_bytes` integer: Size of the uploaded file in bytes - `thumbnail` FileArtifactThumbnail: The companion thumbnail image of a video recording. - `download_url` string, uri, required: Stable URL of the thumbnail image. Requires authentication. - ExternalReferenceArtifact - `artifact_type` 'EXTERNAL_REFERENCE', required: Type of the artifact - `created_at` string, date-time, required: Timestamp when the artifact was created (RFC3339) - `data` ExternalReferenceArtifactData, required: Data for a generic external reference artifact. - `reference_type` string, required: Free-form category identifier for this reference (e.g. "linear_issue", "spec_link", "jira_ticket"). Used for filtering and display. - `url` string, required: Canonical URL for the reference. Used as the key for reverse lookups ("which run produced this URL?"). - `title` string: Optional human-readable label for the reference. - `metadata` object: Optional category-specific extra fields. - `current_run` FactoryTaskCurrentRun: A factory task's current top-level run, resolved from the bound conversation at read time. This differs from FactoryTask.run_id, which is a creation-time provenance snapshot and is never updated. - `run_id` string, required: ID of the task's current top-level (root) run. - `state` 'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED', required: Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: Run is actively being executed - SUCCEEDED: Run completed successfully - FAILED: Run failed - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - ERROR: Run encountered an error - CANCELLED: Run was cancelled by user - `is_run_type_cancellable` boolean, required: Whether the current run's type is eligible for cancellation via the API. State-independent; clients should also gate on state. ## Other responses - `400`: The resolved current run is already in a terminal state. - `401`: Authentication required - `403`: The caller can see the task but lacks access to its resolved current run. - `404`: Factory or task not found under this factory, or the task has no resolvable current run. - `409`: The resolved current run is PENDING and cannot be cancelled yet. Retry after a moment. - `422`: The resolved current run's type does not support server-side cancellation. - `500`: Internal server error ## Changes - **2026-10-19** `2c45dcc0a13e`: 1 breaking, 1 info - removed the required property `outputs/items/oneOf[#/components/schemas/FileArtifact]/data/thumbnail/expires_at` from the response with the `200` status - added the optional property `config_source` to the response with the `200` status - **2026-10-13** `96d1e59a65c5`: 1 info - endpoint added [Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/factory/:uid/tasks/:task_uid/cancel/post.md) --- [API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)