Shortcut Software Search API

openapi: 3.2.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:
    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
    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
    LabelSlim:
      description: A Label can be used to associate and filter Stories and Epics, and also create new Workspaces. A slim Label does not include aggregate stats. Fetch the Label using the labels endpoint to retrieve them.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Label.
          type: string
        description:
          description: The description of the Label.
          type:
          - string
          - 'null'
        archived:
          description: A true/false boolean indicating if the Label has been archived.
          type: boolean
        entity_type:
          description: A string description of this resource.
          type: string
        color:
          description: The hex color to be displayed with the Label (for example, "#ff0000").
          pattern: ^#[a-fA-F0-9]{6}$
          format: css-color
          minLength: 1
          type:
          - string
          - 'null'
        name:
          description: The name of the Label.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        updated_at:
          description: The time/date that the Label was updated.
          type:
          - string
          - 'null'
          format: date-time
        external_id:
          description: This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
          type:
          - string
          - 'null'
        id:
          description: The unique ID of the Label.
          type: integer
          format: int64
        created_at:
          description: The time/date that the Label was created.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - description
      - archived
      - entity_type
      - color
      - name
      - global_id
      - updated_at
      - external_id
      - id
      - created_at
    EpicSearchResults:
      description: The results of the Epic search query.
      type: object
      properties:
        total:
          description: The total number of matches for the search query. The first 1000 matches can be paged through via the API.
          type: integer
          format: int64
        data:
          description: A list of search results.
          type: array
          items:
            $ref: '#/components/schemas/EpicSearchResult'
        next:
          description: The URL path and query string for the next page of search results.
          type:
          - string
          - 'null'
      additionalProperties: false
      required:
      - total
      - data
      - next
    Health:
      description: The current health status of the Epic.
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        author_id:
          description: The ID of the permission who created or updated the Health record.
          type: string
          format: uuid
        epic_id:
          description: The ID of the Epic associated with this Health record.
          type: integer
          format: int64
        objective_id:
          description: The ID of the Objective associated with this Health record.
          type: integer
          format: int64
        updated_at:
          description: The time that the Health record was updated.
          type: string
          format: date-time
        status:
          description: The health status of the Epic or Objective.
          type: string
          enum:
          - At Risk
          - On Track
          - Off Track
          - No Health
        id:
          description: The unique ID of the Health record.
          type:
          - string
          - 'null'
          format: uuid
        created_at:
          description: The time that the Health record was created.
          type: string
          format: date-time
        text:
          description: The text of the Health record.
          type: string
      additionalProperties: false
      required:
      - entity_type
      - status
      - id
    StorySearchResults:
      description: The results of the Story search query.
      type: object
      properties:
        total:
          description: The total number of matches for the search query. The first 1000 matches can be paged through via the API.
          type: integer
          format: int64
        data:
          description: A list of search results.
          type: array
          items:
            $ref: '#/components/schemas/StorySearchResult'
        next:
          description: The URL path and query string for the next page of search results.
          type:
          - string
          - 'null'
      additionalProperties: false
      required:
      - total
      - data
      - next
    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
    IterationSlim:
      description: 'IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the [Get Iteration](#Get-Iteration) endpoint to fetch the unabridged payload for an Iteration. '
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Iteration.
          type: string
        entity_type:
          description: A string description of this resource
          type: string
        labels:
          description: An array of labels attached to the iteration.
          type: array
          items:
            $ref: '#/components/schemas/Label'
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        member_mention_ids:
          description: An array of Member IDs that have been mentioned in the Story description.
          type: array
          items:
            type: string
            format: uuid
        associated_groups:
          description: An array containing Group IDs and Group-owned story counts for the Iteration's associated groups.
          x-doc-skip: true
          type: array
          items:
            $ref: '#/components/schemas/IterationAssociatedGroup'
        name:
          description: The name of the iteration.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        label_ids:
          description: An array of label ids attached to the iteration.
          type: array
          items:
            type: integer
            format: int64
        updated_at:
          description: The instant when this iteration was last updated.
          type: string
          format: date-time
        group_mention_ids:
          description: An array of Group IDs that have been mentioned in the Story description.
          type: array
          items:
            type: string
            format: uuid
        end_date:
          description: The date this iteration ends.
          type: string
          format: date-time
        follower_ids:
          description: An array of UUIDs for any Members listed as Followers.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
          type: array
          items:
            type: string
            format: uuid
        start_date:
          description: The date this iteration begins.
          type: string
          format: date-time
        status:
          description: The status of the iteration. Values are either "unstarted", "started", or "done".
          type: string
        id:
          description: The ID of the iteration.
          type: integer
          format: int64
        stats:
          $ref: '#/components/schemas/IterationStats'
        created_at:
          description: The instant when this iteration was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - entity_type
      - labels
      - mention_ids
      - member_mention_ids
      - associated_groups
      - name
      - global_id
      - label_ids
      - updated_at
      - group_mention_ids
      - end_date
      - follower_ids
      - group_ids
      - start_date
      - status
      - id
      - stats
      - created_at
    Identity:
      description: The Identity of the VCS user that authored the Commit.
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        name:
          description: This is your login in VCS.
          type:
          - string
          - 'null'
        type:
          description: The service this Identity is for.
          type:
          - string
          - 'null'
          enum:
          - slack
          - github
          - gitlab
          - bitbucket
      additionalProperties: false
      required:
      - entity_type
      - name
      - type
    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
    TypedStoryLink:
      description: 'The type of Story Link. The string can be subject or object. '
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        object_id:
          description: The ID of the object Story.
          type: integer
          format: int64
        verb:
          description: How the subject Story acts on the object Story. This can be "blocks", "duplicates", or "relates to".
          type: string
        type:
          description: This indicates whether the Story is the subject or object in the Story Link.
          type: string
        updated_at:
          description: The time/date when the Story Link was last updated.
          type: string
          format: date-time
        id:
          description: The unique identifier of the Story Link.
          type: integer
          format: int64
        subject_id:
          description: The ID of the subject Story.
          type: integer
          format: int64
        subject_workflow_state_id:
          description: The workflow state of the "subject" story.
          x-doc-skip: true
          type: integer
          format: int64
        created_at:
          description: The time/date when the Story Link was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - entity_type
      - object_id
      - verb
      - type
      - updated_at
      - id
      - subject_id
      - subject_workflow_state_id
      - created_at
    LabelStats:
      description: A group of calculated values for this Lab

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