--- title: "Create annotation" method: POST path: "/api/v1/annotations" tags: ["Annotation"] --- # Create annotation `POST /api/v1/annotations` Create an annotation object. Normally you create annotations via the [upload](/api/upload#create-upload) endpoint. This endpoint could be used for creating annotation instances including their content and with `status` set to an explicitly requested value. Currently only `created` is supported which is not touched by the rest of the platform and is not visible via the Rossum UI. This allows for subsequent updates before switching the status to `importing` so that it is passed through the rest of the upload pipeline. The use-case for this is the `upload.created` [hook event](/guides/extensions#webhook-extension) where new annotations could be created and the platform runtime then switches all such annotations' status to `importing`. ## Request body - AnnotationBase - `id` integer — ID of the annotation. - `url` string, uri — URL of the annotation. - `status` 'confirmed' | 'created' | 'deleted' | 'exported' | 'exporting' | 'failed_export' | 'failed_import' | 'importing' | 'in_workflow' | 'postponed' | 'purged' | 'rejected' | 'reviewing' | 'split' | 'to_review' — Status of the document, see [Annotation Lifecycle](/guides/annotation-lifecycle) for more details. - `document` string, uri — Related [document](/api/document). - `queue` string, uri — A [queue](/api/queue) that annotation belongs to. - `schema` string, uri — A [schema](/api/schema) that defines content shape. - `relations` string[] — List of relations that annotation belongs to. - `pages` string[] — List of rendered [pages](/api/page). - `creator` string, uri, nullable — User that created the object. - `created_at` string, date-time — Timestamp of object's creation. - `modifier` string, uri, nullable — User that last modified the annotation. - `modified_by` string, uri, nullable — User that last modified the object. - `modified_at` string, date-time, nullable — Timestamp of last modification. - `assigned_at` string, date-time, nullable — Timestamp of last assignment to a user or when the annotation was started being annotated. - `confirmed_at` string, date-time, nullable — Timestamp when the annotation was moved to status `confirmed`. - `deleted_at` string, date-time, nullable — Timestamp when the annotation was moved to status `deleted`. - `exported_at` string, date-time, nullable — Timestamp of finished export. - `export_failed_at` string, date-time, nullable — Timestamp of failed export. - `purged_at` string, date-time, nullable — Timestamp when was annotation purged. - `rejected_at` string, date-time, nullable — Timestamp when the annotation was moved to status `rejected`. - `confirmed_by` string, uri, nullable — User that confirmed the annotation. - `deleted_by` string, uri, nullable — User that deleted the annotation. - `exported_by` string, uri, nullable — User that exported the annotation. - `purged_by` string, uri, nullable — User that purged the annotation. - `rejected_by` string, uri, nullable — User that rejected the annotation. - `rir_poll_id` string, nullable — Internal identifier used by Rossum. - `messages` object[], nullable — List of messages from the connector (save). - `content` string - `id` integer, nullable - `type` 'error' | 'warning' | 'info' - `content` string, uri — Link to annotation content (datapoint values), see [Annotation Content](/api/annotation-content). - `suggested_edit` string, uri, nullable — Link to [Suggested edit](/api/suggested-edit) object. - `time_spent` number, float — Total time spent while validating the annotation. - `metadata` Metadata — Client data. May be used to store e.g. external system object IDs. See [Metadata](/guides/overview#metadata) for more details. - `automated` boolean — Whether annotation was [automated](/guides/automation) - `related_emails` string[] — List of [emails](/api/email) related with annotation. - `email` string, uri, nullable — Related [email](/api/email) that the annotation was imported by (for annotations imported by email). - `automation_blocker` string, uri, nullable — Related [automation blocker](/api/automation-blocker) object. - `email_thread` string, uri, nullable — 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 — Organization URL. - `automatically_rejected` boolean — Indicates whether the annotation was rejected automatically. - `prediction` object, nullable — Internal prediction data including engine version info. - `assignees` string[] — List of assigned users. - `labels` string[] — List of selected [labels](/api/label). - `restricted_access` boolean — Access to annotation is restricted. - `training_enabled` boolean — Flag signalling whether the annotation should be used in the training of the instant learning component. ## Response `201` Created - Annotation - `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. ## 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 - `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)