---
title: "Apply a Factory Branch sync"
method: POST
path: "/factory/{uid}/branches/{branch_uid}/apply"
tags: ["Factories"]
---

# Apply a Factory Branch sync

`POST /factory/{uid}/branches/{branch_uid}/apply`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/factory/{uid}/branches/{branch_uid}/apply`
- Auth: HTTP bearer

Requires Factory view and source.apply. Queues a Temporal
reconciliation to the current registered head and returns before
synchronization completes. Publication requires complete projection
authorization. Duplicate requests converge. Read branch status to
observe completion or source errors.
Does not accept a target SHA or repository, create tracking, revive
retired identity, or replace settings on existing runs.
Requires factory_branches.

## Path parameters

- `uid` string, required
- `branch_uid` string, required

## Response `202`

Synchronization accepted; the returned state is SYNCING, not a verified source observation.

- FactoryBranchStatus: Read-only observation of an existing Branch. UNKNOWN means the current source could not be verified, never permission to execute. Lifecycle SHA fields describe current synchronization, not a run's historical creation revision.
  - `uid` string, required
  - `factory_uid` string, required
  - `branch` string, required
  - `source_generation` string, required
  - `state` 'UNSYNCED' | 'SYNCING' | 'FRESH' | 'STALE' | 'FAILED' | 'UNKNOWN' | 'DELETED', required
  - `last_success_sha` string, nullable, required
  - `current_head_sha` string, nullable, required
  - `last_synced_at` string, date-time, nullable, required
  - `latest_attempt` FactorySyncItem, required: A single factory sync history/status row.
    - `id` integer, required: Internal sync row ID.
    - `factory_uid` string, required: Public UID of the factory.
    - `target_sha` string, required: Target commit SHA for the sync attempt.
    - `trigger` 'webhook' | 'explicit_apply' | 'anti_entropy' | 'source_link', required: What initiated the sync attempt.
    - `status` 'running' | 'success' | 'failed' | 'noop', required: Outcome of a sync attempt.
    - `plan_summary` string, nullable: Optional human-readable plan summary for the sync.
    - `diagnostics` string: Raw persisted structured diagnostics JSON for the sync attempt (parse errors, dependency failures, etc.). Empty when the sync had no diagnostics. This POC field carries the persisted JSON string verbatim; a future revision may replace it with a structured schema.
    - `created_at` string, date-time, required: Time the sync row was created.
    - `updated_at` string, date-time, required: Time the sync row was last updated.
  - `freshness_checked_at` string, date-time, required
  - `last_error` Error, required: Error response following RFC 7807 (Problem Details for HTTP APIs), using the `application/problem+json` content type. Includes backward-compatible extension members; additional ones (e.g., `auth_url`, `provider`) may be present depending on the error code.
    - `type` string, uri, required: A URI reference that identifies the problem type (RFC 7807). Documentation: `https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/{error_code}` See PlatformErrorCode for the list of possible error codes.
    - `title` string, required: A short, human-readable summary of the problem type (RFC 7807)
    - `status` integer, required: The HTTP status code for this occurrence of the problem (RFC 7807)
    - `detail` string: A human-readable explanation specific to this occurrence of the problem (RFC 7807)
    - `instance` string: The request path that generated this error (RFC 7807)
    - `error` string, required: Human-readable error message combining title and detail. Backward-compatible extension member for older clients.
    - `retryable` boolean: Whether the request can be retried. When true, the error is transient and the request may be retried. When false, retrying without addressing the underlying cause will not succeed.
    - `trace_id` string: OpenTelemetry trace ID for debugging and support requests
    - `provider` string: External provider that requires authorization, such as `linear`.
    - `auth_url` string, uri: URL where the caller can reconnect the external provider.

## Other responses

- `401`: Authentication required
- `403`: Factory access is not enabled for the authenticated principal
- `404`: Hidden Factory, unknown or cross-Factory tracking, or disabled Branch surface
- `409`: Classified conflict with reason branch_sync_pending, branch_head_moved, factory_source_changed, branch_deleted, or factory_scope_unavailable. Pending synchronization, moving heads, and source changes are retryable; deleted or unavailable identity is not.
- `500`: Retryable resource_unavailable for source, synchronization, or database failure

## Changes

- **2026-10-21** `7ee3ba55debc`: 1 breaking, 2 info
  - removed the success response with the status `200`
  - removed the non-success response with the status `400`
  - added the success response with the status `202`
- **2026-10-19** `2c45dcc0a13e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/factory/:uid/branches/:branch_uid/apply/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)