Skip to content
calternal docs

Search content

GET
/api/v1/search
curl --request GET \
  --url 'https://example.com/api/v1/search?q=example' \
  --header 'Authorization: Bearer <token>'

Searches for the content. 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. Inputs: q, limit, show_hidden, semantic. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
q
required
string

Text to search for.

limit
integer format: int32
>= 1 <= 200

Most hits each provider may return (1 to 200, default 20). The search window asks for more as the user scrolls its full view.

show_hidden
boolean

Accepted for client compatibility. Search always excludes hidden paths.

semantic
boolean

Return Search Plugin keyword hits only when false. True or omitted keeps hybrid results from every Plugin.

Responses

Section titled “Responses”

200

Section titled “200”

Search results completed before the request deadline

Media typeapplication/json

Results from the server-side search fan-out.

object
indexing
One of:

Search index progress, when an Index is available.

object
completed_items
required

Searchable paths scanned in the current pass.

integer format: int64
indexing
required

True while the Index is being scanned or repaired.

boolean
progress_percent

Percentage of searchable paths scanned, when the scan size is known.

integer | null format: int32
total_items

Total searchable paths in the current pass, when known.

integer | null format: int64
results
required

Search hits returned by providers that completed before the deadline.

Array<object>

A single result from a server-side plugin search provider.

object
href
required

Client route for opening the result.

string
id
required

Stable result identifier within the plugin.

string
kind

Optional result kind from the search grammar (note, task, log, photo, bookmark, text, file, folder, event). Clients group and facet results by it; a missing kind means the provider does not know it.

string | null
mime

Optional media/document MIME type used to render file results consistently.

string | null
modified

Optional last-modified time (or the day of a log entry) in Unix seconds.

integer | null format: int64
path

Optional Home-relative client path of the object (for example Files/plan.pdf, or Shared/<owner>/… for a Share). Clients use it for thumbnails, previews and folder facets.

string | null
plugin_id
required

Plugin that owns the result.

string
score

Optional provider relevance score. Clients must not compare scores from different providers as if they shared one scale.

number | null format: float
snippet

Optional preview text.

string | null
tags

Ordered Event categories. Calendar clients use the first tag for tint.

Array<string> | null
title
required

Main result label.

string
timed_out
required

True when the request deadline stopped one or more providers.

boolean
Examplegenerated
{
  "indexing": {
    "completed_items": 1,
    "indexing": true,
    "progress_percent": 1,
    "total_items": 1
  },
  "results": [
    {
      "href": "example",
      "id": "example",
      "kind": "example",
      "mime": "example",
      "modified": 1,
      "path": "example",
      "plugin_id": "example",
      "score": 1,
      "snippet": "example",
      "tags": [
        "example"
      ],
      "title": "example"
    }
  ],
  "timed_out": true
}

400

Section titled “400”

Invalid search query

Media typeapplication/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:

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"
  }
}

401

Section titled “401”

Authentication is required

Media typeapplication/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:

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"
  }
}

403

Section titled “403”

Data access is required

Media typeapplication/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:

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"
  }
}