---
title: "Search annotations"
method: POST
path: "/api/v1/annotations/search"
tags: ["Annotation"]
---
# Search annotations
`POST /api/v1/annotations/search`
Search for annotations matching a complex filter.
Please beware that updates of the annotation search data are done asynchronously and are eventually consistent. Search endpoint may return inconsistent results temporarily (for a few seconds).
Please note that only objects of category `datapoint` are returned when sideloading for `content` is active. Objects of other categories are ignored.
Sideloading content for this endpoint is deprecated and will be removed in the near future.
### Search Query
A subset of MongoDB Query Language. Query expressions should be defined as a list under a `$and` key. The following
can be used:
- `` - Matches against annotation attributes according to the `` - see options below.
- `field..` - Matches against annotation content value according to `` treating it
as a ``. Possible types: `string | number | date` (in ISO 8601 format). Max. 256 characters long strings
are allowed.
**The `meta_field` can be one of:**
| Meta Field | Type |
|-------------------------------------|--------|
| `annotation` | URL |
| `arrived_at` | date |
| `assigned_at` | date |
| `assignees` | URL |
| `automated` | bool |
| `automatically_rejected` | bool |
| `confirmed_at` | date |
| `confirmed_by__username` | string |
| `confirmed_by` | URL |
| `created_at` | date |
| `creator__username` | string |
| `creator` | URL |
| `deleted_at` | date |
| `deleted_by__username` | string |
| `deleted_by` | URL |
| `document` | URL |
| `exported_at` | date |
| `exported_by__username` | string |
| `exported_by` | URL |
| `has_email_thread_with_new_replies` | bool |
| `has_email_thread_with_replies` | bool |
| `has_note` | bool |
| `has_suggested_edit` | bool |
| `labels` | URL |
| `messages` | string |
| `modified_at` | date |
| `modifier__username` | string |
| `modifier` | URL |
| `original_file_name` | string |
| `purged_at` | date |
| `purged_by__username` | string |
| `purged_by` | URL |
| `queue` | URL |
| `rejected_at` | date |
| `rejected_by__username` | string |
| `rejected_by` | URL |
| `relations__key` | string |
| `relations__parent` | URL |
| `relations__type` | string |
| `restricted_access` | bool |
| `rir_poll_id` | string |
| `status` | string |
| `workspace` | URL |
| `email_thread` | URL |
| `email_sender` | string |
**Search Query Objects**
| Key | Type | Description |
|------------------------------------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$startsWith` | string | Matches the start of a value. Must be at least 2 characters long. |
| `$anyTokenStartsWith` | string | Matches the start of each token within a string. Must be at least 2 characters long. |
| `$containsPrefixes` | string | Same as `$anyTokenStartsWith` but query is split into tokens (words). Must be at least 2 characters long. Example query `quick brown` matches `quick brown fox` but also `brown quick dog` or `quickiest brown fox`, but not `quick dog`. |
| `$emptyOrMissing` | bool | Matches values that are empty or missing. When false, matches existing non-empty values. |
| `$eq` | `$ne` | number | string | date | URL | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |
| `$gt` | `$lt` | `$gte` | `$lte` | number | string | date | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |
| `$in` | `$nin` | list[number | string | URL] | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |
## Query parameters
- `ordering` 'id' | '-id' | 'arrived_at' | '-arrived_at' | 'assigned_at' | '-assigned_at' | 'assignees' | '-assignees' | 'automated' | '-automated' | 'confirmed_at' | '-confirmed_at' | 'confirmed_by__username' | '-confirmed_by__username' | 'confirmed_by' | '-confirmed_by' | 'created_at' | '-created_at' | 'creator__username' | '-creator__username' | 'creator' | '-creator' | 'deleted_at' | '-deleted_at' | 'deleted_by__username' | '-deleted_by__username' | 'deleted_by' | '-deleted_by' | 'document' | '-document' | 'exported_at' | '-exported_at' | 'exported_by__username' | '-exported_by__username' | 'exported_by' | '-exported_by' | 'export_failed_at' | '-export_failed_at' | 'has_email_thread_with_new_replies' | '-has_email_thread_with_new_replies' | 'has_email_thread_with_replies' | '-has_email_thread_with_replies' | 'has_note' | '-has_note' | 'has_suggested_edit' | '-has_suggested_edit' | 'labels' | '-labels' | 'modified_at' | '-modified_at' | 'modifier__username' | '-modifier__username' | 'modifier' | '-modifier' | 'original_file_name' | '-original_file_name' | 'purged_at' | '-purged_at' | 'purged_by__username' | '-purged_by__username' | 'purged_by' | '-purged_by' | 'queue' | '-queue' | 'rejected_at' | '-rejected_at' | 'rejected_by__username' | '-rejected_by__username' | 'rejected_by' | '-rejected_by' | 'relations__key' | '-relations__key' | 'relations__parent' | '-relations__parent' | 'relations__type' | '-relations__type' | 'rir_poll_id' | '-rir_poll_id' | 'status' | '-status' | 'workspace' | '-workspace' | 'email_thread' | '-email_thread' | 'email_sender' | '-email_sender'
- `page_size` integer
- `search_after` string
- `fields` string
- `fields!` string
- `sideload` string
- `content.schema_id` string
## Request body
- object
- `query` object — A subset of MongoDB Query Language. If `query_string` is used together with `query`, search is done as a conjunction of these expressions (`query_string` AND `query`).
- `$and` object[] — List of query definitions to be used for search. See [Search Query](#search-query) section for more details.
- `query_string` object — Apply full-text search to datapoint values using a chosen term. The value is searched by its prefix, separately for each term separated by whitespace, in case-insensitive way. Special characters at the end of the strings are ignored. For example, when searching for a term `Large drink`, all of the following values passed would give a match: `lar#`, `lar dri`, `dri`. We search also in the non-extracted page data, if the data are available. If `query_string` is used together with `query`, search is done as a conjunction of these expressions (`query_string` AND `query`).
- `string` string — String to be used for full-text search. At least 2 characters need to be passed to apply this search. Max. 256 characters long strings are allowed.
## Response `200`
OK
- object
- `pagination` PaginationWithTotal, required
- `total` integer — Total number of items.
- `total_pages` integer — Total number of pages.
- `next` string, uri, nullable — URL for the next page of results. Contains an opaque signed `cursor` query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.
- `previous` string, uri, nullable — URL for the previous page of results. Contains an opaque signed `cursor` query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.
- `results` AnnotationSearch[], required
- `id` integer, required — ID of the annotation.
- `url` string, uri, required — URL of the annotation.
- `status` 'confirmed' | 'created' | 'deleted' | 'exported' | 'exporting' | 'failed_export' | 'failed_import' | 'importing' | 'in_workflow' | 'postponed' | 'purged' | 'rejected' | 'reviewing' | 'split' | 'to_review', required — Status of the document, see [Annotation Lifecycle](/guides/annotation-lifecycle) for more details.
- `document` string, uri, required — Related [document](/api/document).
- `queue` string, uri, required — A [queue](/api/queue) that annotation belongs to.
- `schema` string, uri, required — A [schema](/api/schema) that defines content shape.
- `relations` string[], required — List of relations that annotation belongs to.
- `pages` string[], required — List of rendered [pages](/api/page).
- `creator` string, uri, nullable, required — User that created the object.
- `created_at` string, date-time, required — Timestamp of object's creation.
- `modifier` string, uri, nullable, required — User that last modified the annotation.
- `modified_by` string, uri, nullable, required — User that last modified the object.
- `modified_at` string, date-time, nullable, required — Timestamp of last modification.
- `assigned_at` string, date-time, nullable, required — Timestamp of last assignment to a user or when the annotation was started being annotated.
- `confirmed_at` string, date-time, nullable, required — Timestamp when the annotation was moved to status `confirmed`.
- `deleted_at` string, date-time, nullable, required — Timestamp when the annotation was moved to status `deleted`.
- `exported_at` string, date-time, nullable, required — Timestamp of finished export.
- `export_failed_at` string, date-time, nullable, required — Timestamp of failed export.
- `purged_at` string, date-time, nullable, required — Timestamp when was annotation purged.
- `rejected_at` string, date-time, nullable, required — Timestamp when the annotation was moved to status `rejected`.
- `confirmed_by` string, uri, nullable, required — User that confirmed the annotation.
- `deleted_by` string, uri, nullable, required — User that deleted the annotation.
- `exported_by` string, uri, nullable, required — User that exported the annotation.
- `purged_by` string, uri, nullable, required — User that purged the annotation.
- `rejected_by` string, uri, nullable, required — User that rejected the annotation.
- `rir_poll_id` string, nullable, required — Internal identifier used by Rossum.
- `messages` object[], nullable, required — List of messages from the connector (save).
- `content` string
- `id` integer, nullable
- `type` 'error' | 'warning' | 'info'
- `content` string, uri, required — Link to annotation content (datapoint values), see [Annotation Content](/api/annotation-content).
- `suggested_edit` string, uri, nullable, required — Link to [Suggested edit](/api/suggested-edit) object.
- `time_spent` number, float, required — Total time spent while validating the annotation.
- `metadata` Metadata, required — Client data. May be used to store e.g. external system object IDs. See [Metadata](/guides/overview#metadata) for more details.
- `automated` boolean, required — Whether annotation was [automated](/guides/automation)
- `related_emails` string[], required — List of [emails](/api/email) related with annotation.
- `email` string, uri, nullable, required — Related [email](/api/email) that the annotation was imported by (for annotations imported by email).
- `automation_blocker` string, uri, nullable, required — Related [automation blocker](/api/automation-blocker) object.
- `email_thread` string, uri, nullable, required — Related [email thread](/api/email-thread) object.
- `has_email_thread_with_replies` boolean — Related email thread contains more than one `incoming` email.
- `has_email_thread_with_new_replies` boolean — Related email thread contains an unread `incoming` email.
- `organization` string, uri, required — Organization URL.
- `automatically_rejected` boolean, required — Indicates whether the annotation was rejected automatically.
- `prediction` object, nullable, required — Internal prediction data including engine version info.
- `assignees` string[], required — List of assigned users.
- `labels` string[], required — List of selected [labels](/api/label).
- `restricted_access` boolean, required — Access to annotation is restricted.
- `training_enabled` boolean, required — Flag signalling whether the annotation should be used in the training of the instant learning component.
- `has_note` boolean, required — Annotation has at least one note.
- `has_suggested_edit` boolean, required — Annotation has a suggested edit.
## Other responses
- `400` — Invalid input data.
- `401` — The username/password is invalid or token is invalid (e.g. expired).
- `403` — Insufficient permission, missing authentication, invalid CSRF token and similar issue.
- `404` — The specified resource was not found.
- `409` — Conflict
- `410` — Gone - Value of `search_after` is not valid anymore. Retry the search with a different value.
- `413` — Payload too large (especially for files uploaded).
- `429` — Request rate is too high, wait before sending more requests. See [Rate Limiting](/guides/overview#rate-limiting) for more details.
- `500` — Server failure while processing the request.
- `502` — Invalid response from the upstream server.
- `503` — We're temporarily offline for maintenance. Please try again later.
- `504` — Upstream server could not complete the request in time.
---
[API](https://skmtc.dev/rossum/apis/rossum-api.md) · [All operations](https://skmtc.dev/rossum/apis/rossum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rossum/rossum-api/revisions/f1b5a910991d/schema)