Shortcut Software Search API

openapi: 3.0.0
info:
  title: Shortcut Categories Search API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Search
paths:
  /api/v3/search:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: search
      description: Search lets you search Epics and Stories based on desired parameters. Since ordering of the results can change over time (due to search ranking decay, new Epics and Stories being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search
      tags:
      - Search
  /api/v3/search/documents:
    get:
      parameters:
      - in: query
        name: title
        description: Search text to match against document titles. Supports fuzzy matching. Required.
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: archived
        description: When true, find archived documents. When false, find non-archived documents.
        required: false
        schema:
          type: boolean
      - in: query
        name: created_by_me
        description: When true, find documents created by the current user. When false, find documents NOT created by current user.
        required: false
        schema:
          type: boolean
      - in: query
        name: followed_by_me
        description: When true, find documents that the current user is following. When false, find documents NOT followed.
        required: false
        schema:
          type: boolean
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocSearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisabledFeatureError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchDocuments
      description: "Search Documents lets you search Documents based on desired parameters.\n                          Supports structured filters: title, archived, created_by_me, followed_by_me."
      summary: Search Documents
      tags:
      - Search
  /api/v3/search/epics:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicSearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchEpics
      description: Search Epics lets you search Epics based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new Epics being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search Epics
      tags:
      - Search
  /api/v3/search/iterations:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterationSearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchIterations
      description: Search Iterations lets you search Iterations based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Iterations being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search Iterations
      tags:
      - Search
  /api/v3/search/milestones:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectiveSearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchMilestones
      description: Search Milestones lets you search Milestones based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Milestones being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search Milestones
      tags:
      - Search
  /api/v3/search/objectives:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectiveSearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchObjectives
      description: Search Objectives lets you search Objectives based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Objectives being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search Objectives
      tags:
      - Search
  /api/v3/search/stories:
    get:
      parameters:
      - in: query
        name: query
        description: See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)
        required: true
        schema:
          type: string
          minLength: 1
      - in: query
        name: page_size
        description: The number of search results to include in a page. Minimum of 1 and maximum of 250.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: detail
        description: "The amount of detail included in each result item.\n   \"full\" will include all descriptions and comments and more fields on\n   related items such as pull requests, branches and tasks.\n   \"slim\" omits larger fulltext fields such as descriptions and comments\n   and only references related items by id.\n   The default is \"full\"."
        required: false
        schema:
          type: string
          enum:
          - full
          - slim
      - in: query
        name: next
        description: The next page token.
        required: false
        schema:
          type: string
      - in: query
        name: entity_types
        description: 'A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.'
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - story
            - milestone
            - epic
            - iteration
            - objective
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorySearchResults'
        '400':
          description: '**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSearchResultsExceededError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: searchStories
      description: Search Stories lets you search Stories based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new stories being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
      summary: Search Stories
      tags:
      - Search
components:
  schemas:
    StoryReaction:
      description: Emoji reaction on a comment.
      type: object
      properties:
        emoji:
          description: Emoji text of the reaction.
          type: string
        permission_ids:
          description: Permissions who have reacted with this.
          type: array
          items:
            type: string
            format: uuid
      additionalProperties: false
      required:
      - emoji
      - permission_ids
    SyncedItem:
      x-doc-skip: true
      description: The synced item for the story.
      type: object
      properties:
        external_id:
          description: The id used to reference an external entity.
          type: string
        url:
          description: The url to the external entity.
          type: string
      additionalProperties: false
      required:
      - external_id
      - url
    StoryComment:
      description: A Comment is any note added within the Comment field of a Story.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Comment.
          type: string
        entity_type:
          description: A string description of this resource.
          type: string
        deleted:
          description: True/false boolean indicating whether the Comment has been deleted.
          type: boolean
        story_id:
          description: The ID of the Story on which the Comment appears.
          type: integer
          format: int64
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        author_id:
          description: The unique ID of the Member who is the Comment's author.
          type: string
          format: uuid
          nullable: true
        member_mention_ids:
          description: The unique IDs of the Member who are mentioned in the Comment.
          type: array
          items:
            type: string
            format: uuid
        blocker:
          description: Marks the comment as a blocker that can be surfaced to permissions or teams mentioned in the comment. Can only be used on a top-level comment.
          type: boolean
        linked_to_slack:
          description: Whether the Comment is currently the root of a thread that is linked to Slack.
          type: boolean
        updated_at:
          description: The time/date when the Comment was updated.
          type: string
          format: date-time
          nullable: true
        group_mention_ids:
          description: The unique IDs of the Group who are mentioned in the Comment.
          type: array
          items:
            type: string
            format: uuid
        external_id:
          description: This field can be set to another unique ID. In the case that the Comment has been imported from another tool, the ID in the other tool can be indicated here.
          type: string
          nullable: true
        parent_id:
          description: The ID of the parent Comment this Comment is threaded under.
          type: integer
          format: int64
          nullable: true
        id:
          description: The unique ID of the Comment.
          type: integer
          format: int64
        position:
          description: The Comments numerical position in the list from oldest to newest.
          type: integer
          format: int64
        unblocks_parent:
          description: Marks the comment as an unblocker to its  blocker parent. Can only be set on a threaded comment who has a parent with `blocker` set.
          type: boolean
        reactions:
          description: A set of Reactions to this Comment.
          x-doc-skip: true
          type: array
          items:
            $ref: '#/components/schemas/StoryReaction'
        created_at:
          description: The time/date when the Comment was created.
          type: string
          format: date-time
        text:
          description: The text of the Comment. In the case that the Comment has been deleted, this field can be set to nil.
          type: string
          nullable: true
      additionalProperties: false
      required:
      - app_url
      - entity_type
      - deleted
      - story_id
      - mention_ids
      - author_id
      - member_mention_ids
      - linked_to_slack
      - updated_at
      - group_mention_ids
      - external_id
      - id
      - position
      - reactions
      - created_at
      - text
    Commit:
      description: Commit refers to a VCS commit and all associated details.
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        author_id:
          description: The ID of the Member that authored the Commit, if known.
          type: string
          format: uuid
          nullable: true
        hash:
          description: The Commit hash.
          type: string
        updated_at:
          description: The time/date the Commit was updated.
          type: string
          format: date-time
          nullable: true
        id:
          description: The unique ID of the Commit.
          type: integer
          format: int64
          nullable: true
        url:
          description: The URL of the Commit.
          type: string
        author_email:
          description: The email address of the VCS user that authored the Commit.
          type: string
        timestamp:
          description: The time/date the Commit was pushed.
          type: string
          format: date-time
        author_identity:
          $ref: '#/components/schemas/Identity'
        repository_id:
          description: The ID of the Repository that contains the Commit.
          type: integer
          format: int64
          nullable: true
        created_at:
          description: The time/date the Commit was created.
          type: string
          format: date-time
        message:
          description: The Commit message.
          type: string
      additionalProperties: false
      required:
      - entity_type
      - author_id
      - hash
      - updated_at
      - id
      - url
      - author_email
      - timestamp
      - author_identity
      - repository_id
      - created_at
      - message
    StoryCustomField:
      type: object
      properties:
        field_id:
          description: The unique public ID for a CustomField.
          type: string
          format: uuid
        value_id:
          description: The unique public ID for a CustomFieldEnumValue.
          type: string
          format: uuid
        value:
          description: A string representation of the value, if applicable.
          type: string
      additionalProperties: false
      required:
      - field_id
      - value_id
      - value
    PullRequest:
      description: Corresponds to a VCS Pull Request attached to a Shortcut story.
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        closed:
          description: True/False boolean indicating whether the VCS pull request has been closed.
          type: boolean
        merged:
          description: True/False boolean indicating whether the VCS pull request has been merged.
          type: boolean
        num_added:
          description: Number of lines added in the pull request, according to VCS.
          type: integer
          format: int64
        branch_id:
          description: The ID of the branch for the particular pull request.
          type: integer
          format: int64
        overlapping_stories:
          description: An array of Story ids that have Pull Requests that change at least one of the same lines this Pull Request changes.
          type: array
          items:
            type: integer
            format: int64
        number:
          description: The pull request's unique number ID in VCS.
          type: integer
          format: int64
        branch_name:
          description: The name of the branch for the particular pull request.
          type: string
        target_branch_name:
          description: The name of the target branch for the particular pull request.
          type: string
        num_commits:
          description: The number of commits on the pull request.
          type: integer
          format: int64
          nullable: true
        title:
          description: The title of the pull request.
          type: string
        updated_at:
          description: The time/date the pull request was created.
          type: string
          format: date-time
        has_overlapping_stories:
          description: Boolean indicating that the Pull Request has Stories that have Pull Requests that change at least one of the same lines this Pull Request changes.
          type: boolean
        draft:
          description: True/False boolean indicating whether the VCS pull request is in the draft state.
          type: boolean
        id:
          description: The unique ID associated with the pull request in Shortcut.
          type: integer
          format: int64
        vcs_labels:
          description: An array of PullRequestLabels attached to the PullRequest.
          type: array
          items:
            $ref: '#/components/schemas/PullRequestLabel'
          nullable: true
        url:
          description: The URL for the pull request.
          type: string
        num_removed:
          description: Number of lines removed in the pull request, according to VCS.
          type: integer
          format: int64
        review_status:
          description: The status of the review for the pull request.
          type: string
        num_modified:
          description: Number of lines modified in the pull request, according to VCS.
          type: integer
          format: int64
          nullable: true
        build_status:
          description: The status of the Continuous Integration workflow for the pull request.
          type: string
        target_branch_id:
          description: The ID of the target branch for the particular pull request.
          type: integer
          format: int64
        repository_id:
          description: The ID of the repository for the particular pull request.
          type: integer
          format: int64
        created_at:
          description: The time/date the pull request was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - entity_type
      - closed
      - merged
      - num_added
      - branch_id
      - number
      - branch_name
      - target_branch_name
      - num_commits
      - title
      - updated_at
      - has_overlapping_stories
      - draft
      - id
      - url
      - num_removed
      - num_modified
      - target_branch_id
      - repository_id
      - created_at
    IterationAssociatedGroup:
      x-doc-skip: true
      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 Iteration.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - group_id
    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
    LabelStats:
      description: A group of calculated values for this Label. This is not included if the slim? flag is set to true for the List Labels endpoint.
      type: object
      properties:
        num_related_documents:
          description: The total number of Documents associated this Label.
          type: integer
          format: int64
        num_epics:
          description: The total number of Epics with this Label.
          type: integer
          format: int64
        num_stories_unstarted:
          description: The total number of stories unstarted Stories with this Label.
          type: integer
          format: int64
        num_stories_total:
          description: The total number of Stories with this Label.
          type: integer
          format: int64
        num_epics_unstarted:
          description: The number of unstarted epics associated with this label.
          type: integer
          format: int64
        num_epics_in_progress:
          description: The number of in progress epics associated with this label.
          type: integer
          format: int64
        num_points_unstarted:
          description: The total number of unstarted points with this Label.
          type: integer
          format: int64
        num_stories_unestimated:
          description: The total number of Stories with no point estimate with this Label.
          type: integer
          format: int64
        num_points_in_progress:
          description: The total number of in-progress points with this Label.
          type: integer
          format: int64
        num_epics_total:
          description: The total number of Epics associated with this Label.
          type: integer
          format: int64
        num_stories_completed:
          description: The total number of completed Stories with this Label.
          type: integer
          format: int64
        num_points_completed:
          description: The total number of completed points with this Label.
          type: integer
          format: int64
        num_stories_backlog:
          description: The total number of stories backlog Stories with this Label.
          type: integer
          format: int64
        num_points_total:
          description: The total number of points with this Label.
          type: integer
        

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