Skip to navigation
API ReferenceOkr

Create Objective

Anybody may create an objective, for anybody in the workspace and any of its teams: a key, or a signed-in session as its person, who is then its creator, who may always see and change it, whoever it belongs to. A Viewer of OKR Hub creates none (403 viewer_only). Its key results may come with it in keyResults (which needs keyResults:write too), or be added afterwards with createKeyResult. The activity feed says it was created, for a key under the name of whoever made the key.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
titlestringRequired

Trimmed; never blank, at most 500 characters.

yearintegerRequired
The fiscal year, 2000 to 2100.
descriptionstringOptional
periodenumOptional
Allowed values:
quarterintegerOptional
visibilityenumOptional
Public objectives are browsable by everyone in the workspace. Private ones are visible to their owner, the members of the owning team, and whoever created them, whoever they belong to. The owners of its key results see it too.
Allowed values:
weightdoubleOptional

0.01 to 100; defaults to 1.

draftbooleanOptional
Defaults to false.
sortOrderintegerOptional

Its place in the workspace’s order; after every other objective when left out.

teamIdstringOptional
ownerUserIdstringOptional
keyResultslist of objectsOptional

Its key results, at most 50, made with it in this order; each as createKeyResult takes one, a first score recorded as a check-in. Sending any needs the keyResults:write scope as well. An owner from outside the workspace refuses the whole objective.

Response

This endpoint returns an object.
idstring
organizationIdstring
titlestring
periodenum
Allowed values:
yearinteger
The fiscal year, 2000 to 2100, named by the year its Q1 falls in.
visibilityenum
Public objectives are browsable by everyone in the workspace. Private ones are visible to their owner, the members of the owning team, and whoever created them, whoever they belong to. The owners of its key results see it too.
Allowed values:
weightdouble
Relative weight when objectives roll up into an average, 0.01 to 100. One carrying twice the weight moves the average twice as much.
keyResultslist of objects
draftboolean

Still being worked out, not yet agreed. A label only: a draft is seen, scored, rolled up and checked in on like any other.

sortOrderinteger
Its place in the workspace's order of objectives, which is set by hand and which every list follows within a period.
archivedboolean
createdAtdatetime
updatedAtdatetime
descriptionstringOptional
quarterintegerOptional

1-4 for a quarterly objective, absent for an annual one.

teamobjectOptional

The team it belongs to. Absent, with owner, for an objective with no owner.

teamIdstringOptional
ownerobjectOptional

The person it belongs to. Absent, with team, for an objective with no owner.

ownerUserIdstringOptional
scoredoubleOptional

The weighted average of its key results’ grades, or absent when none has been scored. Absent rather than 0.0 on purpose: an unscored objective has not failed, and a zero would say it had.

Errors

402
Subscription Required Error
403
Forbidden Error
422
Validation Error
429
Too Many Requests Error