Skip to main content
POST
Pause a factory
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/factories/pause pauses an active factory, as the Console’s factory kill switch does: new work through the factory is blocked until it is resumed, and steps already running finish. The body is strict: id (the factory) and reason (8–1,000 characters, recorded in the audit event). Any other key is 400 bad_request. The answer is 200 with {id, status, previousStatus, changed}. Pausing a paused factory changes nothing: changed is false and no audit event is written. An archived factory is never paused, because a later resume could restore it: the answer is 409 invalid_state with The factory is archived. A factory still provisioning is never paused either, because its setup only finishes from PROVISIONING: the answer is 409 invalid_state with The factory is still provisioning; archive it instead if it must stop. You need switches:use at the factory’s home org unit; otherwise the answer is 403. A factory you cannot read answers 404 with Factory not found. switches:use is an approve-and-administer key: a Forge agent never holds it, and a Personal key that carries the scope expires sooner. The audit event names your External App or key, or a Personal key’s owner. Send an Idempotency-Key to make a retry safe: the same key and body within 24 hours returns the recorded 200 only while you still hold switches:use at the factory’s home; otherwise 409 idempotency_result_unavailable.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

factoryId
string
required

The factory to pause, resume or archive.

Minimum string length: 1

Body

application/json
reason
string
required

Why, for the audit trail.

Required string length: 8 - 1000

Response

Pause a factory

data
object
required
meta
object
required