Skip to main content
POST
Create a project
Creates a PLANNING project owned by an org unit, for an External App owned by an org unit or for a Personal key. An app owned by a person receives 403 forbidden. The body is strict: name (not blank, stored as sent), ownerKind (team or department), and optional ownerRefId, customerId, description, startDate and targetDate (epoch milliseconds). For an External App, ownerRefId defaults to the app’s owning unit and may name a unit below it; a unit outside the app’s unit answers 404 resource_missing (“Owner org unit not found”). A Personal key must name ownerRefId (otherwise 400); an unknown unit, or a unit in another id space, answers 404. A person never owns a machine-created project. ownerKind is recorded as sent, as in the Console; it is not checked against the unit’s structure type, which org units define per organization. The caller needs both projects:manage and projects:read at the owner unit; otherwise 403 forbidden. With customerId, the customer must exist (otherwise 404) and be active (otherwise 409). A customer with its own org unit homes the project there, so the caller then needs both permissions at the customer’s org unit too (otherwise 403 forbidden, and nothing is created); a customer without one leaves the project at its owner unit. The attribution is audited as the Console audits it. The credential’s scopes must include projects:read as well as projects:manage, because the success returns the project; otherwise 403 permission_denied naming projects:read, and nothing is created. Factory, objective and budget links are not accepted (unknown fields answer 400). Success is 201 with the Project. Without an Idempotency-Key, repeating a create creates a second project. With a key, a same-key retry within 24 hours returns the recorded result while your scopes still include projects:read and you may still read and change the project at its home; otherwise 409 idempotency_result_unavailable, and the create never runs twice. If an outcome is unknown, retry with the same key or find the project with List projects.

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

A project owned by an org unit: for an External App, its owning unit or one it covers; for a Personal key, the unit it names. It may name the customer it is for; factory, objective and budget links are not accepted. Unknown fields are refused.

name
string
required

The project name, stored exactly as sent; it must not be blank.

ownerKind
enum<string>
required

The kind of org unit that owns the project. A person never owns a machine-created project.

Available options:
team,
department
ownerRefId
string

The owning org unit. An External App may omit it (its owning unit) or name a unit its owning unit covers; a Personal key must name it. The project's home follows it unless the customer has its own org unit.

Minimum string length: 1
customerId
string

The active customer the project is for. A customer with its own org unit homes the project there, and the caller then needs projects:manage and projects:read at that unit too.

Minimum string length: 1
description
string
startDate
number

When the project starts, epoch milliseconds.

targetDate
number

When the project is due, epoch milliseconds.

Response

Success

data
object
required
meta
object
required