Skip to main content
POST
Create an objective
Creates a DRAFT objective owned by the company or an org unit. Send title (1–200 characters, not blank), ownerKind (company or orgUnit), ownerRefId (recorded as sent), and optionally description (up to 4,000 characters), parentObjectiveId and targetDate (epoch milliseconds). A machine never names a worker owner. A parentObjectiveId that does not exist is 404 resource_missing. The credential needs both the objectives:read and objectives:manage scopes, and objectives:read and objectives:manage granted at the deployment root; otherwise 403 permission_denied names the missing permission. The body is strict: unknown fields are 400 bad_request. Success is 201 with the Objective. Without an Idempotency-Key, repeating a create creates a second objective. 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 objectives.

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 DRAFT objective owned by the company or an org unit. Unknown fields are refused.

title
string
required

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

Maximum string length: 200
ownerKind
enum<string>
required

Who owns the objective. A machine never names a worker owner.

Available options:
company,
orgUnit
ownerRefId
string
required

The owning company or org unit identifier, recorded as sent.

Required string length: 1 - 200
description
string

At most 4,000 characters.

Maximum string length: 4000
parentObjectiveId
string

The parent objective ID, as the objective reads return it.

Minimum string length: 1
targetDate
number

When the objective is due, epoch milliseconds.

Response

Create an objective

data
object
required
meta
object
required