> ## Documentation Index
> Fetch the complete documentation index at: https://superthread.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get search results

> Execute a search query across multiple workspace entities, including boards, cards,
pages, and projects. Customize the search by specifying targeted fields like title
or content, filtering by types of objects, or focusing on specific statuses.
Additional options include filtering by project, controlling whether archived data
is included, and choosing grouped or ungrouped results.
This comprehensive search endpoint provides flexibility to locate relevant workspace
data efficiently.




## OpenAPI

````yaml GET /{team_id}/search
openapi: 3.0.0
info:
  description: Superthread Public API Specification
  version: '0.1'
  title: Public API
  contact:
    email: engineering@superthread.com
servers:
  - url: https://api.superthread.com/v1
security:
  - BearerAuth: []
tags:
  - name: AI
    description: >-
      [Service: AI]. Handles AI-powered functionalities, such as
      recommendations, predictions, and automation features.
  - name: Activity
    description: >-
      [Service: Activity] Manages all activities; creating notifications and
      digests
  - name: Auth
    description: >-
      [Service: Auth] Responsible for user authentication, authorization, and
      session management.
  - name: Boards
    description: >-
      [Service: Boards] Manages core collaboration features such as "boards",
      "cards", "lists", "sprints", "epics".
  - name: Comments
    description: >-
      [Service: Comments] Handles the creation, editing, and management of
      comments across various entities.
  - name: Favourites
    description: >-
      [Service: Favourites] Responsible for favouriting resources in the system
      for quick access.
  - name: Files
    description: >-
      [Service: Files] Manages file uploads, storage, and retrieval for user and
      project resources.
  - name: Importer
    description: >-
      [Service: Importer] Handles data import operations from external sources
      into the platform.
  - name: Integrations
    description: >-
      [Service: Integrations] Facilitates connectivity with external tools and
      services, enabling smooth integration with third-party platforms and APIs.
  - name: Pages
    description: >-
      [Service: Pages] Manages the creation and organization of both public and
      private pages, supporting structured content and navigation and
      collaboration.
  - name: Projects
    description: '[Service: Projects] Handles all project related tasks.'
  - name: Reports
    description: >-
      [Service: Reports] Generates and manages analytical reports and insights
      for users and projects.
  - name: Search
    description: >-
      [Service: Search] Provides search functionalities, including indexing and
      retrieval of platform data.
  - name: TimeTracking
    description: >-
      [Service: TimeTracking] Manages time entries, active timers, time
      categories, billing rates, and audit/lock for time-tracking workflows.
  - name: Views
    description: >-
      [Feature] Provides tools to create and customize views, enabling users to
      organize and visualize their data according to their preferences and
      workflows.
  - name: OAuth2
    description: >-
      [Feature] Supports OAuth2 integration for seamless user authentication and
      authorization, ensuring secure access to external APIs and services.
  - name: Sprints
    description: >-
      [Feature] Facilitates sprint management within agile workflows, including
      planning, progress tracking, and reporting.
  - name: Cards
    description: >-
      [Feature] A Card is the core concept used in the system to describe an
      individual task or work item. They are used across Boards, Sprints, and
      Roadmaps. Cards include features like descriptions, checklists, comments,
      priorities, tags and more.
  - name: Checklists
    description: >-
      [Feature] A Checklist is a list of items that need to be completed. It is
      used to track progress on a card.
  - name: Lists
    description: >-
      [Feature] Represents a collection of tasks or items grouped within
      different contexts in the system. Lists (externally referenced as
      "statuses") are utilized across various entities such as boards, sprints,
      and roadmaps.
  - name: Notes
    description: >-
      [Feature] Enables users to create, edit, and organize notes, supporting
      rich text, attachments, transcriptions and AI enhancements.
  - name: Tags
    description: >-
      [Feature] Groups endpoints related to the creation, retrieval, updating,
      deletion, and merging of tags within teams (workspaces).
  - name: Agents
    description: >-
      [Feature] Manages agents and runs. Provides CRUD operations for agents,
      launching cloud agents, monitoring agent status, retrieving conversations,
      and sending follow-ups.
paths:
  /{team_id}/search:
    parameters:
      - $ref: '#/components/parameters/path_team_id'
    get:
      tags:
        - Search
      summary: Get search results
      description: >
        Execute a search query across multiple workspace entities, including
        boards, cards,

        pages, and projects. Customize the search by specifying targeted fields
        like title

        or content, filtering by types of objects, or focusing on specific
        statuses.

        Additional options include filtering by project, controlling whether
        archived data

        is included, and choosing grouped or ungrouped results.

        This comprehensive search endpoint provides flexibility to locate
        relevant workspace

        data efficiently.
      operationId: getSearch
      parameters:
        - in: query
          name: query
          required: true
          description: Search query
          schema:
            type: string
        - in: query
          name: cursor
          required: false
          description: cursor for pagination
          schema:
            type: string
        - in: query
          name: count
          required: false
          description: max number of items to return. defaults to 25
          schema:
            type: integer
        - in: query
          name: types
          description: >-
            Types of object you would like to search against. includes all types
            if not specified
          schema:
            type: string
            enum:
              - boards
              - cards
              - pages
              - projects
        - in: query
          name: fields
          description: Fields you would like to target in the free text search
          schema:
            type: string
            enum:
              - title
              - content
        - in: query
          name: archived
          description: Whether or not to include archived data. defaults to false
          schema:
            type: boolean
        - in: query
          name: statuses
          description: Card statuses to filter by
          schema:
            type: string
            enum:
              - backlog
              - committed
              - started
              - completed
              - cancelled
        - $ref: '#/components/parameters/query_project_id'
        - in: query
          name: grouped
          description: >-
            Whether the results will be grouped by type (as opposed to all under
            the 'results' prop). defaults to true
          schema:
            type: boolean
        - in: query
          name: highlight
          description: >-
            Whether matching result text may include Elasticsearch highlight
            markup. defaults to false
          schema:
            type: boolean
        - in: query
          name: highlight_pre_tag
          required: false
          description: >-
            Opening tag wrapping highlighted terms in title and excerpt fields.
            Defaults to <sthl>.
          schema:
            type: string
        - in: query
          name: highlight_post_tag
          required: false
          description: >-
            Closing tag wrapping highlighted terms in title and excerpt fields.
            Defaults to </sthl>.
          schema:
            type: string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        default:
          description: client error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
components:
  parameters:
    path_team_id:
      in: path
      name: team_id
      description: >-
        Team ID is an alphanumerical string that identifies a Team. This is
        externally referred to as a "Workspace".
      required: true
      schema:
        type: string
    query_project_id:
      in: query
      name: project_id
      description: >-
        Project ID is a numerical string that identifies a Project. This is
        externally referred to as a "Space".
      required: false
      schema:
        type: string
  schemas:
    SearchResults:
      type: object
      allOf:
        - $ref: '#/components/schemas/ResponseMetadata'
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        boards:
          type: array
          items:
            $ref: '#/components/schemas/BoardSearchResult'
        cards:
          type: array
          items:
            $ref: '#/components/schemas/CardSearchResult'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/PageSearchResult'
        projects:
          type: array
          items:
            $ref: '#/components/schemas/ProjectSearchResult'
        epics:
          type: array
          items:
            $ref: '#/components/schemas/EpicSearchResult'
        notes:
          type: array
          items:
            $ref: '#/components/schemas/NoteSearchResult'
    Error:
      type: object
      properties:
        id:
          type: string
          example: err5f744ab
        code:
          type: integer
          format: int32
          example: 403
        sec:
          $ref: '#/components/schemas/SuperthreadErrorCode'
        message:
          type: string
          example: You do not have access to this resource
          description: A user-friendly error message
        date:
          $ref: '#/components/schemas/STime'
    ResponseMetadata:
      type: object
      required:
        - cursor
        - count
      properties:
        cursor:
          type: string
          example: dmsjqh9d8w1hdjosjaasda
          nullable: false
        count:
          type: integer
          example: 14
          nullable: false
    SearchResult:
      type: object
      properties:
        board:
          $ref: '#/components/schemas/BoardSearchResult'
        page:
          $ref: '#/components/schemas/PageSearchResult'
        card:
          $ref: '#/components/schemas/CardSearchResult'
        project:
          $ref: '#/components/schemas/ProjectSearchResult'
        epic:
          $ref: '#/components/schemas/EpicSearchResult'
        note:
          $ref: '#/components/schemas/NoteSearchResult'
    BoardSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '4'
        title:
          type: string
          example: New <sthl>features</sthl>
        project_id:
          type: string
          example: '2'
        archived:
          $ref: '#/components/schemas/Archived'
        layout:
          $ref: '#/components/schemas/BoardLayout'
    CardSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '13'
        title:
          type: string
          example: Implement new <sthl>service</sthl>
        project_id:
          type: string
          example: '2'
        board_id:
          type: string
          example: '14'
        sprint_id:
          type: string
          example: '1'
        board_title:
          type: string
          example: Ideas
        list_id:
          type: string
          example: '3'
        list_title:
          type: string
          example: Backlog
        list_color:
          type: string
        status:
          $ref: '#/components/schemas/CardStatus'
        owner_id:
          type: string
          example: u123abcd
        members:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        archived:
          $ref: '#/components/schemas/Archived'
        epic:
          $ref: '#/components/schemas/EpicBrief'
        parent_card:
          $ref: '#/components/schemas/ParentCard'
    PageSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '24'
        icon:
          $ref: '#/components/schemas/Image'
        title:
          type: string
          example: Page <sthl>title</sthl>
        project_id:
          type: string
          example: '2'
        excerpt:
          type: string
          example: this is a <sthl>sample</sthl> page content
        archived:
          $ref: '#/components/schemas/ArchivedPage'
    ProjectSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '2'
        icon:
          $ref: '#/components/schemas/Image'
        title:
          type: string
          example: Project <sthl>title</sthl>
        total_members:
          type: integer
          example: 5
        user_id:
          type: string
          example: u2DdoERz
        time_created:
          $ref: '#/components/schemas/STime'
        is_private:
          type: boolean
          example: true
    EpicSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '13'
        title:
          type: string
          example: Implement new <sthl>service</sthl>
        list_id:
          type: string
          example: '3'
        list_title:
          type: string
          example: Backlog
        list_color:
          type: string
        status:
          $ref: '#/components/schemas/CardStatus'
        owner_id:
          type: string
          example: u123abcd
        members:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        archived:
          $ref: '#/components/schemas/Archived'
        icon:
          $ref: '#/components/schemas/Image'
        type:
          type: string
          example: epic
    NoteSearchResult:
      type: object
      properties:
        id:
          type: string
          example: '21'
        title:
          type: string
          example: Page <sthl>title</sthl>
        excerpt:
          type: string
          example: this is a <sthl>sample</sthl> note content
        time_created:
          $ref: '#/components/schemas/STime'
    SuperthreadErrorCode:
      type: string
      description: |
        Superthread Error Code (`SEC`): A structured error code.
        Format: `SEC:{ServiceID}-{InternalErrorCode}`.


          - `SEC`: Prefix for all structured error codes.
          - `ServiceID`: First 3 characters identify the service, '000' is reserved for generic errors.
          - `InternalErrorCode`: the next (last) 5 characters define the specific error.
      pattern: ^SEC:\d{3}-\d{5}$
      example: SEC:000-00014
    STime:
      type: integer
      format: int64
      example: 1608742037016
      description: unix timestamp in seconds
      x-go-type:
        type: STime
        import:
          package: github.com/superthread-com/common/pkg/types
        hints:
          noValidation: true
          kind: primitive
    Archived:
      type: object
      properties:
        user_id:
          type: string
          example: uDsu0j19
        time_archived:
          $ref: '#/components/schemas/STime'
    BoardLayout:
      type: string
      enum:
        - board
        - list
        - timeline
        - calendar
      example: board
      nullable: true
    CardStatus:
      type: string
      enum:
        - committed
        - started
        - completed
        - cancelled
      example: started
    Member:
      type: object
      properties:
        user_id:
          type: string
          example: u-dsu0j19
          x-go-custom-tag: diff:"user_id,identifier"
        assigned_date:
          $ref: '#/components/schemas/STime'
        role:
          $ref: '#/components/schemas/MemberRole'
    EpicBrief:
      type: object
      description: brief view of epic to be used in a card
      properties:
        id:
          type: string
          description: epic id
          example: e-123
        title:
          type: string
          description: epic title
          example: Epic Title
        icon:
          $ref: '#/components/schemas/Image'
    ParentCard:
      type: object
      properties:
        title:
          type: string
          example: Implement service requirements
        card_id:
          type: string
          example: '42'
          x-go-custom-tag: diff:"card_id,identifier"
        list_color:
          type: string
        status:
          $ref: '#/components/schemas/CardStatus'
    Image:
      type: object
      required:
        - type
        - src
      properties:
        type:
          type: string
          enum:
            - image
            - icon
            - emoji
          nullable: false
        id:
          type: string
          description: Unique identifier for the image (optional).
        src:
          type: string
          example: >-
            data:image/png;base64,
            iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
          description: >-
            Depending on the type this can be a URL, base64 image data, emoji
            unicode or an icon name
          nullable: false
        blurhash:
          type: string
          example: LEHV6nWB2yk8pyoJadR*.7kCMdnj
          x-go-custom-tag: dynamodbav:",omitempty"
        color:
          type: string
          example: black
          x-go-custom-tag: dynamodbav:",omitempty"
        emoji:
          type: string
          example: thumbsup
          description: Emoji string ID
          x-go-custom-tag: dynamodbav:",omitempty"
    ArchivedPage:
      type: object
      properties:
        user_id:
          type: string
          example: uDsu0j19
        time_archived:
          $ref: '#/components/schemas/STime'
        parent_page_id:
          type: string
    MemberRole:
      type: string
      enum:
        - admin
        - member
        - viewer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````