Shortcut Software Stories API

openapi: 3.2.0
info:
  title: Shortcut Categories Stories API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Stories
paths:
  /api/v3/stories:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoryParams'
        description: Request parameters for creating a story.
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Story'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createStory
      description: "Create Story is used to add a new story to your Shortcut Workspace.\n    This endpoint requires that either **workflow_state_id** or **project_id** be provided, but will reject the request if both or neither are specified. The workflow_state_id has been marked as required and is the recommended field to specify because we are in the process of sunsetting Projects in Shortcut."
      summary: Create Story
      tags:
      - Stories
  /api/v3/stories/bulk:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStories'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorySlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createMultipleStories
      description: Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as [Create Story](https://developer.shortcut.com/api/rest/v3#create-story).
      summary: Create Multiple Stories
      tags:
      - Stories
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStories'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorySlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateMultipleStories
      description: Update Multiple Stories allows you to make changes to numerous stories at once.
      summary: Update Multiple Stories
      tags:
      - Stories
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteStories'
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: deleteMultipleStories
      description: Delete Multiple Stories allows you to delete multiple archived stories at once.
      summary: Delete Multiple Stories
      tags:
      - Stories
  /api/v3/stories/from-template:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoryFromTemplateParams'
        description: Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Story'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createStoryFromTemplate
      description: Create Story From Template is used to add a new story derived from a template to your Shortcut Workspace.
      summary: Create Story From Template
      tags:
      - Stories
  /api/v3/stories/search:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchStories'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorySlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: queryStories
      description: Search Stories lets you search Stories based on desired parameters.
      summary: Query Stories
      tags:
      - Stories
  /api/v3/stories/{story-public-id}:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Story'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getStory
      description: Get Story returns information about a chosen Story.
      summary: Get Story
      tags:
      - Stories
    put:
      parameters:
      - in: path
        name: story-public-id
        description: The unique identifier of this story.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStory'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Story'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateStory
      description: Update Story can be used to update Story properties.
      summary: Update Story
      tags:
      - Stories
    delete:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story.
        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: deleteStory
      description: Delete Story can be used to delete any Story.
      summary: Delete Story
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/comments:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoryComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listStoryComment
      description: Lists Comments associated with a Story
      summary: List Story Comment
      tags:
      - Stories
    post:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoryComment'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createStoryComment
      description: Create Comment allows you to create a Comment on any Story.
      summary: Create Story Comment
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/comments/{comment-public-id}:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getStoryComment
      description: Get Comment is used to get Comment information.
      summary: Get Story Comment
      tags:
      - Stories
    put:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoryComment'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateStoryComment
      description: Update Comment replaces the text of the existing Comment.
      summary: Update Story Comment
      tags:
      - Stories
    delete:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        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: deleteStoryComment
      description: Delete a Comment from any story.
      summary: Delete Story Comment
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions:
    post:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        $ref: '#/components/requestBodies/CreateOrDeleteStoryReaction'
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoryReaction'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createStoryReaction
      description: Create a reaction to a story comment.
      summary: Create Story Reaction
      tags:
      - Stories
    delete:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Comment is in.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        $ref: '#/components/requestBodies/CreateOrDeleteStoryReaction'
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: deleteStoryReaction
      description: Delete a reaction from any story comment.
      summary: Delete Story Reaction
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/comments/{comment-public-id}/unlink-from-slack:
    post:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story to unlink.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment to unlink.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: unlinkCommentThreadFromSlack
      description: Unlinks a Comment from its linked Slack thread (Comment replies and Slack replies will no longer be synced)
      summary: Unlink Comment thread from Slack
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/history:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/History'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: storyHistory
      summary: Story History
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/sub-tasks:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorySlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listStorySubTasks
      description: List Story Sub tasks returns a list of all Sub-task Stories for a given parent Story.
      summary: List Story Sub tasks
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/tasks:
    post:
      parameters:
      - in: path
        name: story-public-id
        description: The ID of the Story that the Task will be in.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTask'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createTask
      description: Create Task is used to create a new task in a Story.
      summary: Create Task
      tags:
      - Stories
  /api/v3/stories/{story-public-id}/tasks/{task-public-id}:
    get:
      parameters:
      - in: path
        name: story-public-id
        description: The unique ID of the Story this Task is associated with.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: task-public-id
        description: The unique ID of the Task.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getTask
      description: Returns information about a chosen Task.
      summary: Get Task
      tags:
      - Stories
    put:
      parameters:
      - in: path
        name: story-public-id
        description: The unique identifier of the parent Story.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: task-public-id
        description: The unique identifier of the Task you wish to update.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTask'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateTask
      description: Update Task can be used to update Task properties.
      summary: Update Task
      tags:
      - Stories
    delete:
      parameters:
      - in: path
        name: story-public-id
        description: The unique ID of the Story this Task is associated with.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: task-public-id
        description: The unique ID of the Task.
        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: deleteTask
      description: Delete Task can be used to delete any previously created Task on a Story.
      summary: Delete Task
      tags:
      - Stories
components:
  schemas:
    Branch:
      description: Branch refers to a VCS branch. Branches are feature branches associated with Shortcut Stories.
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        deleted:
          description: A true/false boolean indicating if the Branch has been deleted.
          type: boolean
        name:
          description: The name of the Branch.
          type: string
        persistent:
          description: This field is deprecated, and will always be false.
          type: boolean
        updated_at:
          description: The time/date the Branch was updated.
          type:
          - string
          - 'null'
          format: date-time
        pull_requests:
          description: An array of PullRequests attached to the Branch (there is usually only one).
          type: array
          items:
            $ref: '#/components/schemas/PullRequest'
        merged_branch_ids:
          description: The IDs of the Branches the Branch has been merged into.
          type: array
          items:
            type: integer
            format: int64
        id:
          description: The unique ID of the Branch.
          type:
          - integer
          - 'null'
          format: int64
        url:
          description: The URL of the Branch.
          type: string
        repository_id:
          description: The ID of the Repository that contains the Branch.
          type: integer
          format: int64
        created_at:
          description: The time/date the Branch was created.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - entity_type
      - deleted
      - name
      - persistent
      - updated_at
      - pull_requests
      - merged_branch_ids
      - id
      - url
      - repository_id
      - created_at
    HistoryActionWorkspace2BulkUpdate:
      description: An action representing a bulk operation within a workspace2.
      type: object
      properties:
        id:
          description: The ID of the entity referenced.
          type: string
          format: uuid
        entity_type:
          description: The type of entity referenced.
          type: string
        action:
          description: The action of the entity referenced.
          type: string
          enum:
          - bulk-update
        name:
          description: The name of the workspace2 in which the BulkUpdate occurred.
          type: string
      additionalProperties: false
      required:
      - id
      - entity_type
      - action
      - name
    HistoryActionStoryCommentCreate:
      description: An action representing a Story Comment being created.
      type: object
      properties:
        id:
          description: The ID of the entity referenced.
          type: integer
          format: int64
        entity_type:
          description: The type of entity referenced.
          type: string
        action:
          description: The action of the entity referenced.
          type: string
          enum:
          - create
        app_url:
          pattern: ^https?://.+$
          maxLength: 2048
          description: The application URL of the Story Comment.
          type: string
        author_id:
          description: The Member ID of who created the Story Comment.
          type: string
          format: uuid
      additionalProperties: false
      required:
      - id
      - entity_type
      - action
      - app_url
      - author_id
    CreateStoryParams:
      description: Request parameters for creating a story.
      type: object
      properties:
        description:
          maxLength: 100000
          description: The description of the story.
          type: string
        archived:
          description: Controls the story's archived state.
          type: boolean
        story_links:
          description: An array of story links attached to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateStoryLinkParams'
        labels:
          description: An array of labels attached to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
        story_type:
          description: The type of story (feature, bug, chore).
          type: string
          enum:
          - feature
          - chore
          - bug
        custom_fields:
          description: A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValueParams'
        move_to:
          description: One of "first" or "last". This can be used to move the given story to the first or last position in the workflow state.
          type: string
          enum:
          - last
          - first
        file_ids:
          description: An array of IDs of files attached to the story.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        source_task_id:
          description: Given this story was converted from a task in another story, this is the original task ID that was converted to this story.
          type:
          - integer
          - 'null'
          format: int64
        completed_at_override:
          description: A manual override for the time/date the Story was completed.
          type: string
          format: date-time
        name:
          maxLength: 512
          minLength: 1
          description: The name of the story.
          type: string
        comments:
          description: An array of comments to add to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateStoryCommentParams'
        epic_id:
          description: The ID of the epic the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        story_template_id:
          description: The id of the story template used to create this story, if applicable. This is just an association; no content from the story template is inherited by the story simply by setting this field.
          type:
          - string
          - 'null'
          format: uuid
        external_links:
          description: An array of External Links associated with this story.
          type: array
          items:
            type: string
        sub_tasks:
          description: 'An array of maps specifying sub-tasks to be associated with the created story. Each map can either link to an existing story or create a new sub-task story to be linked to the created story.

            Field only applicable when Sub-task feature is enabled.'
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/LinkSubTaskParams'
            - $ref: '#/components/schemas/CreateSubTaskParams'
        requested_by_id:
          description: The ID of the member that requested the story.
          type: string
          format: uuid
        iteration_id:
          description: The ID of the iteration the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        tasks:
          description: An array of tasks connected to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateTaskParams'
        started_at_override:
          description: A manual override for the time/date the Story was started.
          type: string
          format: date-time
        group_id:
          description: The id of the group to associate with this story.
          type:
          - string
          - 'null'
          format: uuid
        workflow_state_id:
          description: The ID of the workflow state the story will be in.
          type: integer
          format: int64
        updated_at:
          description: The time/date the Story was updated.
          type: string
          format: date-time
        follower_ids:
          description: An array of UUIDs of the followers of this story.
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        owner_ids:
          description: An array of UUIDs of the owners of this story.
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        external_id:
          maxLength: 1024
          description: This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
          type: string
        parent_story_id:
          description: 'The ID of the parent story to associate with this story (making the created story a sub-task).

            Field only applicable when Sub-task feature is enabled.'
          type:
          - integer
          - 'null'
          format: int64
        estimate:
          description: The numeric point estimate of the story. Can also be null, which means unestimated.
          type:
          - integer
          - 'null'
          format: int64
        project_id:
          description: The ID of the project the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        linked_file_ids:
          description: An array of IDs of linked files attached to the story.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        deadline:
          description: The due date of the story.
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          description: The time/date the Story was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - name
    CreateStoryFromTemplateParams:
      description: Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.
      type: object
      properties:
        description:
          maxLength: 100000
          description: The description of the story.
          type: string
        archived:
          description: Controls the story's archived state.
          type: boolean
        story_links:
          description: An array of story links attached to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateStoryLinkParams'
        labels:
          description: An array of labels attached to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
        external_links_add:
          description: An array of External Links associated with this story. These will be added to any links provided by the template. Cannot be used in conjunction with `external_links`.
          type: array
          items:
            type: string
          uniqueItems: true
        story_type:
          description: The type of story (feature, bug, chore).
          type: string
          enum:
          - feature
          - chore
          - bug
        custom_fields:
          description: A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValueParams'
        move_to:
          description: One of "first" or "last". This can be used to move the given story to the first or last position in the workflow

# --- truncated at 32 KB (149 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shortcut-software/refs/heads/main/openapi/shortcut-software-stories-api-openapi.yml