Skip to main content
GET
Get search results

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

team_id
string
required

Team ID is an alphanumerical string that identifies a Team. This is externally referred to as a "Workspace".

Query Parameters

query
string
required

Search query

cursor
string

cursor for pagination

count
integer

max number of items to return. defaults to 25

types
enum<string>

Types of object you would like to search against. includes all types if not specified

Available options:
boards,
cards,
pages,
projects
fields
enum<string>

Fields you would like to target in the free text search

Available options:
title,
content
archived
boolean

Whether or not to include archived data. defaults to false

statuses
enum<string>

Card statuses to filter by

Available options:
backlog,
committed,
started,
completed,
cancelled
project_ids
string[]

Projects (spaces) to search in. Repeat the parameter for several (project_ids=1&project_ids=2).

project_id
string

Deprecated and ignored by the search service; kept for compatibility. Use project_ids.

grouped
boolean

Whether the results will be grouped by type (as opposed to all under the 'results' prop). defaults to true

highlight
boolean

Whether matching result text may include highlight markup. defaults to false

highlight_pre_tag
string

Opening tag wrapping highlighted terms in title and excerpt fields. Defaults to .

highlight_post_tag
string

Closing tag wrapping highlighted terms in title and excerpt fields. Defaults to .

mode
enum<string>
default:bm25

How results are matched and ranked. Defaults to bm25.

  • bm25: keyword search. Results match the query's words and are ranked by

    how well they match.

  • semantic: results are ranked by closeness in meaning to the query, so

    they need not contain its words. Each result carries a score. Results below a fixed minimum similarity to the query are not returned, so a query with nothing close to it returns no results. A page or note's excerpt is the passage that matched best. fields and the highlight parameters do not apply, so titles and excerpts carry no highlight markup. count is the number of results on the page rather than a total, because every document is ranked and there is no set of matches to count. The query is limited to 1000 characters. Pagination works as in bm25 mode, to the same depth, and stops once results fall below that minimum.

  • hybrid: combines the two rankings, so results either contain the query's

    words or are close to it in meaning, and a result both find ranks highest. A result found by its words is highlighted as in bm25 mode; one found only by meaning has no highlights, and a page or note's excerpt is the passage that matched best. score is set when the result is close in meaning to the query and null when it was found only by its words. count is the number of results on the page, the query is limited to 1000 characters, and pagination works as in bm25 mode, to the same depth. A query that is an id or a card or page reference is answered as in bm25 mode.

A mode the workspace cannot serve is rejected with a 400. modes on the response lists the ones it can.

Available options:
bm25,
semantic,
hybrid

Response

Search results

cursor
string
required
Example:

"dmsjqh9d8w1hdjosjaasda"

count
integer
required
Example:

14

results
object[]
boards
object[]
cards
object[]
pages
object[]
projects
object[]
epics
object[]
notes
object[]
request_id
string

Identifies this search request. It is generated by the server and recorded against the request, so a client reporting which result a user went on to open can tie that back to the search that produced it.

Example:

"0b6f3a52-6a1e-4d7c-9f1b-3c2e8d4a5b67"

modes
enum<string>[]

The search modes this workspace can serve, for the mode parameter.

How a search matches and ranks results. bm25 is keyword search, semantic ranks by closeness in meaning, and hybrid combines the two.

Available options:
bm25,
semantic,
hybrid