/api/v1/search
GET /search — Search for objects (cacheable).
Same as POST /search, but the SearchRequest is passed as a JSON
string in the BODY query parameter instead of in the request body.
This makes the request a plain GET that clients and intermediate
proxies can cache.
Caching stays an explicit opt-in: without cache_seconds the response
carries the default Cache-Control: no-store, no-cache. Pass
cache_seconds to let fylr answer with
Cache-Control: max-age=<cache_seconds>, public instead.
Access token in the Authorization header:
Authorization: Bearer <token>.
The SearchRequest, encoded as a JSON string. The content is the
same as the request body of POST /search.
When greater than 0, fylr replaces the default
Cache-Control: no-store, no-cache response header with
Cache-Control: max-age=<cache_seconds>, public, so the result
can be cached for that many seconds. The parameter works on any
GET endpoint, not just /search.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
The search ran successfully. The response contains the page of
matching objects and the total result count.
The result of a search.
The search domain, echoed from the request.
The object types that were searched.
Primary language of the result.
Total number of objects matching the search.
Offset of the returned page within the full result.
Maximum number of objects in the returned page.
Render format of the objects in the response.
The merge_linked_objects mode applied, echoed from the request.
The merge_max_depth applied, echoed from the request.
The search request could not be processed. The code field of the
response identifies which validation rejected the request. The
schema below lists the stable codes and shows a concrete example.
A malformed request body or a structural query error (for example a
search element with a missing or unknown type, or an unknown
bool) returns a generic error envelope without one of these stable
codes — treat a missing or unknown code as a generic bad request.
No authenticated user. The request must carry a valid access token.
The requesting user lacks a required system right — for example a
search with type: event needs system.api.event[get].
POST /search — Search for objects.
Run a search and return the matching objects.
The request body is a SearchRequest. Its search property holds a list
of search elements that are combined into a single boolean query. Each
element has a type — one of text, in, range, changelog_range,
complex, nested, geo_bounding_box or geo_shape (match is a
legacy alias of text) — and a bool that decides whether it must,
should or must_not match. Elements of type complex and nested
group further elements, so arbitrarily nested queries can be expressed.
By default the search runs over the indexed objects. Set type on the
request to search a different domain instead: pool, collection,
event, message, user, group or acl.
Only objects the requesting user is allowed to read are returned. The
response reports the total count together with the objects of the
requested page and any requested aggregations.
Access token in the Authorization header:
Authorization: Bearer <token>.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
Describes a search to run against fylr. The search property holds
the query; the remaining properties control paging, sorting, the response
format and aggregations.
Domain to search. Omit (or use an empty string) to search indexed objects. Each other domain has its own object shape in the response.
Restrict the search to these object types. When empty, all object types are searched.
Number of hits to skip before the first returned object.
Maximum number of objects to return.
Render format for the objects in the response, for example standard
or long.
Controls whether linked objects are embedded into the hits.
Maximum depth up to which linked objects are embedded when
merge_linked_objects is used.
Languages to load for localized fields.
If true, objects in the trash are included in the result.
Field name used when this request is a sub search.
If set, only these fields are included in the returned objects.
Fields to omit from the returned objects.
Number of days the signed file URLs in the response stay valid.
Timezone used when interpreting and bucketing dates.
If true, the effective rights are generated for each hit.
If true, each object is reduced to the best mask the user may see.
The search ran successfully. The response contains the page of
matching objects and the total result count.
The result of a search.
The search domain, echoed from the request.
The object types that were searched.
Primary language of the result.
Total number of objects matching the search.
Offset of the returned page within the full result.
Maximum number of objects in the returned page.
Render format of the objects in the response.
The merge_linked_objects mode applied, echoed from the request.
The merge_max_depth applied, echoed from the request.
The search request could not be processed. The code field of the
response identifies which validation rejected the request. The
schema below lists the stable codes and shows a concrete example.
A malformed request body or a structural query error (for example a
search element with a missing or unknown type, or an unknown
bool) returns a generic error envelope without one of these stable
codes — treat a missing or unknown code as a generic bad request.
No authenticated user. The request must carry a valid access token.
The requesting user lacks a required system right — for example a
search with type: event needs system.api.event[get].
GET /search/parse — Parse a query string into a search request.
Same as POST /search/parse, but the parse options are passed as query
parameters instead of in a request body.
Access token in the Authorization header:
Authorization: Bearer <token>.
The query string to parse.
Restrict the search to these object types. Repeat the parameter for more than one object type.
If true, run the parsed search and return its result instead of the
parsed SearchRequest.
Maximum number of objects to return.
Number of objects to skip before the first returned object.
Render format for the objects in the result.
Timezone used when interpreting dates in the query string.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
The query string was parsed. The response is the parsed
SearchRequest when search is false, or the search result when
search is true.
The request could not be processed. More than one failure maps to
this status — the code field of the response says which one. The
schema below lists the stable codes and shows a concrete example.
A malformed request body returns a generic error envelope without
one of these stable codes — treat a missing or unknown code as a
generic bad request.
No authenticated user. The request must carry a valid access token.
POST /search/parse — Parse a query string into a search request.
Parse a query string written in fylr's search query language into the
SearchRequest structure that /search expects.
With search set to false (the default) the parsed SearchRequest is
returned, so a client can inspect or adjust it before searching. With
search set to true the parsed request is executed right away and the
search result is returned instead.
Access token in the Authorization header:
Authorization: Bearer <token>.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
Options for parsing a query string at /search/parse.
The query string to parse.
Restrict the search to these object types.
If true, run the parsed search and return its result instead of the
parsed SearchRequest.
Maximum number of objects to return.
Number of objects to skip before the first returned object.
Render format for the objects in the result.
Timezone used when interpreting dates in the query string.
The query string was parsed. The response is the parsed
SearchRequest when search is false, or the search result when
search is true.
The request could not be processed. More than one failure maps to
this status — the code field of the response says which one. The
schema below lists the stable codes and shows a concrete example.
A malformed request body returns a generic error envelope without
one of these stable codes — treat a missing or unknown code as a
generic bad request.
No authenticated user. The request must carry a valid access token.
DELETE /search/point_in_time — Close point-in-time search contexts.
Close one or more point-in-time (PIT) search contexts. A PIT is opened by
a search that sets point_in_time and is used to keep a stable view of
the index across paginated requests. Closing a PIT frees the resources it
holds in the search backend; PITs that are not closed expire on their own
after their keep_alive.
Access token in the Authorization header:
Authorization: Bearer <token>.
The access token in form of Bearer <token>. You can also use authorization
which does the same. authorization is looked at first.
The access token in form of Bearer <token>.
IDs of the point-in-time contexts to close.
The point-in-time contexts were closed.
The request could not be processed — typically a malformed JSON
payload or a failure from the search backend when closing the
point-in-time. The errors raised here are wrapped generic errors,
so the response uses the standard envelope without a specific
stable code.
Last updated