Parse a search query

GET

/api/v1/search/parse

const url = 'https://example.com/api/v1/search/parse?q=example';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/api/v1/search/parse?q=example'

Parses a search query. It requires a signed-in User with the data scope. It can return 400 if the request is invalid, 401 if the session is missing or expired and 403 if access is denied. Route: /api/v1/search/parse. Inputs: q. Safe reads can use bounded retries.

Parameters

Query Parameters

required

string

Text to search for.

Responses

200

Parsed search words and filters

application/json

The parsed form of a search query. This shape is the cross-client contract for operators; clients can use it to render removable filter pills.

object

filters

required

Filters in query order. Repeated filters are preserved.

Array

One of:

A tag that must match exactly.

object

operator

required

string

Allowed values: tag

value

required

string

A result state such as todo, done, shared, favorite, or a Notes link-health state.

object

operator

required

string

Allowed values: is

value

required

string

terms

required

Plain words and quoted phrases, in query order.

Array<string>

Example

{
  "filters": [
    {
      "operator": "tag"
    }
  ]
}

400

Invalid search query

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}