Shortcut Software Stories API

openapi: 3.0.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:
    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 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
          format: int64
          nullable: true
        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. Must be provided if the template does not provide a name.
          type: string
        file_ids_add:
          description: An array of IDs of files attached to the story in addition to files from the template. Cannot be used in conjunction with `file_ids`.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        file_ids_remove:
          description: An array of IDs of files removed from files from the template. Cannot be used in conjunction with `file_ids`.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        comments:
          description: An array of comments to add to the story.
          type: array
          items:
            $ref: '#/components/schemas/CreateStoryCommentParams'
        follower_ids_add:
          description: The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with `follower_ids.`
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        epic_id:
          description: The ID of the epic the story belongs to.
          type: integer
          format: int64
          nullable: true
        story_template_id:
          description: The id of the story template used to create this story.
          type: string
          format: uuid
        external_links:
          description: An array of External Links associated with this story.
          type: array
          items:
            type: string
        follower_ids_remove:
          description: The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with `follower_ids`.
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        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'
        linked_file_ids_remove:
          description: An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with `linked_files.`
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        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
          format: int64
          nullable: true
        custom_fields_remove:
          description: A map specifying a CustomField ID. These will be removed from any fields provided by the template. Cannot be used in conjunction with `custom_fields`.
          type: array
          items:
            $ref: '#/components/schemas/RemoveCustomFieldParams'
          uniqueItems: true
        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
        labels_add:
          description: An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with `labels`.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
          uniqueItems: true
        group_id:
          description: The id of the group to associate with this story.
          type: string
          format: uuid
          nullable: true
        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
          format: int64
          nullable: true
        estimate:
          description: The numeric point estimate of the story. Can also be null, which means unestimated.
          type: integer
          format: int64
          nullable: true
        owner_ids_remove:
          description: The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with `owners`.
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        custom_fields_add:
          description: A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. These will be added to any fields provided by the template. Cannot be used in conjunction with `custom_fields`.
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValueParams'
          uniqueItems: true
        project_id:
          description: The ID of the project the story belongs to.
          type: integer
          format: int64
          nullable: true
        linked_file_ids_add:
          description: An array of IDs of linked files attached to the story in addition to files from the template. Cannot be used in conjunction with `linked_files`.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        linked_file_ids:
          description: An array of IDs of linked files attached to the story.
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        labels_remove:
          description: An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with `labels`.
          type: array
          items:
            $ref: '#/components/schemas/RemoveLabelParams'
          uniqueItems: true
        deadline:
          description: The due date of the story.
          type: string
          format: date-time
          nullable: true
        owner_ids_add:
          description: The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with `owners`.
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        created_at:
          description: The time/date the Story was created.
          type: string
          format: date-time
        external_links_remove:
          description: An array of External Links associated with this story. These will be removed from any links provided by the template. Cannot be used in conjunction with `external_links`.
          type: array
          items:
            type: string
          uniqueItems: true
      additionalProperties: false
      required:
      - story_template_id
    UploadedFile:
      description: 'An UploadedFile is any document uploaded to your Shortcut Workspace. Files attached from a third-party service are different: see the Linked Files endpoint.'
      type: object
      properties:
        description:
          description: The description of the file.
          type: string
          nullable: true
        entity_type:
          description: A string description of this resource.
          type: string
        story_ids:
          description: The unique IDs of the Stories associated with this file.
          type: array
          items:
            type: integer
            format: int64
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        member_mention_ids:
          description: The unique IDs of the Members who are mentioned in the file description.
          type: array
          items:
            type: string
            format: uuid
        name:
     

# --- 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