Shortcut Software Objectives API
The Objectives API from Shortcut Software — 5 operation(s) for objectives.
OpenAPI Specification
openapi: 3.0.0
info:
title: Shortcut Categories Objectives API
version: '3.0'
description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Objectives
paths:
/api/v3/objectives:
get:
responses:
'200':
description: Resource
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Objective'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: listObjectives
description: List Objectives returns a list of all Objectives and their attributes.
summary: List Objectives
tags:
- Objectives
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateObjective'
required: true
responses:
'201':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Objective'
'400':
description: Schema mismatch
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UnusableEntitlementError'
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: createObjective
description: Create Objective allows you to create a new Objective in Shortcut.
summary: Create Objective
tags:
- Objectives
/api/v3/objectives/{objective-public-id}:
get:
parameters:
- in: path
name: objective-public-id
description: The ID of the Objective.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Objective'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: getObjective
description: Get Objective returns information about a chosen Objective.
summary: Get Objective
tags:
- Objectives
put:
parameters:
- in: path
name: objective-public-id
description: The ID of the Objective.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateObjective'
required: true
responses:
'200':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Objective'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: updateObjective
description: Update Objective can be used to update Objective properties.
summary: Update Objective
tags:
- Objectives
delete:
parameters:
- in: path
name: objective-public-id
description: The ID of the Objective.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: No Content
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: deleteObjective
description: Delete Objective can be used to delete any Objective.
summary: Delete Objective
tags:
- Objectives
/api/v3/objectives/{objective-public-id}/epics:
get:
parameters:
- in: path
name: objective-public-id
description: The ID of the Objective.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Resource
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EpicSlim'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: listObjectiveEpics
description: List all of the Epics within the Objective.
summary: List Objective Epics
tags:
- Objectives
/api/v3/objectives/{objective-public-id}/health:
get:
parameters:
- in: path
name: objective-public-id
description: The unique ID of the Objective.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Health'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: getObjectiveHealth
description: Get the current health for the specified Objective.
summary: Get Objective Health
tags:
- Objectives
post:
parameters:
- in: path
name: objective-public-id
description: The unique ID of the Objective.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateObjectiveHealth'
required: true
responses:
'201':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Health'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: createObjectiveHealth
description: Create a new health status for the specified Objective.
summary: Create Objective Health
tags:
- Objectives
/api/v3/objectives/{objective-public-id}/health-history:
get:
parameters:
- in: path
name: objective-public-id
description: The unique ID of the Objective.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Resource
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Health'
'400':
description: Schema mismatch
'404':
description: Resource does not exist
'422':
description: Unprocessable
operationId: listObjectiveHealths
description: List the history of health statuses for the specified Objective, most recent first.
summary: List Objective Healths
tags:
- Objectives
components:
schemas:
Category:
description: A Category can be used to associate Objectives.
type: object
properties:
archived:
description: A true/false boolean indicating if the Category has been archived.
type: boolean
entity_type:
description: A string description of this resource.
type: string
color:
description: The hex color to be displayed with the Category (for example, "#ff0000").
pattern: ^#[a-fA-F0-9]{6}$
format: css-color
minLength: 1
type: string
nullable: true
name:
description: The name of the Category.
type: string
global_id:
description: The Global ID of the Category.
x-doc-skip: true
type: string
type:
description: The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category.
x-doc-skip: true
type: string
updated_at:
description: The time/date that the Category was updated.
type: string
format: date-time
external_id:
description: This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
type: string
nullable: true
id:
description: The unique ID of the Category.
type: integer
format: int64
created_at:
description: The time/date that the Category was created.
type: string
format: date-time
additionalProperties: false
required:
- archived
- entity_type
- color
- name
- global_id
- type
- updated_at
- external_id
- id
- created_at
CreateCategoryParams:
description: Request parameters for creating a Category with a Objective.
type: object
properties:
name:
maxLength: 128
minLength: 1
description: The name of the new Category.
type: string
color:
pattern: ^#[a-fA-F0-9]{6}$
format: css-color
description: The hex color to be displayed with the Category (for example, "#ff0000").
minLength: 1
type: string
external_id:
maxLength: 128
minLength: 1
description: This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
type: string
additionalProperties: false
required:
- name
EpicStats:
description: A group of calculated values for this Epic.
type: object
properties:
num_points_done:
description: The total number of completed points in this Epic.
type: integer
format: int64
num_related_documents:
description: The total number of documents associated with this Epic.
type: integer
format: int64
num_stories_unstarted:
description: The total number of unstarted Stories in this Epic.
type: integer
format: int64
num_stories_total:
description: The total number of Stories in this Epic.
type: integer
format: int64
last_story_update:
description: The date of the last update of a Story in this Epic.
type: string
format: date-time
nullable: true
num_points_started:
description: The total number of started points in this Epic.
type: integer
format: int64
num_points_unstarted:
description: The total number of unstarted points in this Epic.
type: integer
format: int64
num_stories_started:
description: The total number of started Stories in this Epic.
type: integer
format: int64
num_stories_unestimated:
description: The total number of Stories with no point estimate.
type: integer
format: int64
num_stories_backlog:
description: The total number of backlog Stories in this Epic.
type: integer
format: int64
num_points_backlog:
description: The total number of backlog points in this Epic.
type: integer
format: int64
num_points:
description: The total number of points in this Epic.
type: integer
format: int64
num_stories_done:
description: The total number of done Stories in this Epic.
type: integer
format: int64
additionalProperties: false
required:
- num_points_done
- num_related_documents
- num_stories_unstarted
- num_stories_total
- last_story_update
- num_points_started
- num_points_unstarted
- num_stories_started
- num_stories_unestimated
- num_stories_backlog
- num_points_backlog
- num_points
- num_stories_done
CreateObjectiveHealth:
x-doc-skip: true
type: object
properties:
status:
description: The health status of the Objective.
type: string
enum:
- At Risk
- On Track
- Off Track
- No Health
text:
description: The description of the Health status.
type: string
additionalProperties: false
required:
- status
EpicSlim:
description: EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the [Get Epic](#Get-Epic) endpoint to fetch the unabridged payload for an Epic.
type: object
properties:
app_url:
description: The Shortcut application url for the Epic.
type: string
description:
description: The Epic's description.
type: string
archived:
description: True/false boolean that indicates whether the Epic is archived or not.
type: boolean
started:
description: A true/false boolean indicating if the Epic has been started.
type: boolean
entity_type:
description: A string description of this resource.
type: string
labels:
description: An array of Labels attached to the Epic.
type: array
items:
$ref: '#/components/schemas/LabelSlim'
mention_ids:
description: '`Deprecated:` use `member_mention_ids`.'
type: array
items:
type: string
format: uuid
member_mention_ids:
description: An array of Member IDs that have been mentioned in the Epic description.
type: array
items:
type: string
format: uuid
associated_groups:
description: An array containing Group IDs and Group-owned story counts for the Epic's associated groups.
type: array
items:
$ref: '#/components/schemas/EpicAssociatedGroup'
project_ids:
description: The IDs of Projects related to this Epic.
type: array
items:
type: integer
format: int64
stories_without_projects:
description: The number of stories in this epic which are not associated with a project.
type: integer
format: int64
completed_at_override:
description: A manual override for the time/date the Epic was completed.
type: string
format: date-time
nullable: true
productboard_plugin_id:
description: The ID of the associated productboard integration.
type: string
format: uuid
nullable: true
started_at:
description: The time/date the Epic was started.
type: string
format: date-time
nullable: true
completed_at:
description: The time/date the Epic was completed.
type: string
format: date-time
nullable: true
objective_ids:
description: An array of IDs for Objectives to which this epic is related.
type: array
items:
type: integer
format: int64
name:
description: The name of the Epic.
type: string
global_id:
x-doc-skip: true
type: string
completed:
description: A true/false boolean indicating if the Epic has been completed.
type: boolean
productboard_url:
description: The URL of the associated productboard feature.
type: string
nullable: true
planned_start_date:
description: The Epic's planned start date.
type: string
format: date-time
nullable: true
state:
description: '`Deprecated` The workflow state that the Epic is in.'
type: string
milestone_id:
description: '`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.'
type: integer
format: int64
nullable: true
requested_by_id:
description: The ID of the Member that requested the epic.
type: string
format: uuid
epic_state_id:
description: The ID of the Epic State.
type: integer
format: int64
label_ids:
description: An array of Label ids attached to the Epic.
type: array
items:
type: integer
format: int64
started_at_override:
description: A manual override for the time/date the Epic was started.
type: string
format: date-time
nullable: true
group_id:
description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
type: string
format: uuid
nullable: true
updated_at:
description: The time/date the Epic was updated.
type: string
format: date-time
nullable: true
group_mention_ids:
description: An array of Group IDs that have been mentioned in the Epic description.
type: array
items:
type: string
format: uuid
productboard_id:
description: The ID of the associated productboard feature.
type: string
format: uuid
nullable: true
follower_ids:
description: An array of UUIDs for any Members you want to add as Followers on this Epic.
type: array
items:
type: string
format: uuid
group_ids:
description: An array of UUIDS for Groups to which this Epic is related.
type: array
items:
type: string
format: uuid
owner_ids:
description: An array of UUIDs for any members you want to add as Owners on this new Epic.
type: array
items:
type: string
format: uuid
external_id:
description: This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
type: string
nullable: true
id:
description: The unique ID of the Epic.
type: integer
format: int64
position:
description: The Epic's relative position in the Epic workflow state.
type: integer
format: int64
productboard_name:
description: The name of the associated productboard feature.
type: string
nullable: true
deadline:
description: The Epic's deadline.
type: string
format: date-time
nullable: true
stats:
$ref: '#/components/schemas/EpicStats'
created_at:
description: The time/date the Epic was created.
type: string
format: date-time
nullable: true
additionalProperties: false
required:
- app_url
- archived
- started
- entity_type
- labels
- mention_ids
- member_mention_ids
- associated_groups
- project_ids
- stories_without_projects
- completed_at_override
- productboard_plugin_id
- started_at
- completed_at
- objective_ids
- name
- global_id
- completed
- productboard_url
- planned_start_date
- state
- milestone_id
- requested_by_id
- epic_state_id
- label_ids
- started_at_override
- group_id
- updated_at
- group_mention_ids
- productboard_id
- follower_ids
- group_ids
- owner_ids
- external_id
- id
- position
- productboard_name
- deadline
- stats
- created_at
CreateObjective:
x-doc-skip: true
type: object
properties:
name:
maxLength: 256
minLength: 1
description: The name of the Objective.
type: string
description:
maxLength: 100000
description: The Objective's description.
type: string
state:
description: The workflow state that the Objective is in.
type: string
enum:
- in progress
- to do
- done
started_at_override:
description: A manual override for the time/date the Objective was started.
type: string
format: date-time
completed_at_override:
description: A manual override for the time/date the Objective was completed.
type: string
format: date-time
categories:
description: An array of IDs of Categories attached to the Objective.
type: array
items:
$ref: '#/components/schemas/CreateCategoryParams'
additionalProperties: false
required:
- name
LabelSlim:
description: A Label can be used to associate and filter Stories and Epics, and also create new Workspaces. A slim Label does not include aggregate stats. Fetch the Label using the labels endpoint to retrieve them.
type: object
properties:
app_url:
description: The Shortcut application url for the Label.
type: string
description:
description: The description of the Label.
type: string
nullable: true
archived:
description: A true/false boolean indicating if the Label has been archived.
type: boolean
entity_type:
description: A string description of this resource.
type: string
color:
description: The hex color to be displayed with the Label (for example, "#ff0000").
pattern: ^#[a-fA-F0-9]{6}$
format: css-color
minLength: 1
type: string
nullable: true
name:
description: The name of the Label.
type: string
global_id:
x-doc-skip: true
type: string
updated_at:
description: The time/date that the Label was updated.
type: string
format: date-time
nullable: true
external_id:
description: This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
type: string
nullable: true
id:
description: The unique ID of the Label.
type: integer
format: int64
created_at:
description: The time/date that the Label was created.
type: string
format: date-time
nullable: true
additionalProperties: false
required:
- app_url
- description
- archived
- entity_type
- color
- name
- global_id
- updated_at
- external_id
- id
- created_at
Objective:
description: An Objective is a collection of Epics that represent a release or some other large initiative that you are working on.
type: object
properties:
app_url:
description: The Shortcut application url for the Objective.
type: string
description:
description: The Objective's description.
type: string
archived:
description: A boolean indicating whether the Objective has been archived or not.
type: boolean
started:
description: A true/false boolean indicating if the Objective has been started.
type: boolean
entity_type:
description: A string description of this resource.
type: string
completed_at_override:
description: A manual override for the time/date the Objective was completed.
type: string
format: date-time
nullable: true
started_at:
description: The time/date the Objective was started.
type: string
format: date-time
nullable: true
completed_at:
description: The time/date the Objective was completed.
type: string
format: date-time
nullable: true
name:
description: The name of the Objective.
type: string
global_id:
x-doc-skip: true
type: string
completed:
description: A true/false boolean indicating if the Objectivehas been completed.
type: boolean
state:
description: The workflow state that the Objective is in.
type: string
started_at_override:
description: A manual override for the time/date the Objective was started.
type: string
format: date-time
nullable: true
updated_at:
description: The time/date the Objective was updated.
type: string
format: date-time
categories:
description: An array of Categories attached to the Objective.
type: array
items:
$ref: '#/components/schemas/Category'
id:
description: The unique ID of the Objective.
type: integer
format: int64
key_result_ids:
description: The IDs of the Key Results associated with the Objective.
type: array
items:
type: string
format: uuid
position:
description: A number representing the position of the Objective in relation to every other Objective within the Workspace.
type: integer
format: int64
stats:
$ref: '#/components/schemas/ObjectiveStats'
created_at:
description: The time/date the Objective was created.
type: string
format: date-time
additionalProperties: false
required:
- app_url
- description
- archived
- started
- entity_type
- completed_at_override
- started_at
- completed_at
- name
- global_id
- completed
- state
- started_at_override
- updated_at
- categories
- id
- key_result_ids
- position
- stats
- created_at
ObjectiveStats:
description: A group of calculated values for this Objective.
type: object
properties:
average_cycle_time:
description: The average cycle time (in seconds) of completed stories in this Objective.
type: integer
format: int64
average_lead_time:
description: The average lead time (in seconds) of completed stories in this Objective.
type: integer
format: int64
num_related_documents:
description: The number of related documents to this Objective.
type: integer
format: int64
additionalProperties: false
required:
- num_related_documents
EpicAssociatedGroup:
type: object
properties:
group_id:
description: The Group ID of the associated group.
type: string
format: uuid
associated_stories_count:
description: The number of stories this Group owns in the Epic.
type: integer
format: int64
additionalProperties: false
required:
- group_id
Health:
description: The current health status of the Epic.
type: object
properties:
entity_type:
description: A string description of this resource.
type: string
author_id:
description: The ID of the permission who created or updated the Health record.
type: string
format: uuid
epic_id:
description: The ID of the Epic associated with this Health record.
type: integer
format: int64
objective_id:
description: The ID of the Objective associated with this Health record.
type: integer
format: int64
updated_at:
description: The time that the Health record was updated.
type: string
format: date-time
status:
description: The health status of the Epic or Objective.
type: string
enum:
- At Risk
- On Track
- Off Track
- No Health
id:
description: The unique ID of the Health record.
type: string
format: uuid
nullable: true
created_at:
description: The time that the Health record was created.
type: string
format: date-time
text:
description: The text of the Health record.
type: string
additionalProperties: false
required:
- entity_type
- status
- id
UpdateObjective:
x-doc-skip: true
type: object
properties:
description:
maxLength: 100000
description: The Objective's description.
type: string
archived:
description: A boolean indicating whether the Objective is archived or not
type: boolean
completed_at_override:
description: A manual override for the time/date the Objective was completed.
type: string
format: date-time
nullable: true
name:
maxLength: 256
minLength: 1
description: The name of the Objective.
type: string
state:
description: The workflow state that the Objective is in.
type: string
enum:
- in progress
- to do
- done
started_at_override:
description: A manual override for the time/date the Objective was started.
type: string
format: date-time
nullable: true
categories:
description: An array of IDs of Categories attached to the Objective.
type: array
items:
$ref: '#/components/schemas/CreateCategoryParams'
before_id:
description: The ID of the Objective we want to move this Objective before.
type: integer
format: int64
after_id:
description: The ID of the Objective we want to move this Objective after.
type: integer
format: int64
additionalProperties: false
UnusableEntitlementError:
type: object
properties:
reason_tag:
description: The tag for violating an entitlement action.
type: string
enum:
- entitlement-violation
entitlement_tag:
maxLength: 63
minLength: 1
description: Short tag describing the unusable entitlement action taken by the user.
type: string
message:
maxLength: 256
minLength: 1
description: Message displayed to the user on why their action failed.
type: string
additionalProperties: false
required:
- reason_tag
- entitlement_tag
- message
securitySchemes:
api_token:
type: apiKey
in: header
name: Shortcut-Token