Skip to main content
POST
Create a pod
Creates an active pod managed by managingOrgUnitId, with a name unique among that unit’s active pods (otherwise 409 ending (POD_NAME_CONFLICT)) and an optional description. Returns 201 with the new pod. A managing org unit that does not exist, is a customer organization or sits under one returns 404 ending (MANAGING_ORG_UNIT_NOT_FOUND). The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the written row; otherwise 403 naming workforce:read, and nothing changes. workforce:manage must be held at the platform scope. Send an Idempotency-Key to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform workforce:manage and the pod’s visibility still hold, 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

Body

application/json
name
string
required

Unique among the managing unit's active pods.

Minimum string length: 1
managingOrgUnitId
string
required

The org unit that manages the pod.

Minimum string length: 1
description
string

Response

Success

data
object
required
meta
object
required