Skip to main content
POST
Create a workstream
Creates an ACTIVE workstream. Send name (1–200 characters, not blank), ownerKind (company, department or team), ownerRefId (recorded as sent), and optionally description (up to 4,000 characters). The credential needs both the projects:manage and objectives:read scopes, and objectives:read and projects:manage granted at the deployment root; otherwise 403 permission_denied names the first missing permission and nothing is written. The body is strict: unknown fields are 400 bad_request. Success is 201 with the PlanningWorkstream. Without an Idempotency-Key, repeating a create creates a second record. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise 409 idempotency_result_unavailable, and the write never runs twice. Reconcile an unknown outcome with List workstreams.

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

Body

application/json

An ACTIVE workstream owned by the company, a department or a team. Unknown fields are refused.

name
string
required

Stored exactly as sent; at most 200 characters and not blank.

Maximum string length: 200
ownerKind
enum<string>
required

Who owns it: the company, a department or a team. Never a person.

Available options:
company,
department,
team
ownerRefId
string
required

The owning company, department or team identifier, recorded as sent.

Required string length: 1 - 200
description
string

At most 4,000 characters.

Maximum string length: 4000

Response

Create a workstream

data
object
required
meta
object
required