Skip to main content
POST
Transition a project
Moves a project through its status machine. The body is strict: id and status. ARCHIVED archives the project and records archivedAt; ARCHIVED → PLANNING revives it and clears archivedAt. A disallowed move, including a move to the current status, answers 409 invalid_state with a message naming the allowed targets, and changes nothing. Authority is the same as Update project: 404 unless the caller holds projects:read at the project’s home, 403 without projects:manage there. Success is 200 with the post-write Project. Without an Idempotency-Key, repeating a completed transition answers 409 invalid_state. With a key, a same-key retry within 24 hours returns the recorded result while the caller’s scopes still include projects:read and it may still read and change the project; 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

projectId
string
required

The project ID, as GET /api/v2/projects/get returns it.

Minimum string length: 1

Body

application/json

Move a project through the canonical status machine. ARCHIVED archives the project; ARCHIVED→PLANNING revives it.

status
enum<string>
required

The target status. PLANNING→ACTIVE|ARCHIVED, ACTIVE→ON_HOLD|COMPLETE|ARCHIVED, ON_HOLD→ACTIVE|ARCHIVED, COMPLETE→ARCHIVED|ACTIVE, ARCHIVED→PLANNING (revive).

Available options:
PLANNING,
ACTIVE,
ON_HOLD,
COMPLETE,
ARCHIVED

Response

Success

data
object
required
meta
object
required