\"\n\n@app.route(\"/test_hook\", methods=[\"POST\"])\ndef test_hook():\n digest = hmac.new(SECRET_KEY.encode(), request.data, hashlib.sha256).hexdigest()\n try:\n prefix, signature = request.headers[\"X-Rossum-Signature-SHA256\"].split(\"=\")\n except ValueError:\n abort(401, \"Incorrect header format\")\n\n if not (prefix == \"sha256\" and hmac.compare_digest(signature, digest)):\n abort(401, \"Authorization failed.\")\n return\n```\n\nFor authorization of payloads, the [shared secret](https://en.wikipedia.org/wiki/Shared_secret) method is used.\nWhen a secret token is set in [`hook.config.secret`](/api/hook), Rossum uses it to create a hash signature with each payload.\nThis hash signature is passed along with each request in the headers as `X-Rossum-Signature-SHA256`.\n\nThe goal is to compute a hash using [`hook.config.secret`](/api/hook) and the request body,\nand ensure that the signature produced by Rossum is the same. Rossum uses HMAC SHA256 signature by default.\n\nPreviously, Rossum was using SHA1 algorithm to sign the payload. This option is\nstill available as a legacy `X-Elis-Signature` header. Please contact\nRossum support to enable this header in case it is missing.\n\n\nThe algorithm used is the same as the one of Github.\n\n\nWebhook requests may also be authenticated using a client SSL certificate, see\n[Hook](/api/hook) API for reference.\n\n### Access to Rossum API\n\nYou can access Rossum API from the Webhook. Each execution gets unique API key. The key is valid\nfor 10 minutes or until Rossum receives a response from the Webhook. You can set `token_lifetime_s` up to 2 hours to keep\nthe token valid longer. The API key and the environment's base URL are passed to webhooks as a first-level attributes\n`rossum_authorization_token` and `base_url` within the webhook payload.\n\n\nThe `rossum_authorization_token` field is only included in the payload when the hook has a `token_owner` configured.\n\n\n## Serverless Function Extension\n\nServerless functions allow to extend Rossum functionality without setup and\nmaintenance of additional services.\n\n[Webhooks](/api/hook) and Serverless functions share a basic setup: input and output data\nformat and error handling. They are both configured using a [hook](/api/hook) API\nobject.\n\nUnlike webhooks, serverless functions do not send the event and action\nnotifications to a specific URL. Instead, the function's *code* snippet is\nexecuted within the Rossum platform. See [function](/api/hook) API\ndescription for details about how to set up a serverless function and connect it\nto the queue.\n\nFor description of supported events, actions and input/output data examples,\nplease refer to [Webhook Extensions](/api/hook)\nsection.\n\n### Supported runtimes\n\nCurrently, Rossum supports [NodeJS](https://nodejs.org/) and [Python](https://www.python.org/) to execute serverless\nfunctions. See the table below for a full list of supported runtimes. If you would like to use another runtime,\nplease let us know at product@rossum.ai.\n\nPlease be aware that we may eventually deprecate and remove runtimes in the future.\n\n| Name | Identifier | Deprecation date | Block function creation date | Removal date | Note |\n|-------------|--------------|-------------------|------------------------------|-------------------|--------------------------------------------------------------|\n| Python 3.12 | `python3.12` | not scheduled | not scheduled | not scheduled | |\n| NodeJS 22 | `nodejs22.x` | not scheduled | not scheduled | not scheduled | |\n\n#### Runtime deprecations\n\nWe schedule runtime deprecation when it is being phased out by the serverless vendors. The recommended action\nis to upgrade to one of the up-to-date runtimes.\n\nSee the table above for specific deprecation dates of individual runtimes.\n\n- **Deprecation date** - Date when the deprecation is announced.\n- **Block function creation date** - From this date, it will not be possible to create new extensions with the\ndeprecated runtime. Existing extensions can be used as they are and their code can be updated until the removal date.\n- **Removal date** - All extensions will be automatically switched to the up-to-date runtime on this date.\nWe recommend making the switch earlier to test and update the code if needed, to avoid any issues.\n\n#### Python Runtime and Rossum Transaction Scripts\n\nThe `python3.12` runtime includes a `txscript` module that provides [convenience\nfunctionality](/guides/rossum-transaction-scripts) for working with Rossum objects,\nin particular in the context of the `annotation_content` event.\n\n### Implementation\n\n```python\n'''\nThis custom serverless function example demonstrates showing messages to the\nuser on the validation screen, updating values of specific fields, and\nexecuting actions on the annotation.\n\nSee https://elis.rossum.ai/api/docs/#rossum-transaction-scripts for more examples.\n'''\n\nfrom txscript import TxScript, default_to, substitute\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n\n for row in t.field.line_items:\n if default_to(row.item_amount_base, 0) >= 1000000:\n t.show_warning('Value is too big', row.item_amount_base)\n\n t.field.document_id = substitute(r'-', '', t.field.document_id)\n\n if default_to(t.field.amount_total, 0) > 1000000:\n print(\"postponing\")\n t.annotation.action(\"postpone\")\n return t.hook_response()\n\n return t.hook_response()\n```\n\n```javascript\n// This serverless function example can be used for annotation_content events\n// (e.g. updated action). annotation_content events provide annotation\n// content tree as the input.\n//\n// The function below shows how to:\n// 1. Display a warning message to the user if \"item_amount_base\" field of\n// a line item exceeds a predefined threshold\n// 2. Removes all dashes from the \"invoice_id\" field\n//\n// item_amount_base and invoice_id should be fields defined in a schema.\n\nexports.rossum_hook_request_handler = async (payload) => {\n const content = payload.annotation.content;\n\n try {\n const TOO_BIG_THRESHOLD = 1000000;\n\n const amountBaseColumnDatapoints = findBySchemaId(\n content,\n 'item_amount_base',\n );\n\n const messages = [];\n for (var i = 0; i < amountBaseColumnDatapoints.length; i++) {\n\n if (amountBaseColumnDatapoints[i].content.normalized_value >= TOO_BIG_THRESHOLD) {\n messages.push(\n createMessage(\n 'warning',\n 'Value is too big',\n amountBaseColumnDatapoints[i].id,\n ),\n );\n }\n }\n\n const [invoiceIdDatapoint] = findBySchemaId(content, 'invoice_id');\n\n const operations = [\n createReplaceOperation(\n invoiceIdDatapoint,\n invoiceIdDatapoint.content.value.replace(/-/g, ''),\n ),\n ];\n\n return {\n messages,\n operations,\n };\n } catch (e) {\n const messages = [\n createMessage('error', 'Serverless Function: ' + e.message)\n ];\n return {\n messages,\n };\n }\n};\n\nconst findBySchemaId = (content, schemaId) =>\n content.reduce(\n (results, dp) =>\n dp.schema_id === schemaId ? [...results, dp] :\n dp.children ? [...results, ...findBySchemaId(dp.children, schemaId)] :\n results,\n [],\n );\n\nconst createMessage = (type, content, datapointId = null) => ({\n content: content,\n type: type,\n id: datapointId,\n});\n\nconst createReplaceOperation = (datapoint, newValue) => ({\n op: 'replace',\n id: datapoint.id,\n value: {\n content: {\n value: newValue,\n },\n },\n});\n```\n\nTo implement a serverless function, create a [hook](/api/hook) object of type\n`function`. Use `code` object config attribute to specify a serialized source\ncode. You can use a code editor built-in to the Rossum UI, which also allows to\ntest and debug the function before updating the code of the function itself.\n\nSee Python and NodeJS examples of a serverless function implementation next to this section\nor check out this article (and\nothers in the relevant section).\n\n\nPlease note that users are responsible for their code that is being executed.\nBe sure not to expose any sensitive data or trigger excessive usage of the function API.\nIn case of violation of the Rossum terms of use, the organization account may\nbe suspended.\n\n\nIf there is an issue with an extension code itself, it will be displayed as `CallFunctionException` in the\nannotation view. Raising this exception usually means issues such as:\n\n* undefined variables are called in the code\n* the code is raising an exception as a response rather than returning a proper response\n\n\n### Testing\nTo write, test and debug a serverless function, you can refer to this guide.\n\n### Limitations\n\nBy default, no internet access is allowed from a serverless function, except\nthe Rossum API. If your functions require internet access to work properly,\ne.g. when exporting data over API to ERP system, please let us know at\nproduct@rossum.ai.\n\n### Access Rossum API\n\nThe Rossum API can be accessed directly from serverless functions. See\nexamples below for how to access the Rossum API from a serverless function.\n\n```python\nimport json\nimport urllib.request\n\ndef rossum_hook_request_handler(payload):\n request = urllib.request.Request(\n \"https://example.rossum.app/api/v1/queues\",\n headers={\"Authorization\": \"Bearer \" + payload[\"rossum_authorization_token\"]}\n )\n with urllib.request.urlopen(request) as response:\n queues = json.loads(response.read())\n queue_names = (q[\"name\"] for q in queues[\"results\"])\n return {\"messages\": [{\"type\": \"info\", \"content\": \", \".join(queue_names)}]}\n```\n\n```javascript\nconst https = require('https');\n\nexports.rossum_hook_request_handler = async (payload) => {\n const token = payload.rossum_authorization_token;\n\n queues = JSON.parse(await getFromRossumApi(\"https://example.rossum.app/api/v1/queues\", token));\n queue_names = queues.results.map(q => q.name).join(\", \")\n return { \"messages\": [{\"type\": \"info\", \"content\": queue_names}] };\n}\n\nconst getFromRossumApi = async (url, token) => {\n const parsedUrl = new URL(url);\n const options = {\n hostname: parsedUrl.hostname,\n path: parsedUrl.pathname + parsedUrl.search,\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer ' + token,\n },\n };\n const response = await new Promise((resolve, reject) => {\n let dataString = '';\n const req = https.request(options, function(res) {\n res.on('data', chunk => {\n dataString += chunk;\n });\n res.on('end', () => {\n resolve({\n statusCode: 200,\n body: dataString\n });\n });\n });\n req.on('error', (e) => {\n reject({\n statusCode: 500,\n body: 'Something went wrong!'\n });\n });\n req.end()\n });\n return response.body\n}\n\n```\n\n\n## Connector Extension\n\n\n[Webhooks](/api/hook) are more recent and flexible alternative to connectors.\nFor new implementations, consider using webhooks.\n\n\nThe connector component is aimed at two main use-cases: applying custom business rules\nduring data validation, and direct integration of Rossum with downstream systems.\n\nThe connector component receives two types of callbacks - an on-the-fly validation\ncallback on every update of captured data, and an on-export save callback when the\ndocument capture is finalized.\n\nThe custom business rules take use chiefly of the on-the-fly validation callback.\nThe connector can auto-validate and transform both the initial AI-based extractions\nand each user operator edit within the validation screen; based on the input, it can\npush user-visible messages and value updates back to Rossum. This allows for both simple\ntweaks (like verifying that two amounts sum together or transforming decimal points\nto thousand separators) and complex functionality like intelligent PO match.\n\nThe integration with downstream systems on the other hand relies mainly on the save\ncallback. At the same moment a document is exported from Rossum, it can be imported\nto a downstream system. Since there are typically constraints on the captured data,\nthese constraints can be enforced even within the validation callback.\n\n### Implement a connector\n\n\nThe Extension Howto\non our Developer Hub is a good starting point when building your own connector.\n\n\nConnectors are designed to be implemented using a push-model using common HTTPS\nprotocol. When annotation content is changed, or when data export is triggered,\nspecific connector endpoint is called with annotation data as a request payload.\nThe connector must be deployed with a public IP address so that the Rossum platform\ncan call its endpoints; for testing, a middleware like [ngrok](https://ngrok.com/) or\n[serveo](https://serveo.net/) may come useful.\n\nExample of a valid no-op (empty) validate response:\n\n```json\n{\"messages\": [], \"updated_datapoints\": []}\n```\n\nExample of a valid no-op (empty) save response:\n\n```json\n{}\n```\n\nExample data sent to connector (validate, save):\n\n```json\n{\n \"meta\": {\n \"document_url\": \"https://example.rossum.app/api/v1/documents/6780\",\n \"arrived_at\": \"2019-01-30T07:55:13.208304Z\",\n \"original_file\": \"https://example.rossum.app/api/v1/original/bf0db41937df8525aa7f3f9b18a562f3\",\n \"original_filename\": \"Invoice.pdf\",\n \"queue_name\": \"Invoices\",\n \"workspace_name\": \"EU\",\n \"organization_name\": \"East West Trading Co\",\n \"annotation\": \"https://example.rossum.app/api/v1/annotations/4710\",\n \"queue\": \"https://example.rossum.app/api/v1/queues/63\",\n \"workspace\": \"https://example.rossum.app/api/v1/workspaces/62\",\n \"organization\": \"https://example.rossum.app/api/v1/organizations/1\",\n \"modifier\": \"https://example.rossum.app/api/v1/users/27\",\n \"updated_datapoint_ids\": [\"197468\"],\n \"modifier_metadata\": {},\n \"queue_metadata\": {},\n \"annotation_metadata\": {},\n \"rir_poll_id\": \"54f6b9ecfa751789f71ddf12\",\n \"automated\": false\n },\n \"content\": [\n {\n \"id\": \"197466\",\n \"category\": \"section\",\n \"schema_id\": \"invoice_info_section\",\n \"children\": [\n {\n \"id\": \"197467\",\n \"category\": \"datapoint\",\n \"schema_id\": \"invoice_number\",\n \"page\": 1,\n \"position\": [916, 168, 1190, 222],\n \"rir_position\": [916, 168, 1190, 222],\n \"rir_confidence\": 0.97657,\n \"value\": \"FV103828806S\",\n \"validation_sources\": [\"score\"],\n \"type\": \"string\"\n },\n {\n \"id\": \"197468\",\n \"category\": \"datapoint\",\n \"schema_id\": \"date_due\",\n \"page\": 1,\n \"position\": [938, 618, 1000, 654],\n \"rir_position\": [940, 618, 1020, 655],\n \"rir_confidence\": 0.98279,\n \"value\": \"12/22/2018\",\n \"validation_sources\": [\"score\"],\n \"type\": \"date\"\n },\n {\n \"id\": \"197469\",\n \"category\": \"datapoint\",\n \"schema_id\": \"amount_due\",\n \"page\": 1,\n \"position\": [1134, 1050, 1190, 1080],\n \"rir_position\": [1134, 1050, 1190, 1080],\n \"rir_confidence\": 0.74237,\n \"value\": \"55.20\",\n \"validation_sources\": [\"human\"],\n \"type\": \"number\"\n }\n ]\n },\n {\n \"id\": \"197500\",\n \"category\": \"section\",\n \"schema_id\": \"line_items_section\",\n \"children\": [\n {\n \"id\": \"197501\",\n \"category\": \"multivalue\",\n \"schema_id\": \"line_items\",\n \"children\": [\n {\n \"id\": \"198139\",\n \"category\": \"tuple\",\n \"schema_id\": \"line_item\",\n \"children\": [\n {\n \"id\": \"198140\",\n \"category\": \"datapoint\",\n \"schema_id\": \"item_desc\",\n \"page\": 1,\n \"position\": [173, 883, 395, 904],\n \"rir_position\": null,\n \"rir_confidence\": null,\n \"value\": \"Red Rose\",\n \"validation_sources\": [],\n \"type\": \"string\"\n },\n {\n \"id\": \"198142\",\n \"category\": \"datapoint\",\n \"schema_id\": \"item_net_unit_price\",\n \"page\": 1,\n \"position\": [714, 846, 768, 870],\n \"rir_position\": null,\n \"rir_confidence\": null,\n \"value\": \"1532.02\",\n \"validation_sources\": [\"human\"],\n \"type\": \"number\"\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\nThe connector API consists of two endpoints, [validate](#endpoint-validate) and [save](#endpoint-save),\ndescribed below.\nA connector must always implement both endpoints (though they may not necessarily\nperform a function in a particular connector - see the right column for an empty\nreply example), the platform raises an error if it is not able to run an endpoint.\n\n\nIn case a custom connector extension is deployed by a user in production, it should follow our best practices:\n\n- run on HTTPS and have a valid public certificate\n
- be fast enough to keep up the pace with Rossum interactive behavior\n
- be able to receive traffic from any IP address. (Source IP address may change over time.)\n
- require authentication by authentication token to prevent data leaks or forgery\n
\n\n\n### Setup a connector\n\nThe next step after implementing the first version of a connector is configuring it\nin the Rossum platform.\n\nIn Rossum, a [connector object](/api/connector) defines `service_url` and `params` for\nconstruction of HTTPS requests and `authorization_token` that is passed in\nevery request to authenticate the caller as the actual Rossum server. It may also\nuniquely identify the organization when multiple Rossum organizations share the\nsame connector server.\n\nTo set up a connector for a [queue](/api/queue), create a\n[connector object](/api/connector) using our API – follow these instructions.\nA connector object may be associated with one or more queues. One queue can only have one connector object associated with it.\n\n### Connector API\n\nAll connector endpoints, representing particular points in the\ndocument lifetime, are simple verbs that receive a JSON `POST`ed and\npotentially expect a JSON returned in turn.\n\nThe authorization type and authorization token is passed as an `Authorization`\nHTTP header. Authorization type may be `secret_key` (shared secret) or `Basic`\nfor [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).\n\nPlease note that for Basic authentication, `authorization_token` is passed\nas-is, therefore it must be set to a correct base64 encoded value. For example\nusername `connector` and password `secure123` is encoded as\n`Y29ubmVjdG9yOnNlY3VyZTEyMw==` authorization token.\n\nConnector requests may be authenticated using a client SSL certificate, see\n[Connector](/api/connector) API for reference.\n\n#### Errors\n\nIf a connector does not implement an endpoint, it may return HTTP status 404.\nAn endpoint may fail, returning either HTTP 4xx or HTTP 5xx; for some endpoints\n(like validate and save), this may trigger a user interface message;\neither the **error** key of a JSON response is used, or the response body\nitself in case it is not JSON. The connector endpoint save can be called\nin asynchronous (default) as well as synchronous mode (useful for\n[embedded mode](/guides/embedded-mode)).\n\n#### Data format\n\nThe received JSON object contains two keys, `meta` carrying the metadata and `content`\ncarrying endpoint-specific content.\n\nThe metadata identify the concerned document, containing attributes:\n\n| Key | Type | Description |\n|------------------------------------|--------------|-----------------------------------------------------------------|\n| [document_url](/api/document) | URL | [document](/api/document) URL |\n| arrived_at | timestamp | A time of document arrival in Rossum (ISO 8601) |\n| [original_file](/api/document#retrieve-document-content) | URL | Permanent URL for the document [original file](/api/document#retrieve-document-content) |\n| original_filename | string | Filename of the document on arrival in Rossum |\n| [queue_name](/api/queue) | string | Name of the document's queue |\n| [workspace_name](/api/workspace) | string | Name of the document's workspace |\n| [organization_name](/api/organization) | string | Name of the document's organization |\n| [annotation](/api/annotation) | URL | Annotation URL |\n| [queue](/api/queue) | URL | Document's queue URL |\n| [workspace](/api/workspace) | URL | Document's workspace URL |\n| [organization](/api/organization) | URL | Document's organization URL |\n| modifier | URL | Modifier URL |\n| modifier_metadata | object | Metadata attribute of the modifier, see [metadata](/guides/overview#metadata) |\n| queue_metadata | object | Metadata attribute of the queue, see [metadata](/guides/overview#metadata) |\n| annotation_metadata | object | Metadata attribute of the annotation, see [metadata](/guides/overview#metadata) |\n| rir_poll_id | string | Internal extractor processing ID |\n| updated_datapoint_ids | list[string] | IDs of objects that were recently modified by user |\n| automated | bool | Flag whether annotation was [automated](/guides/automation) |\n\nA common class of content is the **annotation tree**, which is a JSON object\nthat can contain nested datapoint objects, and matches the schema datapoint tree.\n\nIntermediate nodes have the following structure:\n\n| Key | Type | Description |\n|-----------|---------|-----------------------------------------------|\n| id | integer | A unique ID of the given node |\n| schema_id | string | Reference mapping the node to the schema tree |\n| category | string | One of *section*, *multivalue*, *tuple* |\n| children | list | A list of other nodes |\n\nDatapoint (leaf) nodes structure contains actual data:\n\n| Key | Type | Description |\n|----------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------|\n| id | integer | A unique ID of the given node |\n| schema_id | string | Reference mapping the node to the schema tree |\n| category | string | *datapoint* |\n| type | string | One of *string*, *date* or *number*, as specified in the [schema](/guides/queue-schema) |\n| value | string | The datapoint value, string represented but normalizes, to that they are machine readable: ISO format for dates, a decimal for numbers |\n| page | integer | A 1-based integer index of the page, optional |\n| position | list[float] | List of four floats describing the x1, y1, x2, y2 bounding box coordinates |\n| rir_position | list[float] | Bounding box of the value as detected by the data extractor. Format is the same as for `position`. |\n| rir_confidence | float | Confidence (estimated probability) that this field was extracted correctly. |\n\n\nNote that for both meta and content the set of keys returned is subject to extension.\n\n\n#### Annotation lifecycle with a connector\nIf an asynchronous connector is deployed to a queue, an annotation status will change from `reviewing` to `exporting` and subsequently to `exported` or `failed_export`. If no connector extension is deployed to a queue or if the attribute `asynchronous` is set to `false`, an annotation status will change from `reviewing` to `exported` (or `failed_export`) directly.\n\n### Endpoint: validate\n\nThis endpoint is called after the document processing has finished, when operator opens a document\nin the Rossum verification interface and then every time after operator updates a field. After the\nprocessing is finished, the initial validate call is marked with `initial=true` URL parameter.\nFor the other calls, only `/validate` without the parameter is called. Note that after document processing, initial \nvalidation is followed by [business rules](/api/rule) execution for both `validation` and `annotation_imported` events. \n\nThe request path is fixed to `/validate` and cannot be changed.\n\nIt may:\n\n* validate the given annotation tree and return a list of messages commenting on it\n(e.g. pointing out errors or showing matched suppliers).\n* update the annotation tree by returning a list of replace, add and remove operations\n\nBoth the messages and the updated data are shown in the verification\ninterface. Moreover, the messages may block confirmation in the case of errors.\n\nThis endpoint should be fast as it is part of an interactive workflow.\n\nReceives an annotation tree as **content**.\n\nReturns a JSON object with the lists: `messages`, `operations` and `updated_datapoints`.\n\n#### Keys `messages`, `operations` (optional)\n\nThe description of these keys was moved to the [Hook Extension](/api/hook).\n\n#### Key `updated_datapoints` (optional, deprecated)\n\nWe also support a simplified version of updates using `updated_datapoints`\nresponse key. It only supports updates (no add or remove operations) and is now\ndeprecated. The updated datapoint object contains attributes:\n\n| Key | Type | Description |\n|----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------|\n| id | string | A unique ID of the relevant datapoint, currently only datapoints of category `datapoint` can be updated |\n| value | string | New value of the datapoint. Value is formatted according to the datapoint type (e.g. date is string representation of ISO 8601 format). |\n| hidden | boolean | Toggle for hiding/showing of the datapoint, see [datapoint](/guides/queue-schema#datapoint) |\n| options | list[object] | Options of the datapoint -- valid only for `type=enum`, see [enum options](/guides/queue-schema#enum) |\n| position | list[float] | New position of the datapoint, list of four numbers. |\n\nValidate endpoint should always return *200 OK* status.\n\nAn *error* message returned from the connector prevents user from confirming the document.\n\n### Endpoint: save\n\nThis endpoint is called when the invoice transitions to the `exported` state.\nConnector may process the final document annotation and save it to the target\nsystem. It receives an annotation tree as `content`. The request path is fixed\nto `/save` and cannot be changed.\n\nThe save endpoint is called asynchronously (unless synchronous mode is set) in\nrelated [connector object](/api/connector). Timeout of the save endpoint is 60\nseconds.\n\n\nThe save endpoint configuration influences the document state flow - when the document\nleaves the reviewing state, it enters the exporting state in case the save\nendpoint is called asynchronously. Otherwise, it transitions straight to the exported\nstate.\n\n\nFor successful export, the request should have *2xx* status.\n\nExample of successful save responses without messages in UI:\n\n```http\nHTTP/1.1 204 No Content\n```\n\n```http\nHTTP/1.1 200 OK\nContent-Type: text/plain\n\nthis response body is ignored\n```\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"messages\": []\n}\n```\n\nWhen messages are expected to be displayed in the UI, they should be sent in the\nsame format as in [validate endpoint](#endpoint-validate).\n\nExample of successful save response with messages in UI:\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"messages\": [\n {\n \"content\": \"Everything is OK.\",\n \"id\": null,\n \"type\": \"info\"\n }\n ]\n}\n```\n\nIf the endpoint fails with an HTTP error and/or message of type `error` is received,\nthe document transitions to the `failed_export` state - it is then available\nto the operators for manual review and re-queueing to the `to_review` state\nin the user interface. Re-queueing may be done also programmatically via\nthe API using a PATCH call to set `to_review` annotation status. Patching\nannotation status to `exporting` state triggers an export retry.\n\nExample of failed save response with messages in UI:\n\n```http\nHTTP/1.1 422 Unprocessable Entity\nContent-Type: application/json\n\n{\n \"messages\": [\n {\n \"content\": \"Even though this message is info, the export will fail due to the status code.\",\n \"id\": null,\n \"type\": \"info\"\n }\n ]\n}\n```\n\nExample of failed save response with messages in UI:\n\n```http\nHTTP/1.1 500 Internal Server Error\nContent-Type: text/plain\n\nAn error message \"Export failed.\" will show up in the UI\n```\n\nExample of failed save response with messages in UI:\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"messages\": [\n {\n \"content\": \"Proper status code could not be set.\",\n \"id\": null,\n \"type\": \"error\"\n }\n ]\n}\n```\n\n\nIn the future, 5xx error status may cause automatic retries on the Rossum side.\nCurrently, no automatic retries are performed.\n\n\n## Custom UI Extension\n\nSometimes users might want to extend the behavior of UI validation view with something special. That should be the goal of custom UI extensions.\n\n### Buttons\n\nCurrently, there are two different ways of using a custom button:\n\n1. Popup Button - opens a specific URL in the web browser\n2. Validate Button - triggers a standard validate call to connector\n\nIf you would like to read more about how to create a button, see the [Button schema](/guides/queue-schema#schema-content).\n\n#### Popup Button\n\nPopup Button opens a website completely managed by the user in a separate tab. It runs in parallel to the validation interface session in the app. Such website can be used for any interface that will assist operators in the reviewing process.\n\nExample Use Cases of Popup Button:\n\n1. opening an email linked to the annotated document\n2. creating a new item in external database according to extracted data\n\n#### Communication with the Validation Interface\n\n\nCalling Rossum API from a popup outside the scope of the calls described below is not possible.\n\n\nYou can communicate with the validation interface directly\nusing standard browser API of window.postMessage.\nYou will need to use window.addEventListeners in order to receive messages\nfrom the validation interface:\n\n```javascript\nwindow.addEventListener('message', ({ data: { type, result } }) => {\n // logic\n});\n```\n\nThe shape of the `result` key is the same as the top level `content`\nattribute of the [annotation content](/api/annotation-content) response.\n\nOnce the listener is in place, you can post one of supported message types:\n\n* `GET_DATAPOINTS` - returns the same tree structure you'd get by requesting annotation content\n\n```javascript\nwindow.opener.postMessage(\n { type: 'GET_DATAPOINTS' },\n 'https://example.rossum.app'\n)\n```\n\n* `UPDATE_DATAPOINT` - sends updated value to a Rossum datapoint. Only one datapoint value can be updated\nat a time.\n\n```javascript\nwindow.opener.postMessage(\n {\n type: 'UPDATE_DATAPOINT',\n data: {id: DATAPOINT_ID, value: \"Updated value\"}\n },\n 'https://example.rossum.app'\n)\n```\n\n\n\n* `FINISH` - informs the Rossum app that the popup process is ready to be closed.\n After this message is posted, popup will be closed and Rossum app will trigger a validate call.\n\n```javascript\nwindow.opener.postMessage(\n { type: 'FINISH' },\n 'https://example.rossum.app'\n);\n```\n\nProviding message type to postMessage lets Rossum interface know what operation\nuser requests and determines the type of the answer which could be used to\nmatch appropriate response.\n\n#### Validate button\nIf `popup_url` key is missing in button's schema, clicking the button will trigger a standard validate call to connector. In such call, `updated_datapoint_ids` will contain the ID of the pressed button.\n\nNote: if you're missing some annotation data that you'd like to receive in a similar way, do contact our support team. We're collecting feedback to further expand this list.\n\n## Extension Logs\n\nFor easy and efficient development process of the extensions, our backend logs `requests`, `responses` (if enabled) and\nadditional information, when the hook is being called.\n\n### Hook Log\n\nThe hook log objects consist of following attributes, where it also differentiates between the hook events as follows:\n\n#### Base Hook Log object\n\nThese attributes are included in all the logs independent of the hook event\n\n| Key | Type | Description | Optional |\n|----------------------------------|--------|------------------------------------------------------------------------------------------------------|----------|\n| timestamp* | str | Timestamp of the log-record | |\n| request_id | UUID | [Hook](/api/hook) call request ID | |\n| event | string | Hook's [event](/api/events) | |\n| action | string | Hook's [action](/api/actions) | |\n| [organization_id](/api/organization) | int | ID of the associated [Organization](/api/organization). |\n| [queue_id](/api/queue) | int | ID of the associated [Queue](/api/queue). | true |\n| [hook_id](/api/hook) | int | ID of the associated [Hook](/api/hook). | |\n| hook_type | str | Hook type. Possible values: `webhook`, `function` | |\n| log_level | str | Log-level. Possible values: `INFO`, `ERROR`, `WARNING` | |\n| message | str | A log-message | |\n| request | str | Raw request sent to the Hook | true |\n| response | str | Raw response received from the Hook | true |\n\n*Timestamp is of the ISO 8601 format with UTC timezone e.g. `2023-04-21T07:58:49.312655`\n\n\n#### Annotation Content or Annotation Status Hook Events\n\nIn addition to the Base Hook Log object, the `annotation content` and `annotation status` event hook logs contains\nthe following attributes:\n\n| Key | Type | Description | Optional |\n|------------------------------|------|-------------------------------------------------|----------|\n| [annotation_id](/api/annotation) | int | ID of the associated [Annotation](/api/annotation). | true |\n\n\n#### Email Hook Events\n\nIn addition to the Base Hook Log object, the `email` event hook logs contains the following attributes:\n\n| Key | Type | Description | Optional |\n|--------------------|------|---------------------------------------|----------|\n| [email_id](/api/email) | int | ID of the associated [Email](/api/email). | true |\n\n\n## Source IP Address ranges\n\nRossum will use these source IP addresses for outgoing connections to your\nservices (e.g. when sending requests to a webhook URL):\n\nEurope (Ireland):\n\n* 34.254.110.123\n* 52.209.175.153\n* 54.217.193.239\n* 54.246.127.143\n\nEurope 2 (Frankfurt):\n\n* 3.75.26.254\n* 3.126.211.68\n* 3.126.98.96\n* 3.76.159.143\n\nUS (N. Virginia):\n\n* 3.222.161.192\n* 50.19.104.88\n* 52.2.120.212\n* 18.213.174.191\n\nJP (Tokyo):\n\n* 3.115.38.171\n* 35.74.141.62\n* 35.75.49.12\n* 52.194.128.167\n\nYou can use the list to limit incoming connections on a firewall. The list may be\nupdated eventually, please update your configuration at least once per three months.\n"
},
{
"name": "Rossum Transaction Scripts",
"description": "The Rossum platform can evaluate snippets of Python code that can manipulate\nbusiness transactions processed by Rossum - Transaction Scripts (or TxScripts).\nThe principal use of these TxScript snippets is\nto automatically fill in computed values of `formula` type fields.\nThe code can be also evaluated as a serverless function based extension that is\nhooked to the `annotation_content` event.\n\nThe TxScript Python environment is based on Python 3.12 or newer,\nin addition including a variety of additional predefined functions and variables.\nThe environment has been designed so that code operating on Rossum objects\nis very short, easy to read and write by both humans and LLMs, and many simple\ntasks are doable even by non-programmers (who could however e.g. build\nan Excel spreadsheet).\n\nThe environment is special in the following ways:\n\n* Predefined variables allowing easy access to Rossum objects.\n\n* Some environment-specific helper functions and aliases.\n\n* How code is evaluated specifically in formula field context to yield a computed value.\n\n\nRight now, the TxScript environment is geared just towards the annotation_content\nevent. Ultimately, we plan to provide TxScript coverage for all provided events.\n\n\nThe TxScript environment provides accessors to Rossum objects associated with\nthe event that triggered the code evaluation.\nThe event context is generally available through a `txscript.TxScript` object;\ncalling the object methods and modifying the attributes (such as raising\nmessages or modifying field values) controls the event hook response.\n\nBasic TxScript usage in a serverless function:\n\n```python\nfrom txscript import TxScript\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n print(t)\n return t.hook_response()\n```\n\nIn serverless functions,\nthis object must be explicitly imported and instantiated using a `.from_payload()`\nfunction. The `.hook_response()` method yields a dict representing the\nprescribed event hook response (with keys such as `\"messages\"`, `\"operations\"`\netc.) that can be directly returned from the handler.\n\nMeanwhile, in formula fields it is instantiated automatically and its existence is\nentirely transparent to the developer as the object's attributes and methods are\ndirectly available as globals of the formula fields code.\n\n\nThe txscript package is published on PyPI.\nYou can install it yourself with pip install txscript and execute scripts locally.\n\n\n\n## Pythonized Rossum objects\n\nThe TxScript environment provides instances of several pertinent Rossum objects.\nThese instances are directly available in globals namespace in formula fields, and\nas attributes of the `TxScript` instance within serverless functions.\n\n\n### Fields Object\n\nA `field` object is provided that allows access to the fields of\nannotation content.\n\n#### Attributes\n\nObject attributes correspond to annotation fields, e.g. `field.amount_total` will evaluate\nto the value of the `amount_total` field. The attributes behave specially:\n\n* The field value types are pythonized. String fields are `str` type, number fields\n are `float` type, date fields are `datetime.date` instances.\n\n* Since number fields are of type `float`, they should always be rounded when tested for\n equality (because e.g. 0.1 + 0.2 isn't exactly 0.3 in floating-point arithmetics):\n `round(field.amount_total, 2) == round(field.amount_total_base, 2)`\n\nExample using `all_values` property:\n\n```python\nif all(not is_empty(field.item_amount_base.all_values)):\n sum(default_to(field.item_amount_tax.all_values, 0) * 0.9 + field.item_amount_base.all_values)\n```\n\n* You can access all in-multivalue field ids (table columns or simple multivalues)\n via the `.all_values` property (e.g. `field.item_amount.all_values`). Its value\n is a special sequence object `TableColumn` that behaves similarly to a `list`,\n but with operators applying elementwise or distributive to scalars (NumPy-like).\n Outside a single row context, the `.all_values` property is the only legal way\n to work with these field ids. It is also a way to access a row of another multivalue \n from a multivalue formula.\n\nExample iterating over multivalue rows in a formula:\n\n```python\nfor row in field.line_items:\n if not is_empty(row.item_amount) and row.item_amount < 0:\n show_warning(\"Negative amount\", row.item_amount)\n```\n\nExample iterating over multivalue rows in a serverless function:\n\n```python\nfrom txscript import TxScript, is_empty\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n for row in t.field.line_items:\n if not is_empty(row.item_amount) and row.item_amount < 0:\n t.show_warning(\"Negative amount\", row.item_amount)\n return t.hook_response()\n```\n\n* You can access individual multivalue tuple rows by accessing the multivalue or tuple field ID,\n which provides a list of `field`-like objects that provide in-row tuple field members\n as attributes named by their field id.\n\n* While `field.amount_total` evaluates to a float-like value (or other types),\n the value also provides an `attr` attribute that gives access to all\n field schema, field object value and field object value content API object attributes\n (i.e. one can write `field.amount_total.attr.rir_confidence`). Attributes\n `position`, `page`, `validation_sources`, `hidden` and `options` are read-write.\n\n* Fields that are not set (or are in an error state due to an invalid value)\n evaluate to a `None`-like value (except strings which evaluate to `\"\"`),\n but because of the above they are in fact not pure Python `None`s. Therefore,\n they **must not** be tested for using `is None`. Instead, convenience helpers\n `is_empty(field.amount_total)` and `default_to(field.amount_total, 0)` should be used.\n These helpers also behave correctly on string fields as well.\n\nExample using `is_empty` and `default_to` helpers:\n\n```python\nfrom txscript import TxScript, is_empty, default_to\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n\n if not is_empty(t.field.amount_tax_base):\n # Note: This type of operation is strongly discouraged in serverless\n # functions, since the modification is non-transparent to the user and\n # it is hard to trace down which hook modified the field.\n # Always prefer making amount_total a formula field!\n t.field.amount_total = t.field.amount_tax_base + default_to(t.field.amount_tax, 0)\n\n # Merge po_number_external to the po_numbers multivalue\n if not is_empty(t.field.po_number_external):\n t.field.po_numbers.all_values.remove(t.field.po_number_external)\n t.automation_blocker(\"External PO\", t.field.po_numbers)\n else:\n t.field.po_number_external.attr.hidden = True\n\n # Filter out non-empty line items and add a discount line item\n t.field.line_items = [row for row in t.field.line_items if not is_empty(row.item_amount)]\n if \"10% discount\" in t.field.terms and not is_empty(t.field.amount_total):\n t.field.line_items.append({\"item_amount\": -t.field.amount_total * 0.1, \"item_description\": \"10% discount\"})\n t.field.line_items[-1].item_amount.attr.validation_sources.append(\"connector\")\n t.field.line_items[-1].item_description.attr.validation_sources.append(\"connector\")\n\n t.field.po_match.attr.options = [{\"label\": f\"PO: {po}\", \"value\": po} for po in t.field.po_numbers.all_values]\n t.field.po_match.attr.options += t.field.default_po_enum.attr.options\n # Update the currently selected enum option if the value fell out of the list\n if (\n len(t.field.po_match.attr.options) > 0\n and t.field.po_match not in [po.value for po in t.field.po_match.attr.options]\n ):\n t.field.po_match = t.field.po_match.attr.options[0].value\n\n return t.hook_response()\n```\n\n* You can assign values to the field attributes and modify the multivalue lists,\n which will be reflected back in the app once your hook finishes. (This is not\n permitted in the read-only context of formula fields.) You may construct\n values of tuple rows as dicts indexed by column schema ids.\n\n* You can modify the `field.*.attr.validation_sources` list and it will be\n reflected back in the app once your hook finishes. It is not recommended\n to perform any operation except `.append(\"connector\")` (automates the field).\n\n* For `enum` type fields, you can modify the `field.*.attr.options` list\n and it will be reflected back in the app once your hook finishes. Elements of\n the list are objects with the `label` and `value` attribute each. You may\n construct new elements as dicts with the `label` and `value` keys.\n\n* Outside of formula fields, you may access fields dynamically by computed schema\n ID (for example based on configuration variables) by using standard Python's\n `getattr(field, schema_id)`. Note that inside formula fields, such dynamic\n access is not supported as it breaks automatic dependency tracking and formula\n field value would not be recomputed once the referred field value changes.\n\n* You may also access the parent of nested fields (within multivalues and/or\n tuples) via their `.parent` attribute, or the enclosing multivalue field via\n `.parent_multivalue`. This is useful when combined with the `getattr` dynamic\n field access. For example, in the default Rossum schema naming setup,\n `getattr(field, \"item_quantity\").parent_multivalue == field.line_items`.\n\n\nWhen referring to formula field values within TxScript, note that their value\nmay be out of date in case one of their inputs was modified during the same\nTxScript context - their value is recomputed only once TxScript evaluation\nfinishes. (However, at the beginning of each hook, all formula field values\nare guaranteed to be up to date.) Please note that any of this behavior may change in the future.\n\n\n\n### Annotation Object\n\nAn `annotation` object is provided, representing the pertinent annotation.\n\n#### Attributes\n\nThe available attributes are: `id`, `url`, `status` `previous_status`, `automated`, `automatically_rejected`, `einvoice`, `metadata`, `created_at`, `modified_at`, `exported_at`, `confirmed_at`, `assigned_at`, `export_failed_at`, `deleted_at`, `rejected_at`, `purged_at`\n\nThe timestamp attributes, such as `created_at`, are represented as a python `datetime` instance.\n\n\nYou can format a python datetime to your format of choice using `annotation.created_at.strftime(\"%m/%d/%Y, %H:%M:%S\")`.\n\n\nThe `raw_data` attribute is a dict containing all attributes\nof the [annotation](/api/annotation) API object.\n\nThe `annotation` also has a `document` attribute. The `document` itself has the following attributes: `id`, `url`, `arrived_at`, `created_at`, `original_file_name`, `metadata`, `mime-type`, see [document](/api/document) for more details. `raw_data` is also provided.\n\nThis enables txscript code such as `annotation.document.original_file_name`.\n\nThe `annotation` also has an optional `email` attribute. The `email` itself has the following attributes: `id`, `url`, `created_at`, `last_thread_email_created_at`, `subject`, `email_from` (identical to `from` on API), `to`, `cc`, `bcc`, `body_text_plain`, `body_text_html`, `metadata`, `annotation_counts`, `type`, `labels`, `filtered_out_document_count`, see [email](/api/email) for more details. `raw_data` is also provided.\n\nThis enables txscript code such as `annotation.email.subject`.\n\n\nIn a hook context, the `email` is available only if emails are sideloaded.\n\n\nExample of rejecting an annotation:\n\n```python\nfrom txscript import TxScript\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n if round(t.field.amount_total) != round(t.field.amount_total_base + t.field.amount_tax):\n annotation.action(\"reject\", note_content=\"Amounts do not match\")\n if t.field.amount_total > 100000:\n annotation.action(\"postpone\")\n return t.hook_response()\n```\n\n#### Methods\n\nThe `action(verb: str, **args)` method issues a `POST` on the [annotation](/api/annotation)\nAPI object for a given verb in the form `POST /v1/annotations/{id}/{verb}`, passing\nadditional arguments as specified.\n(Notable verbs are `reject`, `postpone` and `delete`.)\n\nNote that Rossum authorization token passing must be enabled on the hook.\n\n\n## TxScript Functions\n\nSeveral functions are provided that map 1:1 to common extension hook return values.\nThese functions are directly available in globals namespace in formula fields, and\nas methods of the `TxScript` instance within serverless functions.\n\nExample of raising a message in a formula field:\n\n```python\nif field.date_issue < date(2024, 1, 1):\n show_warning(\"Issue date long in the past\", field.date_issue)\n```\n\nExample of raising a message in serverless function hook:\n\n```python\nfrom txscript import TxScript\n\ndef rossum_hook_request_handler(payload: dict) -> dict:\n t = TxScript.from_payload(payload)\n if t.field.date_issue < date(2024, 1, 1):\n t.show_warning(\"Issue date long in the past\", field.date_issue)\n return t.hook_response()\n```\n\nThe `show_error()`, `show_warning()` and `show_info()` functions raise a message,\neither document-wide or attached to a particular field. As arguments, they take\nthe message text (`content` key) and optionally the field to attach the message to\n(converted to the `id` key). If no field is passed or if the field references \na multivalue column, a document-level message is created.\n\nFor example, you may use `show_error()` for fatals like a missing required field,\nwhereas `show_info()` is suitable to decorate a supplier company ID with its name\nas looked up in the suppliers database.\n\nExample of a formula raising an automation blocker:\n\n```python\nif not is_empty(field.amount_total) and field.amount_total < 0:\n automation_blocker(\"Total amount is negative\", field.amount_total)\n```\n\nThe `automation_blocker()` function analogously\nraises an automation blocker, creating [automation blockers](/api/automation-blocker)\nof type `extension` and therefore stopping the\n[automation](/guides/automation) without the need to create an error message.\nThe function signature is the same as for the methods shown above.\n\n\n## Helper Functions and Aliases\n\nWhenever a helper function is available, it should be used preferentially.\nThis is for the sake of better usability for admin users, but also because\nthese functions are e.g. designed to seamlessly work with `TableColumn`\ninstances.\n\nAll identifiers below are directly available in globals namespace in formula fields.\nWithin serverless functions, they can be imported as `from txscript import ...`\n(or all of them obtained via `from txscript import *`).\n\n### Helper Functions\n\nThe `is_empty(field.amount_total)` boolean function returns True if the given\nfield has no value set. Use this instead of testing for None.\n\nThe `default_to(field.order_id, \"INVALID\")` returns either the field value,\nor a fallback value (string INVALID in this example) in case it is not set.\n\n### Convenience Aliases\n\nAll string manipulations should be performed using `substitute(...)`,\nwhich is an alias for `re.sub`.\n\nThese identifiers are automatically imported:\n\n`from datetime import date, timedelta`\n\n`import re`\n\n\n## Formula Fields\n\nThe Rossum Transaction Scripts can be evaluated in the context of\na formula-type field to automatically compute its value.\n\nIn this context, the `field` object is read-only, i.e. side-effects on\nvalues of other fields are prohibited (though you can still attach a message\nor automation blocker to another field).\n\nThe `annotation` object is available, including the `annotation.document` and\n`annotation.email` sideloads (see [Annotation Object](#annotation-object) above\nfor available attributes).\n\nThis example sets the formula field value to either 0 or the output of the specified regex substitution:\n\n```python\nif field.order_id == \"INVALID\":\n show_warning(\"Falling back to zero\", field.order_id)\n \"0\"\nelse:\n substitute(r\"[^0-9]\", r\"\", field.order_id)\n```\n\nThe Python code is evaluated just as Python's interactive mode would run it,\nusing the last would-be printed value as the formula field value. In other words,\nthe value of the last evaluated expression in the code is used as the new value\nof the field.\n\nIn case the field is within a multivalue tuple, it is evaluated for each\ncell of that column, i.e. within each row. Referring to other fields within\nthe row via the `field` object accesses the value of the respective single row cell\n(just like the `row` object when iterating over multivalue tuple rows). Referring\nto fields outside the multivalue tuple via the `field` object still works as usual.\nThus, in a definition of `field.item_amount` formula, `field.item_quantity` refers\nto the quantity value of the current row, while you can still also access\n`field.amount_total` header field. Further, `field._index` provides the row number.\n\nField dependencies of formula fields are determined automatically. The only caveat\nis that in case you iterate over line item rows within the formula field code, you\nmust name your iterator `row`.\n"
},
{
"name": "Using Triggers",
"description": "Trigger REST operations can be found [here](/api/trigger)\n\nWhen an event occurs, all triggers of that type will perform actions of their related objects:\n\n| Related object | Action | Description |\n|--------------------------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [Email template](/guides/using-triggers#triggering-email-templates) | Send email with the template to the event triggerer if `automate=true` | Automatically respond to document vendors based on the document's content. The document has to come from an email |\n| [Delete recommendations](/api/delete-recommendation) | Stop automation if one of the validation rules applies to the processed document | Based on the user's rules for delete recommendations, stop automation for the document which applies to these rules. The document requires manual evaluation |\n\n\n\n\nIf you have a Hook and a Trigger configured for same event, the Hook action will be executed first\n\n\n\n## Trigger Event Types\n\nTrigger objects can have one of the following event types:\n\n| Trigger Event type | Description (Trigger for an event of) |\n|---------------------------------------|-----------------------------------------------------------------------|\n| email_with_no_processable_attachments | An Email has been received without any processable attachments |\n| annotation_created | Processing of the Annotation started (Rossum received the Annotation) |\n| annotation_imported | Annotation data have been extracted by Rossum |\n| annotation_confirmed | Annotation was checked and confirmed by user (or automated) |\n| annotation_exported | Annotation was exported. Only triggered for non-automated annotations that have an associated email |\n| validation | Document is being validated |\n\n### Trigger Events Occurrence Diagram\n\nTo show an overview of the Trigger events and when they are happening, this diagram was created.\n\n\n\n## Trigger Condition\n\nA subset of MongoDB Query Language. The annotation will get converted into JSON records behind the scenes. \nThe trigger gets activated if at least one such record matches the condition according to the [MQL query rules](https://www.mongodb.com/docs/manual/reference/mql/). \nA `null` condition matches any record, just like `{}`. Record format:\n\n\n {\n \"field\": {\n \"{schema_id}\": string | null,\n },\n \"required_field_missing\": boolean,\n \"missing_fields\": string[],\n }\n\n\nExample trigger condition with AND operator:\n\n```json\n{\n \"$and\": [\n {\n \"field.vendor_id\": {\n \"$and\": [\n {\"$exists\": true},\n {\"$regex\": \"Meat ltd\\\\.\"}\n ]\n }\n }\n ]\n}\n```\n\nExample on how to check if any of the required fields are missing:\n\n```json\n{\n \"$and\": [\n {\"required_field_missing\": true}\n ]\n}\n```\n\nThis example shows how to use the AND operator to check for multiple conditions. \nIn this case, the trigger will be activated if the vendor ID exists and matches the regex pattern \"Milk( inc\\\\.)?\" and if the required field is missing.\n\n```json\n{\n \"$and\": [\n {\n \"field.vendor_id\": {\n \"$and\": [\n {\"$exists\": true},\n {\"$regex\": \"Milk( inc\\\\.)?\"}\n ]\n }\n },\n {\"required_field_missing\": true}\n ]\n}\n```\n\nExample checking for specific document type:\n\n```json\n{\n \"$or\": [\n {\n \"field.document_type\": {\"$eq\": \"invoice\"}\n }\n ]\n}\n```\n\nExample checking field value range:\n\n```json\n{\n \"$or\": [\n {\n \"field.vendor_id\": {\n \"$or\": [\n {\"$regex\": \"Milk( inc\\\\.)?\"},\n {\"$regex\": \"Barn( inc\\\\.)?\"} \n ]\n }\n }\n ]\n}\n```\n\nExample checking for high amount:\n\n```json\n{\n \"$or\": [\n {\n \"number_of_pages\": {\n \"$gt\": 10\n }\n }\n ]\n}\n```\n\nSupported MQL subset based on the trigger event type:\n\nAll trigger event types:\n\n\n {}\n\n\nOnly `annotation_imported`, `annotation_confirmed`, and `annotation_exported` trigger event types:\n\n\n {\n \"$and\": [\n {\"field.{schema_id}\": {\"$and\": [{\"$exists\": true}, REGEX]}}\n ]\n }\n\n\nOnly `annotation_imported` trigger event type:\n\n\n {\n \"$and\": [\n {\"field.{schema_id}\": {\"$and\": [{\"$exists\": true}, REGEX]}},\n {\"required_field_missing\": true},\n {\"missing_fields\": {\"$elemMatch\": {\"$in\": list[str[schema_id]]}}\n ]\n }\n\n\nOnly `validation` trigger event type:\n\n\n {\n \"$or\": [\n {\"field.document_type\": {\"$in\": list[str[document_type]]},\n {\"field.language\": {\"$in\": list[str[language]]},\n {\"field.currency\": {\"$in\": list[str[currency]]},\n {\"number_of_pages\": {\"$gt\": 10},\n {\"filename\": REGEX}\n ]\n }\n\n\n\n {\n \"$or\": [\n {\"field.document_type\": {\"$in\": list[str[document_type]]},\n {\"field.language\": {\"$in\": list[str[language]]},\n {\"field.currency\": {\"$in\": list[str[currency]]},\n {\"number_of_pages\": {\"$gt\": 10},\n {\"filename\": {\"$or\": [REGEX, REGEX]}\n ]\n }\n\n\n\n| Field | Required | Description |\n|--------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------|\n| field.{schema_id} | | A field contained in the Annotation data. The `schema_id` is the [schema](/api/schema) ID it got extracted under |\n| required_field_missing | | Any of the [schema](/api/schema)-required fields is missing. (*) Can not be combined with `missing_fields` |\n| missing_fields | | At least one of the [schema](/api/schema) fields is missing. (*) Can not be combined with `required_field_missing` |\n| field.{validation_field} | | A field contained a list of Delete Recommendation data. The `validation_field` is the [schema](/api/schema) ID it got extracted under |\n| number_of_pages | | A threshold value for the number of pages. A document with more pages is matched by the trigger. |\n| filename | | The filename or subset of filenames of the document is to match. |\n| REGEX | true | Either `{\"$regex\": re2}` or `{\"$not\": {\"$regex\": re2}}`**. Uses [re2 regex syntax](https://github.com/google/re2/wiki/Syntax) |\n\n(*) A field is considered missing if any of the two following conditions is met\n\n- the field has [ui_configuration](/guides/queue-schema#schema-content) of type `captured` or `null` and no value was extracted for it and `rir_confidence` [score](/guides/automation#ai-confidence-scores) is at least 0.95\n\n- the field has [ui_configuration](/guides/queue-schema#schema-content) of other types (`data`, `manual`, `formula`, ...) and has an empty value\n\n\n(**) The `$not` option for REGEX is not valid for the `validation` trigger.\n\n## Triggering Email Templates\n\nEmail template REST operations can be found [here](/api/email-template).\n\nTo set up email template trigger automation, link an email template object to a trigger object and set its `automate`\nattribute to `true`. Currently, only one trigger can be linked. To set up the recipient(s) of the automated emails,\nyou can use [built-in placeholders](/api/email#send-email) or direct values in the `to`, `cc`, and `bcc`\nfields in email templates.\n\nOnly some email template types and some trigger event types can be linked together:\n\n| Template type | Allowed trigger events |\n|---------------------------------------|---------------------------------------|\n| custom | * |\n| email_with_no_processable_attachments | email_with_no_processable_attachments |\n| rejection | annotation_imported |\n| rejection_default | annotation_imported |\n\n\nEmail templates of type `rejection` and `rejection_default` will also reject the associated annotation when triggered.\n\nEvery newly created queue has [default email templates](/api/email-template). Some of them have a trigger linked,\nincluding an email template of type `email_with_no_processable_attachments` which can not have its trigger unlinked\nor linked to another trigger. To disable its automation, set its `automate` attribute to `false`.\n\n## Triggering Validation\n\nDelete Recommendation REST operations can be found [here](/api/delete-recommendation).\n\nTo set up validation trigger automation, specify the rules for validation and set its enabled attribute to `true`.\n\nThis trigger is only valid for the `validation` trigger event.\n\n## Hooks and Triggers Workflow\n\nSometimes it may happen that there is a need to know, what triggers and hooks and when are they run. That can be found in this workflow.\n\n\n"
},
{
"name": "Workflow Guide",
"description": "Beta\nThis feature must be explicitly enabled in [queue settings](/api/queue).\n\n\nTalk with a Rossum representative about enabling this feature.\n\n\n## Approval workflows\nApproval workflows allow you to define multiple steps of approval process.\n\nThe workflow is started when the data extraction process is done (annotation is [confirmed](/api/annotation#confirm-validation)) - it enters `in_workflow` status.\nThen the annotation must be [approved](/api/annotation#approve-annotation) by defined approvers in order to be moved further (`confirmed` or `exported` status).\n\nThe annotation is moved to `rejected` status if one of the assignees [rejects](/api/annotation#reject-annotation) it.\n\n\nThe resources used for configuration of workflows ([workflow](/api/workflow), [workflow step](/api/workflow-step)) have read-only API at the moment. Please, contact Rossum support if you wish to change it.\n\n\nThe current status of workflow is stored in [workflow run](/api/workflow-run) object. All the events that happened during workflow can be tracked down by [workflow activity](/api/workflow-activity) resources.\n"
},
{
"name": "Embedded Mode",
"description": "In some use-cases, it is desirable to use only the per-annotation validation view of\nthe Rossum application.\nRossum may be integrated with other systems using so-called [embedded mode](https://knowledge-base.rossum.ai/docs/embedding-ai-powered-data-capture-in-your-document-management-workflow).\n\nIn embedded mode, special URL is constructed and then used in iframe or popup\nbrowser window to show Rossum annotation view. Some view navigation widgets are hidden\n(such as *home*, *postpone* and *delete* buttons), so that user is only allowed to update\nand confirm all field values.\n\nEmbedded mode can be used to view annotations only in status to_review, reviewing, postponed, or confirmed.\n\nFor security reasons it is strongly recommended to use `annotator_embedded` [user role](/api/user-role) for this feature\nas this user role has limited permissions to only be able to interact with resources necessary for embedded validation screen.\n\n\nSee the embedded mode in action in our embedded demo sample.\n\n\n\nTalk with a Rossum representative about enabling this feature.\n\n\n## Embedded mode workflow\n\nThe host application first [uploads a document](/api/upload#create-upload) using standard Rossum\nAPI. During this process, an [annotation](/api/annotation) object\nis created. It is possible to obtain a [status](/guides/annotation-lifecycle) of the annotation object and wait for\nthe status to become `to_review` (ready for checking) using [annotation](/api/annotation#retrieve-annotation) endpoint.\n\nAs soon as importing of the annotation object has finished, an authenticated user\nmay call [start_embedded](/api/annotation#start-validation-for-embedded-use) endpoint to obtain a URL that is\nto be included in iframe or popup browser window of the host application. Parameters of the call\nare `return_url` and `cancel_url` that are used to redirect to in a browser when user finishes\nthe annotation.\n\nThe URL contains security token that is used by embedded Rossum application to access Rossum API.\nWhen the checking of the document has finished, user clicks\non *done* button and host application is notified about finished annotation through\n`save` endpoint of the connector HTTP API. By default, this call is made asynchronously, which\ncauses a lag (up to a few seconds) between the click on *done* button and the call to `save`\nendpoint. However, it is possible to switch the calls to synchronous mode by switching the\n`connector` `asynchronous` toggle to `false` (see [connector](/api/connector) for reference).\n"
},
{
"name": "FAQ",
"description": "## SSL connection errors\n\nRossum API only supports TLS 1.2 to ensure that [up-to-date algorithms and ciphers](https://security.googleblog.com/2018/10/modernizing-transport-security.html) are used.\n\nOlder SSL libraries may not work properly with TLS 1.2. If you encounter\nSSL/TLS compatibility issue, please make sure the library supports TLS 1.2 and\nthe support is switched on.\n"
},
{
"name": "Annotation Content",
"description": "Annotation content is used by the Rossum UI to display annotation content. Be aware that\nvalues in attribute value are not normalized (e.g. numbers, dates) and data\nstructure may be changed to accommodate UI requirements.\n\n\nUse export endpoint to download extracted data using a stable interface with normalized values. It supports various data formats (JSON, XML, CSV).\n\n\n#### Time Spent\n\nTime spent on datapoint are in seconds and are stored on datapoint object,\nfor category multivalue or datapoint. For time spent on the annotation level,\nsee annotation processing duration.\n\nActive time spent is stored in time_spent. Overall time spent is stored in\ntime_spent_overall. Active time spent with an active magic grid is stored in\ntime_spent_grid. Overall time spent with an active magic grid is stored in\ntime_spent_grid_overall.\n\nMeasuring starts when an annotation is not in a read-only mode after selecting\na datapoint.\n\nMeasuring ends when:\n* Another datapoint is selected. Selecting of datapoints when showing automation blockers doesn’t end or affect the measuring.\n* The user leaves an annotation (for the same reasons as measuring ends on an annotation)\n* The user goes to edit mode\n\nWhen a measuring ends time_spent of the previously selected datapoint is incremented\nby measured time_spent and the result is patched together with adding a human validation\nsource to validation sources.\n\n#### Formula Datapoints\n\nFor `datapoint` category fields which have their schema UI configuration's `type`\nproperty set to formula the datapoint content and attributes are being updated\nautomatically based on the provided formula code.\n\nFor editable formula fields (i.e. the corresponding UI configuration's `edit`\nproperty is not set to disabled option) the automatic recalculation can be\ndisabled by setting the datapoint no_recalculation flag to true. To re-enable\nthe formula automatic recalculation set the `no_recalculation` flag to `false`.\n\n\nUpdates of formula datapoints properties and values via API are only available for invocations\ndone from the UI.\n\n\n#### Validation Source\n\nThe `validation_sources` property is a list of sources that verified the extracted data. When the list is non-empty, datapoint is considered to be validated (and no eye-icon is displayed next to it in the Rossum UI).\n\nCurrently, these are the sources of validation:\n - score: confidence score coming from the AI Core Engine was equal or higher than a preset score threshold (can be set on queue, or individually per datapoint in schema; default is 0.8).\n - checks: Data extractor does several checks like summing up tax_details, which can verify that the data were extracted correctly.\n - not_found: Value was not found by the AI engine. As we do not report confidence in such cases yet, we add a validation source instead. It will be removed as soon as we have confidence present for field that were not found.\n - data_matching: Set by a hook when, for example, the datapoint matches some other database.\n - history: Several fields can be confirmed from historical data in exported documents (can be turned on/off on per queue basis using autopilot section in its settings).\n - connector: A connector verified the validity.\n - table_suggester: Used internally for the complex line items user interface.\n - rules: Added from rules and actions on a queue.\n - einvoicing: Used when the value is verified against e-invoicing data sources or external e-invoicing systems.\n - human: An operator visited the field in validation interface (assumed just verifying the value, not necessarily making any corrections).\n - non_required: Value was not found, is non-required and has no rir_field_name set.\n - NA: Validation sources are \"Not Applicable\" and may now occur only for button datapoints.\n\nThe list is subject to ongoing expansion.\n\n#### Grid\n\nGrid object (for internal use only) is used to store table vertical and horizontal separators and related attributes. Every grid consists of\nzero or more `parts`.\n\nCurrently, it is only allowed to have one part per page (for a particular grid).\n\n\nIf two or more tables that should be extracted are present on one page, the grid\nobject should be placed over the area of all of them. The parts that do not\ninclude the needed data should be marked as a row with `\"type\": null` value of\nthe grid object.\n\n"
},
{
"name": "Annotation",
"description": "An annotation object contains all extracted and verified data related to a document. Every document belongs to a queue and is related to the schema object, that defines datapoint types and overall shape of the extracted data.\n\nCommonly you need to use the [upload](/api/upload) endpoint to create annotation instances.\n\n\n## Sideloading\nThe annotations API supports efficient data fetching through sideloading. Add the `sideload` query parameter to include\nrelated objects in the response. This parameter accepts comma-separated list of keywords. The response is then enriched\nby the requested keys, which contain lists of the sideloaded objects.\n\n```\nGET /annotations?sideload=content,relations,assignees,labels\n```\n\n**Available sideload options**:\n- `assignees` - Users assigned to the annotation\n- `automation_blockers` - Automation blockers associated with the annotation\n- `confirmed_bys` - Users who confirmed the annotation\n- `content` - Annotation data (datapoints). **Required**: Must filter by `content.schema_id=`\n- `creators` - Users who created the annotation\n- `deleted_bys` - Users who deleted the annotation\n- `documents` - Document details\n- `emails` - Email objects\n- `exported_bys` - Users who exported the annotation\n- `labels` - Applied labels\n- `modifiers` - Users who last modified the annotation\n- `organizations` - Organization objects\n- `pages` - Page objects\n- `purged_bys` - Users who purged the annotation\n- `queues` - Queue objects\n- `rejected_bys` - Users who rejected the annotation\n- `related_emails` - Related email objects\n- `relations` - Related annotations (parent/child from splits)\n- `child_relations` - Child relations for split annotations\n- `schemas` - Schema objects\n- `suggested_edits` - Suggested edits for the annotation\n- `workflow_runs` - Workflow details\n- `workspaces` - Workspace objects\n\nSideloaded content can be filtered by `schema_id` to obtain only a subset of datapoints in content part of response,\nbut is a deprecated feature and will be removed in the future. Filter on content can be specified using query\nparameter `content.schema_id` that accepts comma-separated list of required schema_ids. \n \n**Example with filtering**:\n```\nGET /annotations?sideload=content&content.schema_id=123&status=to_review\n```\n\n## Query Field Filtering\nFilter annotations by specific field values using query parameters:\n\n```\nGET /annotations?queue=&status=to_review&modifier=\n```\n\n**Common filters**:\n- `queue` - Filter by queue URL\n- `status` - Filter by status (can specify multiple: `status=to_review,reviewing`)\n- `modifier` - Filter by user who last modified\n- `document__arrived_at_before` / `document__arrived_at_after` - Date range filtering\n- `ordering` - Sort results (e.g., `-created_at` for descending)\n\n## Key Relationships\n\n- **Document**: Every annotation is linked to exactly one document containing the original file and pages\n- **Queue**: Defines the workflow, schema, and processing rules for the annotation\n- **Schema**: Defines the structure and datapoint types for extracted data\n- **Content (DataPoints)**: The actual extracted and validated data values\n- **Relations**: Links to parent/child annotations (for split documents) or related annotations\n- **Assignees**: Users assigned to review the annotation\n- **Labels**: Tags for categorization and filtering\n"
},
{
"name": "Audit Log",
"description": "Audit log represents a log record of actions performed by users.\n\nOnly admin or organization group admins can access the log records.\nLogs do not include records about changes made by Rossum representatives via internal systems. The log retention policy is set to 1 year.\n\n\nTalk with a Rossum representative about enabling this feature.\n\n"
},
{
"name": "Automation Blocker",
"description": "Automation blocker stores reason why [annotation](/api/annotation) was not [automated](/guides/automation.)\n\nAutomation blocker types\n- `automation_disabled`\n - automation is disabled due to [queue](/api/queue) settings\n - `level: annotation` only\n - occurs when automation level on [queue](/api/queue) is set to `never` or `automation_enabled` [queue settings](/api/queue) is `false`\n- `is_duplicate`\n - annotation is a duplicate of another one (there exists a [relation](/api/relation) of `duplicate` type)\n and `automate_duplicate` [queue settings](/api/queue) is set to `false`\n - `level: annotation` only\n- `suggested_edit_present`\n - there is a [suggested edit](/api/suggested-edit) by the AI engine and `automate_suggested_edit` [queue settings](/api/queue) is set to `false`\n - `level: annotation` only\n- `low_score`\n - [AI confidence score](/guides/automation#ai-confidence-scores) is lower than `score_threshold` set for given [datapoint](/guides/document-schema#schema-content)\n - `level: datapoint` only\n- `failed_checks`\n - schema field constraint or connector validation failed\n - only for `level: datapoint`\n- `no_validation_sources`\n - validation source list was reset e.g. by hook, so automation was blocked\n - only for `level: datapoint`\n- `error_message`\n - for both `levels`, `annotation` and `datapoint`\n - `error` type messages received from connector\n- [Delete recommendation](/api/delete-recommendation) based on validation trigger match for the document\n - `delete_recommendation_filename`, `delete_recommendation_page_count`\n - `level: annotation` only\n - deletion was recommended based on filename/page count condition of the trigger\n - `delete_recommendation_field`\n - only for `level: datapoint`\n - deletion recommended based on a value of given field (defined in the condition of trigger)\n- `extension`\n - automation blocker created by an extension\n - for both levels - `annotation` and `datapoint`\n- `human_confirmation_required`\n - Annotation was randomly marked for human confirmation\n - `level: annotation`\n"
},
{
"name": "Connector",
"description": "A connector is an extension of Rossum that allows to validate and modify data\nduring validation and also export data to an external system. A connector\nobject is used to configure external or internal endpoint of such an extension\nservice. For more information see [Extensions](/guides/extensions.)\n"
},
{
"name": "Dedicated Engine",
"description": "A Dedicated Engine object holds specification and a current state of training setup for a Dedicated Engine.\n\n**Important Notes:**\n- Talk with a Rossum representative about enabling this feature\n- You can create new Dedicated Engine objects, but no Dedicated Engine will be trained unless Dedicated Engines are part of your contract.\n"
},
{
"name": "Delete Recommendation",
"description": "A Delete-recommendation is an object that binds together triggers that fire when a document meets a queue's\ncriteria for a deletion recommendation. Currently, only binding to a single trigger is supported.\nThe trigger bound to a Delete Recommendation must belong to the same queue.\n\n\nOnly administrators are allowed to view or manipulate delete-recommendation objects.\n\n"
},
{
"name": "Document Relation",
"description": "A document relation object introduces additional relations between annotations and documents. An annotation\ncan be related to one or more documents and it may belong to several such relations of different types at the\nsame time. These are additional to the main relation between the annotation and the document from which it was\ncreated, see [annotation](/api/annotation.)\n"
},
{
"name": "Document",
"description": "A document object contains information about one input file. To create it, one can:\n * Use upload endpoint\n * import document by email\n * create document via API\n"
},
{
"name": "Documents Download",
"description": "Set of endpoints enabling download of multiple [documents](/api/document) at once. The workflow of such action is as follows:\n\n* Create a download object via POST on /documents/downloads. The response of the call will contain a [task](/api/task) URL.\n* Call GET on the task URL. Watch the task `status` to see when the task is ready. `result_url` of a successful task will contain URL to the download object.\n* Either call GET on the download object to get metadata about the object or call GET on the download object's [content](/api/documents-download#retrieve-download-content) endpoint to download the archive directly.\n\nA download object contains information about a downloadable archive in a `.zip` format.\n"
},
{
"name": "Email Template",
"description": "An email template object represents templates one can choose from when sending an email from Rossum.\n\n### Email Template Types\n\n- `rejection` - Template for a rejection email (can be manually created and deleted)\n- `rejection_default` - Default template for a rejection email\n- `email_with_no_processable_attachments` - Template for a reply to an email with no attachments\n- `custom` - Custom email template (can be manually created and deleted)\n\nEvery newly created queue triggers a creation of five default email templates with default messages and subjects.\n\n### Email templates\n\nEmail templates support variable expansion for dynamic content rendering using double curly brackets: `{{ variable }}`.\n\nPlease note that only simple variables are supported. Filters and the . lookup are not. A template such as:\n\n```\n{% if subject %}\nThe subject is {{ subject }}.\n{% endif %}\nThe message is {{ message }}.\n```\n\nwith template settings such as:\n\n```\n{'subject': 'Hello', 'message': 'World'}\n```\n\nwill render as:\n\n```\n{% if subject %}\nThe subject is Hello.\n{% endif %}\nThe message is World.\n```\n"
},
{
"name": "Email Thread",
"description": "An email thread object represents thread of related objects in Rossum's inbox.\n"
},
{
"name": "Email",
"description": "An email object represents emails sent to Rossum inboxes.\n"
},
{
"name": "Engine Field",
"description": "Engine field objects define the data fields that an engine can extract from documents. Each field has a specific type (string, number, date, enum) and optional subtype for more precise data validation and formatting. Fields can be configured for tabular data extraction and support pre-trained field types for common document elements.\n"
},
{
"name": "Engine",
"description": "Engine objects are AI models used for data extraction and document splitting. There are two types of engines:\n- `extractor`: Engine used for data extraction from documents\n- `splitter`: Engine used for splitting of documents\n"
},
{
"name": "Generic Engine Schema",
"description": "\nPlease note that Generic Engine Schema is an internal API and can be changed without notice.\n\n\nAn engine schema is an object which describes what fields are available in the engine. Do not confuse engine schema with [Schema](/guides/queue-schema.)\n"
},
{
"name": "Generic Engine",
"description": "A Generic Engine object holds a specification of training setup for Rossum trained Engine. It contains metadata and a link to the related generic engine schema used for extraction.\n\nWarning: Generic Engine is an internal API object and can be changed without notice.\n"
},
{
"name": "Hook Run",
"description": "A hook run is a record of hook execution (log). For easy and efficient development process of the extensions, the backend logs requests, responses (if enabled) and additional information, when the hook is being called.\n\nThe retention policy for the logs is set to 7 days.\n"
},
{
"name": "Hook Template",
"description": "Hook template is a definition of hook in Rossum extension store.\n\n### Hook template variables\nYou can use variable substitution in Hook Templates. To use it, surround an available variable like\nso `{{magic_variable}}` anywhere in the request body. If the variable is available, it will be replaced.\nIf the variable is not available, response will return `500`.\n\nCurrently available Hook Template variables:\n\n| Variable |\n|-----------------------|\n| api_url |\n| webhook_base_domain |\n| webhook_domain_prefix |\n"
},
{
"name": "Hook",
"description": "A hook is an extension of Rossum that is notified when specific event occurs.\nA hook object is used to configure what endpoint or function is executed and\nwhen. For an overview of other extension options see [Extensions](/guides/extensions.)\n"
},
{
"name": "Inbox",
"description": "An inbox object enables email ingestion to a related [queue](/api/queue.) We enforce `email` domain to match Rossum domain (e.g. example.rossum.app). `email_prefix` may be used to construct unique email address.\n\nPlease note that due to security reasons, emails from Rossum do not contain processed files. This feature can be enabled upon request by customer support.\n\nThe `filters` attribute allows filtering of incoming emails and documents:\n- `allowed_senders` and `denied_senders` settings allow filtering based on sender email address using wildcards (`*` matches everything, `?` matches any single character)\n- `document_rejection_conditions` defines rules for filtering incoming documents via email. See [document rejection conditions object](/api/hook-template#list-hook-templates)\n\nSeveral bounce-related attributes are deprecated and their configuration has moved to Email notifications settings.\n"
},
{
"name": "Label",
"description": "Label object represents arbitrary labels added to [annotation](/api/annotation) objects.\n"
},
{
"name": "Membership",
"description": "Membership represents a relation between user, organization (besides its primary organization) and queues.\nIt provides a way how users can work with multiple organizations within the same organization group. Using\nmemberships one can query the resources from a different organization the same way how one would do in\ntheir own organization. To do so, a membership shall be [created](/api/membership#create-membership) \nfirst, then a membership token shall be [generated](/api/organization#generate-organization-token). Such token then\ncan be used in any subsequent calls made to the target organization.\n\n\nDirect access to the API requires you to login using Rossum\ncredentials. User must have `organization_group_admin` role (this user role is available only on demand since it is a priced add-on).\n\n"
},
{
"name": "Organization Group",
"description": "Organization group object represents coupling among organizations.\n"
},
{
"name": "Organization",
"description": "Organization is a basic unit that contains all objects that are required to fully use Rossum platform.\n"
},
{
"name": "Page",
"description": "A page object contains information about one page of the annotation (we render\npages separately for every annotation, but this will change in the future).\n\nPage objects are created automatically during document import and cannot be\ncreated through the API, you need to use the [upload](/api/upload#create-upload)\nendpoint. Pages cannot be deleted directly -- they are deleted on parent annotation delete.\n"
},
{
"name": "Queue",
"description": "A queue object represents a basic organization unit of annotations. Annotations are imported to a queue either through a REST API [upload endpoint](/api/upload#create-upload) or by sending an email to a related [inbox](/api/inbox.) Export is also performed on a queue using [export](/api/queue#export-annotations) endpoint.\n\nQueue also specifies a [schema](/api/schema) for annotations and a [connector](/api/connector.)\n\nAnnotators and viewers only see queues they are assigned to.\n"
},
{
"name": "Relation",
"description": "A relation object introduces common relations between annotations. An annotation could be related to one or more other annotations and\nit may belong to several relations at the same time.\n\n#### Relation types:\n\n- `edit` relation is created after editing annotation in user interface (rotation or split of the document). The original annotation is set to `parent` attribute and newly created\nannotations are set to `annotations` attribute. To find all siblings of edited annotation see [filters on annotation](/api/annotation#list-annotations)\n- `attachment` is a relationship representing the state that one or more documents are attachments to another document. `key` is null in this case. Feature must be enabled.\n- `duplicate` relation is created after importing the same document that already exists in Rossum for current organization.\nIf `duplicate` relation already exists then corresponding annotation is added to existing relation.\n`key` of `duplicate` relation is set to hash of document content.\nTo find all duplicates of the annotation filter annotations with appropriate hash in relation `key`. See [filters on annotation](/api/annotation#list-annotations)\n\n\nThis resource supports `ETag` HTTP header handling. Use `If-None-Match` for conditional retrieval and `If-Match` for conditional updates and deletes.\n\n"
},
{
"name": "Rule",
"description": "Rule object represents arbitrary business rules added to [schema](/api/schema) objects.\n\n\nTalk with a Rossum representative about enabling this feature.\n\n\n### Trigger condition\nThe `trigger_condition` is a TxScript formula which controls the execution of the list of actions in a rule object.\n\nThere are two possible evaluation modes for this condition:\n* simple mode: when the condition does not reference any datapoint, or only reference header fields. Example: `len(field.document_id) < 10`.\n* line-item mode: when the condition references a line item datapoint (a column of a multivalue table). Example: `field.item_amount > 100.0`.\n\nIn line item mode, the condition is evaluated **once for each row of the table**, which means multiple actions can potentially be executed. In this case, a deduplication mechanism prevents the creation of duplicate messages (`show_message` action), duplicate blockers (`add_automation_blocker` action), and identical emails from being sent (`send_email` action).\n\n\nTrigger condition must evaluate strictly to `\"True\"`, truthy values are not enough to trigger the execution of actions. Wrap your condition with `bool(your_condition)` if necessary.\n\n\n### Rule actions\n\nObject defines rule actions to be executed when trigger condition is met.\n\n| Attribute | Type | Read-only | Description |\n|-----------|--------|-----------|--------------------------------------------------------------------------------------------------------|\n| id | string | no | Rule action ID. Needs to be unique within the Rule's `actions`. |\n| enabled | bool | no | If false the action is disabled (default: `true`). |\n| type | string | no | See the following for the list of possible actions. |\n| payload | object | no | See the following for the payload structure for each action. |\n| event | object | no | Actions are configured to be executed on a specific event, see [trigger events](/api/trigger.) |\n\nNote that just after document import, the initial validation is performed and rules are then executed: \nthe trigger conditions are first evaluated on the latest anntoation content, and then actions registered on `validation` \nand `annotation_imported` events are both executed. \n\n\n#### Action Show message\n\nAction: `show_message`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|------------------|------------------------------------------------------------------|\n| type | string | One of: `error`, `warning`, `info`. |\n| content | string | Message content to be displayed. |\n| schema_id | Optional[string] | Optional message target field (omit for document scope message). |\n\n#### Action Add automation blocker\n\nAction: `add_automation_blocker`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|------------------|-------------------------------------------------------------------------------------------|\n| content | string | Automation blocker content to be displayed. |\n| schema_id | Optional[string] | Optional automation blocker target field id (omit for document scope automation blocker). |\n\nNote: at most one action of type `add_automation_blocker` can be set up for one [rule](/api/rule) object.\n\n#### Action change status\n\nAction: `change_status`\n\nEvent: can be triggered on `annotation_imported` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|--------|--------------------------------------------------------------------------|\n| method | string | Possible options: `postpone`, `export`, `delete`, `confirm`, `reject`. |\n\nNote: at most one action of type `change_status` can be set up for one [rule](/api/rule) object.\n\n#### Action Change queue\n\nThis action moves the annotation to another queue with or without re-extraction of the data (see the `reimport` flag). \n\nAction: `change_queue`\n\nEvent: Can be configured to trigger on `annotation_imported`, `annotation_confirmed` or `annotation_exported`.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|----------------|-------------------------------------------------------------------------------------------|\n| reimport | Optional[bool] | Flag that controls whether the annotation will be reimported during the action execution. |\n| queue_id | integer | ID of the target queue. |\n\nNote: at most one action of type `change_queue` can be set up for one [rule](/api/rule) object.\n\n#### Action Add label\n\nAction: `add_label`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|-----------|-----------------------------------------------------------------------------------------|\n| labels | list[url] | URLs of [label](/api/label) object to be linked to the processed [annotation](/api/annotation.) |\n\nNote: at most one action of type `add_label` can be set up for one [rule](/api/rule) object.\n\n#### Action Remove label\n\nAction: `remove_label`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|-----------|---------------------------------------------------------------------------------------------|\n| labels | list[url] | URLs of [label](/api/label) object to be unlinked from the processed [annotation](/api/annotation.) |\n\nNote: at most one action of type `remove_label` can be set up for one [rule](/api/rule) object.\n\n#### Action Add / Remove label\n\nAction: `add_remove_label`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|-----------|-----------------------------------------------------------------------------------------|\n| labels | list[url] | URLs of [label](/api/label) object to be linked to the processed [annotation](/api/annotation.) |\n\nThe affected labels are added to the annotation when the condition is satisfied, and removed otherwise.\n\nNote: at most one action of type `add_remove_label` can be set up for one [rule](/api/rule) object.\n\n#### Action Show / hide field\n\nAction: `show_hide_field`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|------------|---------------|-----------------------------------------------------------------------------------------------------------------|\n| schema_ids | List[string] | Set `hidden` attribute of schema fields according to condition. (Please see [schema content](/api/schema.) |\n\nThe affected schema field is visible when the condition is satisfied, and is hidden otherwise. \n\n#### Action Show field\n\nAction: `show_field`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|------------|---------------|-----------------------------------------------------------------------------------------------------|\n| schema_ids | List[string] | Set `hidden` attribute of schema fields to `False`. (Please see [schema content](/api/schema.) |\n\nNote: at most one action of type `show_field` can be set up for one [rule](/api/rule) object.\n\n#### Action Hide field\n\nAction: `hide_field`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|------------|---------------|----------------------------------------------------------------------------------------------------|\n| schema_ids | List[string] | Set `hidden` attribute of schema fields to `True`. (Please see [schema content](/api/schema.) |\n\nNote: at most one action of type `hide_field` can be set up for one [rule](/api/rule) object.\n\n#### Action Add validation source\n\nAdds `rules` validation source to a datapoint.\n\nAction: `add_validation_source`\n\nEvent: can be triggered on `validation` event only.\n\nPayload:\n\n| Attribute | Type | Description |\n|-----------|---------|------------------------------------------------------------------------------------------------------------|\n| schema_id | string | Schema ID of the datapoint to add the validation source to (Please see [schema content](/api/schema.) |\n\nNote: at most one action of type `add_validation_source` can be set up for one [rule](/api/rule) object.\n\n#### Action send email\n\nIn line item mode of execution, deduplication mechanism will prevent multiple identical emails from being sent, and at most **five** emails can be sent by a single action. \n\nAction: `send_email`\n\nEvent: Can be configured to trigger on `annotation_imported`, `annotation_confirmed` or `annotation_exported`.\n\nPayload:\n\nIf `email_template` is defined, the rest of the attributes are ignored. \n\n| Attribute | Type | Description | Required |\n|-----------------|---------|----------------------------------------------------------------------------------------------------------------------|----------|\n| email_template | string | Email template URL. | Yes |\n| attach_document | boolean | When true document linked to the annotation will be sent together with the email as an attachment (default `False`). | No |\n\nIf `email_template` is not defined, then the payload can contain the following attributes:\n\n| Attribute | Type | Description | Required |\n|-----------|--------------|-----------------------|----------|\n| to | List[string] | List of recipients. | Yes |\n| subject | string | Subject of the email. | Yes |\n| body | string | Body of the email. | Yes |\n| cc | List[string] | List of cc. | No |\n| bcc | List[string] | List of bcc. | No |\n\n#### Action Exclude from training\n\nThis action sets `training_enabled` to `false` on the annotation, excluding it from being used for AI training.\n\nAction: `exclude_from_training`\n\nEvent: Can be configured to trigger on `annotation_confirmed` or `annotation_exported`.\n\nPayload: none.\n\nNote: at most one action of type `exclude_from_training` can be set up for one [rule](/api/rule) object.\n\n"
},
{
"name": "Rules Execution Log",
"description": "A rules execution log is a record of rule execution. When a rule is triggered and evaluated, the backend logs the trigger event, condition evaluation results, and executed actions.\n\nThis endpoint provides visibility into rule execution history for debugging and monitoring purposes.\n\nThe retention policy for the logs is set to 7 days.\n"
},
{
"name": "Schema",
"description": "A schema object specifies the set of datapoints that are extracted from the\nannotation. For more information see [Schema](/guides/queue-schema.)\n\nSchema content consists of a list of section objects. Each section represents a logical part of the document,\nsuch as amounts or vendor info. Schema allows multiple sections, and there should be at least one section in the schema.\n\nRossum schema supports data fields with single values (datapoint), fields with multiple values (multivalue)\nor tuples of fields (tuple). At the topmost level, each schema consists of sections, which may either directly\ncontain actual data fields (datapoints) or use nested multivalues and tuples as containers for single datapoints.\n\nThe supported shapes are:\n- simple: atomic datapoints of type number, string, date or enum\n- list: simple datapoint within a multivalue\n- tabular: simple datapoint within a \"multivalue tuple\" (a multivalue list containing a tuple for every row)\n\nAll schema objects use discriminators based on the 'category' field for proper type identification.\n\n\nThis resource supports `ETag` HTTP header handling. Use `If-None-Match` for conditional retrieval and `If-Match` for conditional updates and deletes.\n\n"
},
{
"name": "Suggested Edit",
"description": "A suggested edit object contains splittings of incoming document suggested by the AI engine.\n\nSuggested edit objects are created automatically during document import.\n"
},
{
"name": "Task",
"description": "Tasks are used as status monitors of asynchronous operations.\n\nTasks with `succeeded` status can redirect to the object created as a result of them. If `no_redirect=true` is passed as a query parameter, endpoint won't redirect to an object created, but will return information about the task itself instead.\n\n## Task Types\n\nCurrently supported task types:\n- `documents_download` - Used for monitoring document download operations.\n- `upload_created` - Used for monitoring upload creation operations.\n- `email_imported` - Used for monitoring email import operations.\n\n## Task Content\n\nThe `content` field contains detailed information related to tasks, which varies by task type:\n\n### Documents Download Task Content\n\n- `file_name` (string) - File name of the archive to be downloaded specified when creating a download.\n\n### Documents Upload Task Content\n\n- `upload` (url) - URL of the object representing the upload.\n"
},
{
"name": "Trigger",
"description": "A Trigger object represents a condition that will trigger its related object's actions when an event occurs.\n\n\nA Trigger with trigger event type of `email_with_no_processable_attachments` can be only retrieved. It can not be created, updated nor deleted.\n\n"
},
{
"name": "Upload",
"description": "Object representing an upload. An upload contains information about documents uploaded to a queue, including the creator, creation time, and associated documents and annotations.\n\nCreate upload endpoints also support *basic authentication* to enable easy integration with third-party systems.\n"
},
{
"name": "User Role",
"description": "User role is a group of permissions that are assigned to the user. Permissions are assigned to individual operations on objects.\n\nThere are multiple pre-defined roles:\n\n| Role | Description |\n|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| viewer | Read-only user, cannot change any API object. May be useful for automated data export or auditor access. |\n| annotator | In addition to permissions of annotator_limited the user is also allowed to [import a document](/api/document#documents_import). |\n| admin | User can modify API objects to set-up organization (e.g. [workspaces](/api/workspace,) [queues](/api/queue,) [schemas](/api/schema) |\n| manager | In addition to permissions of annotator the user is also allowed to access [usage-reports](/guides/usage-report.) |\n| annotator_limited | User that is allowed to change annotation and its datapoints. Note: this role is under active development and should not be used in production environment. |\n| annotator_embedded | This role is specifically designed to be used with [embedded mode](/guides/embedded-mode.) User can modify annotation and its datapoints, also has read-only permissions for objects needed for interaction on embedded validation screen. |\n| organization_group_admin | In addition to permissions of admin the user can manage [memberships](/api/membership) among [organizations](/api/organization) within her [organization group](/api/organization-group.) **Talk with a Rossum representative about enabling this feature.** |\n| approver | In addition to permission of viewer the user can also approve/reject annotations. This may be combined with other roles. **Talk with a Rossum representative about enabling this feature.** For more info see [workflows](/guides/workflow-guide.) |\n\n\nPlease note that id may be different between organizations, use names to identify groups properly.\n\n\nUser can only access annotations from queues it is assigned to, except for `admin` and `organization_group_admin` roles that can access any queue.\n\nPermissions assigned to the role cannot be changed through the API.\n"
},
{
"name": "User",
"description": "A user object represents individual user of Rossum. Every user is assigned to an organization.\n\nA user can be assigned [user roles](/api/user-role) (permission groups). User usually has only one assigned role (with the exception of *approver* role).\n\nUser may be assigned to one or more queues and can only access annotations\nfrom the assigned queues. This restriction is not applied to admin users, who may\naccess annotations from all queues.\n\nUsers cannot be deleted, but can be disabled (set `is_active` to `false`).\nField `email` cannot be changed through the API (due to security reasons).\nField `password` can be set on [user creation](/api/user#create-user) but cannot be changed through the API (due to security reasons).\nField `oidc_id` will be set to User's email when transitioning to `sso` authorization, if empty.\n"
},
{
"name": "Workflow Activity",
"description": "Workflow activity objects represent actions and events that occur during the execution of workflows. They track the progression of documents through workflow steps, including when steps are started, completed, approved, rejected, or when users are reassigned.\n"
},
{
"name": "Workflow Run",
"description": "A workflow run object represents the execution of a workflow for a specific annotation. It tracks the current step and status of the workflow process.\n"
},
{
"name": "Workflow Step",
"description": "A workflow step object defines individual steps within a [workflow](/api/workflow) that control the approval process for annotations. Each step has a specific type, mode, and condition that determines how the workflow progresses.\n\nCurrently, the only supported step type is `approval`, which requires designated assignees to approve annotations before they can proceed in the workflow.\n"
},
{
"name": "Workflow",
"description": "A workflow object represents an approval workflow for an organization. Workflows define conditions that determine when they will be entered during document processing.\n\n\nTalk with a Rossum representative about enabling this feature. Read more about workflows [here](/guides/workflow-guide)\n\n"
},
{
"name": "Workspace",
"description": "A workspace object is a container of [queue](/api/queue) objects.\n"
}
],
"paths": {
"/api/v1/annotations": {
"post": {
"summary": "Create annotation",
"description": "Create an annotation object.\n\nNormally you create annotations via the [upload](/api/upload#create-upload) endpoint.\n\nThis endpoint could be used for creating annotation instances including their content and with `status` set to an\nexplicitly requested value. Currently only `created` is supported which is not touched by the rest of the platform\nand is not visible via the Rossum UI. This allows for subsequent updates before switching the status to `importing`\nso that it is passed through the rest of the upload pipeline.\n\nThe use-case for this is the `upload.created` [hook event](/guides/extensions#webhook-extension) where new\nannotations could be created and the platform runtime then switches all such annotations' status to `importing`.\n",
"operationId": "annotations_create",
"tags": [
"Annotation"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"document",
"queue"
],
"properties": {
"status": {
"type": "string",
"enum": [
"created"
],
"description": "Requested annotation status. Only `created` is currently supported."
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "Document [document](/api/document)."
}
],
"example": "https://example.rossum.app/api/v1/documents/314628"
},
"queue": {
"type": "string",
"format": "uri",
"description": "Target [queue](/api/queue.)",
"example": "https://example.rossum.app/api/v1/queues/8199"
},
"content_data": {
"type": "array",
"items": {
"type": "object"
},
"description": "Array of [annotation content](/api/annotation-content) objects.",
"example": [
{
"category": "datapoint",
"schema_id": "doc_id",
"content": {
"value": "122"
},
"validation_sources": []
}
]
},
"values": {
"type": "object",
"description": "Values object as described in the [upload](/api/upload#create-upload) endpoint."
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"training_enabled": {
"type": "boolean",
"description": "Flag signalling whether the annotation should be used in the training of the instant learning component.",
"default": true
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List annotations",
"description": "Retrieve all annotation objects.",
"operationId": "annotations_list",
"tags": [
"Annotation"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/status"
},
{
"$ref": "#/components/parameters/modifier"
},
{
"$ref": "#/components/parameters/confirmed_by"
},
{
"$ref": "#/components/parameters/deleted_by"
},
{
"$ref": "#/components/parameters/exported_by"
},
{
"$ref": "#/components/parameters/purged_by"
},
{
"$ref": "#/components/parameters/rejected_by"
},
{
"$ref": "#/components/parameters/assignees"
},
{
"$ref": "#/components/parameters/labels"
},
{
"$ref": "#/components/parameters/document"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/queue__workspace"
},
{
"$ref": "#/components/parameters/relations__parent"
},
{
"$ref": "#/components/parameters/relations__type"
},
{
"$ref": "#/components/parameters/relations__key"
},
{
"$ref": "#/components/parameters/arrived_at_before"
},
{
"$ref": "#/components/parameters/arrived_at_after"
},
{
"$ref": "#/components/parameters/assigned_at_before"
},
{
"$ref": "#/components/parameters/assigned_at_after"
},
{
"$ref": "#/components/parameters/confirmed_at_before"
},
{
"$ref": "#/components/parameters/confirmed_at_after"
},
{
"$ref": "#/components/parameters/modified_at_before"
},
{
"$ref": "#/components/parameters/modified_at_after"
},
{
"$ref": "#/components/parameters/deleted_at_before"
},
{
"$ref": "#/components/parameters/deleted_at_after"
},
{
"$ref": "#/components/parameters/exported_at_before"
},
{
"$ref": "#/components/parameters/exported_at_after"
},
{
"$ref": "#/components/parameters/export_failed_at_before"
},
{
"$ref": "#/components/parameters/export_failed_at_after"
},
{
"$ref": "#/components/parameters/purged_at_before"
},
{
"$ref": "#/components/parameters/purged_at_after"
},
{
"$ref": "#/components/parameters/rejected_at_before"
},
{
"$ref": "#/components/parameters/rejected_at_after"
},
{
"$ref": "#/components/parameters/restricted_access"
},
{
"$ref": "#/components/parameters/automated"
},
{
"$ref": "#/components/parameters/has_email_thread_with_replies"
},
{
"$ref": "#/components/parameters/has_email_thread_with_new_replies"
},
{
"$ref": "#/components/parameters/search"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"document",
"-document",
"document__arrived_at",
"-document__arrived_at",
"document__original_file_name",
"-document__original_file_name",
"modifier",
"-modifier",
"modifier__username",
"-modifier__username",
"modified_by",
"-modified_by",
"modified_by__username",
"-modified_by__username",
"creator",
"-creator",
"creator__username",
"-creator__username",
"queue",
"-queue",
"status",
"-status",
"created_at",
"-created_at",
"assigned_at",
"-assigned_at",
"confirmed_at",
"-confirmed_at",
"modified_at",
"-modified_at",
"exported_at",
"-exported_at",
"export_failed_at",
"-export_failed_at",
"purged_at",
"-purged_at",
"rejected_at",
"-rejected_at",
"deleted_at",
"-deleted_at",
"confirmed_by",
"-confirmed_by",
"deleted_by",
"-deleted_by",
"exported_by",
"-exported_by",
"purged_by",
"-purged_by",
"rejected_by",
"-rejected_by",
"confirmed_by__username",
"-confirmed_by__username",
"deleted_by__username",
"-deleted_by__username",
"exported_by__username",
"-exported_by__username",
"purged_by__username",
"-purged_by__username",
"rejected_by__username",
"-rejected_by__username"
]
}
},
{
"$ref": "#/components/parameters/fields"
},
{
"$ref": "#/components/parameters/fields_exclude"
},
{
"$ref": "#/components/parameters/sideload"
},
{
"$ref": "#/components/parameters/content_schema_id"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/annotation"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"get": {
"summary": "Retrieve annotation",
"description": "Get an annotation object.",
"operationId": "annotations_retrieve",
"tags": [
"Annotation"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update annotation",
"description": "Update annotation object.",
"operationId": "annotations_update",
"tags": [
"Annotation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation",
"required": [
"document",
"queue"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update annotation",
"description": "Update part of annotation object.\n\n\nOne can be tempted by patching the status of the annotation to the `confirmed` or `exported`\nstate. However, patching status skips key annotation metadata updates which negatively affects the Dedicated AI\nEngine training. Use the [confirm](/api/annotation#confirm-validation) endpoint for switching annotation\nto the `confirmed` or `exported` state.\n\n\n\nPlease be aware that annotation status cannot be manually set to `purged`. Use the\n[purge deleted](/api/annotation#purge-deleted-annotations) endpoint. Also note, that once annotation\nhas `purged` status, it cannot be changed anymore.\n\n",
"operationId": "annotations_partial_update",
"tags": [
"Annotation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/approve": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Approve annotation",
"description": "Approve annotation, switch its status to `exporting` or `confirmed`, or it stays in `in_workflow`, depending on the evaluation of the current [workflow step](/api/workflow-step.)\n\n\nApproving is allowed only for documents in states: `in_workflow`. See [Annotation Lifecycle](/guides/annotation-lifecycle) for more information about states.\n\n\nOnly admin, organization group admin, or an assigned user with approver role can approve annotation in this state. A [workflow activity](/api/workflow-activity) record object will be created.\n\n\nTalk with a Rossum representative about enabling this feature. Read more about [workflows](/guides/workflow-guide.)\n\n",
"operationId": "annotations_approve",
"tags": [
"Annotation"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "New status of the annotation.",
"example": "confirmed"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/assign": {
"post": {
"summary": "Assign annotation",
"description": "Change `assignees` of the annotation.\n\n\n`admin` and `organization_group_admin` user roles can assign to arbitrary set of users. The rest of the roles can only swap themselves for a different user (without changing the others).\n\n",
"operationId": "annotations_assign",
"tags": [
"Annotation"
],
"x-beta": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"annotations",
"assignees"
],
"properties": {
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of annotations to change the assignees of (currently we support only one annotation at a time).",
"example": [
"https://example.rossum.app/api/v1/annotations/319668"
]
},
"assignees": {
"$ref": "#/components/schemas/assignees_writable",
"description": "List of users to be added as annotation assignees."
},
"note_content": {
"type": "string",
"description": "Content of the note that will be added to the workflow activity of action `reassign` (only applicable for annotation in `in_workflow` state).",
"default": ""
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/edit_pages/cancel": {
"post": {
"summary": "Cancel edit pages session",
"operationId": "annotations_edit_pages_cancel",
"tags": [
"Annotation"
],
"description": "Cancels an edit pages session, stopping review on specified child annotations and optionally the parent.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotations": {
"type": "array",
"description": "Child annotations to cancel (stop reviewing). Must be in the `reviewing` state.",
"items": {
"type": "string",
"format": "uri",
"example": "https://example.rossum.app/api/v1/annotations/67890"
}
},
"cancel_parent": {
"type": "boolean",
"default": true,
"description": "Whether to also cancel the parent annotation",
"example": true
}
}
}
}
}
},
"responses": {
"204": {
"description": "Edit pages session cancelled successfully"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/cancel": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Cancel validation",
"description": "Cancel annotation, switch its status back to `to_review` or `postponed`.\n\n\nAnnotation with the status `exporting` or `exported` cannot be cancelled. To send an exported annotation\nback to any previous status, update the annotation status appropriately instead or enable the confirmed state\nfor the particular [queue](/api/queue) in your workflow instead.\n\n",
"operationId": "annotations_cancel",
"tags": [
"Annotation"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/delete": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Switch to deleted",
"description": "Switch annotation status to `deleted`. Annotation with status `deleted` is still available in Rossum UI.\n",
"operationId": "annotations_delete_status",
"tags": [
"Annotation"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/confirm": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Confirm validation",
"description": "Confirm annotation, switch status to `exported` (or `exporting`). If the `confirmed` state is enabled,\nthis call moves the annotation to the `confirmed` status.\n\n\nThe confirm call is the right choice when confirming correctly captured data and switching the annotations\nto `confirmed` or `exported` state. One can be tempted by patching the status of the annotation to the `confirmed`\nor `exported` state. However, patching status skips key annotation metadata updates which negatively affects\nthe [Dedicated AI Engine](https://knowledge-base.rossum.ai/docs/ai-engines) training.\n\n",
"operationId": "annotations_confirm",
"tags": [
"Annotation"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"skip_workflows": {
"type": "boolean",
"default": false,
"description": "Whether to skip workflows evaluation. Read more about workflows [here](/guides/workflow-guide)\n\nThe `bypass_workflows_allowed` must be set to `true` in workflows queue settings in order to use this feature.\n"
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/copy": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Copy annotation",
"description": "Make a copy of annotation in another queue. All data and metadata are copied.\n\nIf you want to directly reimport the copied annotation, you can use `reimport=true` query parameter (such annotation will be billed).\n",
"operationId": "annotations_copy",
"tags": [
"Annotation"
],
"parameters": [
{
"name": "reimport",
"in": "query",
"description": "Whether to reimport the copied annotation.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"target_queue"
],
"properties": {
"target_queue": {
"type": "string",
"format": "uri",
"description": "URL of [queue](/api/queue,) where the copy should be placed.",
"example": "https://example.rossum.app/api/v1/queues/8236"
},
"target_status": {
"type": "string",
"description": "The [status](/guides/annotation-lifecycle) of copied annotation (if not set, it stays the same).",
"example": "to_review"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"annotation"
],
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of the new annotation object.",
"example": "https://example.rossum.app/api/v1/annotations/320332"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/create_embedded_url": {
"post": {
"summary": "Create embedded URL",
"operationId": "annotations_create_embedded_url",
"tags": [
"Annotation"
],
"description": "Similar to [start embedded annotation](/api/annotation#start-validation-for-embedded-use) endpoint but can be\ncalled for annotations with all statuses and does not switch status.\n\nEmbedded annotation cannot be started by users with admin or organization group admin roles. We strongly recommend\ncreating embedded URLs by users with `annotator_embedded` [user role](/api/user-role) and permissions for the given\nqueue only to limit the scope of actions that user is able to perform to required minimum.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"return_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to after annotation is confirmed",
"example": "https://service.com/return"
},
"cancel_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is cancelled",
"example": "https://service.com/cancel"
},
"delete_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is deleted",
"example": "https://service.com/delete"
},
"postpone_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is postponed",
"example": "https://service.com/postpone"
},
"max_token_lifetime_s": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 583200,
"description": "Duration (in seconds) for which the token will be valid. The default is the [queue's](/api/queue) `session_timeout`).",
"example": 3600
}
}
}
}
}
},
"responses": {
"200": {
"description": "Embedded URL created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL to be used in the browser iframe/popup window. URL includes a token that is valid for this\ndocument only for a limited period of time.\n",
"example": "https://example.rossum.app/embedded/document/12345#authToken=db313f24f5738c8e04635e036ec8a45cdd6d6b03"
},
"status": {
"type": "string",
"description": "Status of annotation, see [annotation lifecycle](/guides/annotation-lifecycle.)",
"example": "to_review"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/edit": {
"post": {
"summary": "Edit annotation (legacy split)",
"operationId": "annotations_edit",
"tags": [
"Annotation"
],
"description": "Legacy endpoint for splitting annotations. Creates new annotations from the original annotation's pages.\n\n\nThis is a legacy endpoint. For new implementations, use the [split](/api/annotation#split-annotation)\nendpoint instead, which provides the same functionality with a clearer name.\n\n\nIf used on an annotation in a way that after the editing only one document remains, the original annotation will\nbe edited. If multiple documents are to be created after the call, status of the original annotation is switched\nto `split`, status of the newly created annotations is `importing` and the extraction phase begins over again.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"documents"
],
"properties": {
"documents": {
"type": "array",
"minItems": 1,
"description": "Array of documents to create",
"items": {
"type": "object",
"required": [
"pages"
],
"properties": {
"pages": {
"type": "array",
"minItems": 1,
"description": "Pages to include in this document",
"items": {
"$ref": "#/components/schemas/edit_page"
}
},
"metadata": {
"$ref": "#/components/schemas/edit_metadata"
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Annotation edited successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/edit_pages_result"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/edit_pages": {
"post": {
"summary": "Edit pages (split and reorganize)",
"operationId": "annotations_edit_pages",
"tags": [
"Annotation"
],
"description": "Edit document pages, split and re-split already split document.\n\nWhen using this endpoint, status of the original annotation (when not editing existing split) is switched to `split`,\nstatus of the newly created annotations is `importing` and the extraction phase begins over again.\n\nThis endpoint can be used for splitting annotations also from webhook listening to `annotation_content.initialize`\nevent and action.\n\n**Operations**:\n- **edit**: Create new annotations from parent pages with optional rotation and values\n- **move**: Move existing child annotations to different queues\n- **delete**: Delete child annotations\n- **stop_reviewing**: Stop review on child annotations without deleting\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"edit": {
"type": "array",
"description": "Create new annotations from parent pages",
"items": {
"type": "object",
"properties": {
"parent_pages": {
"type": "array",
"description": "List of parent pages with rotation.",
"items": {
"$ref": "#/components/schemas/edit_page"
}
},
"target_queue": {
"type": "string",
"format": "uri",
"description": "Target queue URL. When not provided, the new annotation is imported into the same queue as the parent annotation.",
"example": "https://example.rossum.app/api/v1/queues/111"
},
"metadata": {
"$ref": "#/components/schemas/edit_metadata"
},
"values": {
"type": "object",
"description": "Values to be propagated to newly created annotations. Keys must be prefixed with \"edit:\",\ne.g. `\"edit:document_type\"`.\n",
"additionalProperties": true
},
"document_name": {
"type": "string",
"description": "Name for the newly created document. When not provided, generated automatically.",
"example": "my_document.pdf"
},
"annotation": {
"type": "string",
"format": "uri",
"description": "Annotation URL",
"example": "https://example.rossum.app/api/v1/annotations/42"
}
}
}
},
"move": {
"type": "array",
"description": "Move child annotations to different queues",
"items": {
"type": "object",
"required": [
"annotation",
"target_queue"
],
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "Child annotation to move",
"example": "https://example.rossum.app/api/v1/annotations/67890"
},
"target_queue": {
"type": "string",
"format": "uri",
"description": "Target queue URL",
"example": "https://example.rossum.app/api/v1/queues/111"
}
}
}
},
"delete": {
"type": "array",
"description": "Child annotations to delete",
"items": {
"type": "string",
"format": "uri",
"example": "https://example.rossum.app/api/v1/annotations/67890"
}
},
"stop_reviewing": {
"type": "array",
"description": "Child annotations to stop reviewing. Must be in `reviewing` state.",
"items": {
"type": "string",
"format": "uri",
"example": "https://example.rossum.app/api/v1/annotations/67891"
}
},
"stop_parent": {
"type": "boolean",
"default": true,
"description": "Whether to stop reviewing the parent annotation",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Edit pages operation completed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/edit_pages_result"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/edit_pages/in_place": {
"post": {
"summary": "Edit pages in place",
"operationId": "annotations_edit_pages_in_place",
"tags": [
"Annotation"
],
"description": "Edits pages of an annotation in place by reordering, rotating, or removing pages without creating new annotations.\n\nUnlike the `edit_pages` endpoint which creates new child annotations, this endpoint modifies the existing annotation directly.\n\nThis endpoint can be used for the embedded mode.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"parent_pages"
],
"properties": {
"parent_pages": {
"type": "array",
"minItems": 1,
"description": "List of parent pages with rotation.",
"items": {
"$ref": "#/components/schemas/edit_page"
}
},
"target_queue": {
"type": "string",
"format": "uri",
"description": "Target queue URL. When not provided, the annotation stays in its current queue.",
"example": "https://example.rossum.app/api/v1/queues/111"
},
"metadata": {
"$ref": "#/components/schemas/edit_metadata"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pages edited successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/edit_pages_result"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/purge_deleted": {
"post": {
"summary": "Purge deleted annotations",
"description": "Start the asynchronous process of purging customer's data related to selected annotations with `deleted` status. The following operations will happen:\n\n* delete [annotation content](/api/annotation-content)\n* delete [pages](/api/page)\n* remove content and file names of [documents](/api/document)\n* remove annotations from [relations](/api/relation) of type `duplicate`\n* preserve [annotations](/api/annotation) objects, move them to `purged` [status](#Annotation-Lifecycle)\n\nThis is an asynchronous endpoint, status of annotations is changed to `purged` and related objects are gradually being deleted.\n\nAt least one of `annotations`, `queue` fields must be filled in. The resulting set of annotations is the disjunction of `queue` and `annotations` filter.\n",
"operationId": "annotations_purge_deleted",
"tags": [
"Annotation"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of annotations to be purged.",
"example": [
"https://example.rossum.app/api/v1/annotations/12345"
]
},
"queue": {
"type": "string",
"format": "uri",
"description": "Queue of which the annotations should be purged.",
"example": "https://example.rossum.app/api/v1/queues/42"
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/reject": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Reject annotation",
"description": "Reject annotation, switch its status to `rejected`.\n\n\nRejection is allowed only for documents in states: `to_review`, `reviewing`, `postponed`, `in_workflow`.\nSee [Document Lifecycle](/guides/annotation-lifecycle) for more information about states.\n\n\n\n\nIf rejecting in `in_workflow` state, the `annotation.workflow_run.workflow_status` will also be set to `rejected`\nand a [workflow activity record](/api/workflow-activity) object will be created. Only admin, organization group\nadmin, or an assigned user can approve annotation in this state.\n\n\nTalk with a Rossum representative about enabling this feature. Read more about workflows [here](/guides/workflow-guide)\n\n",
"operationId": "annotations_reject",
"tags": [
"Annotation"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"note_content": {
"type": "string",
"description": "Rejection note.",
"default": ""
},
"automatically_rejected": {
"type": "boolean",
"description": "Designates whether annotation is displayed as automatically rejected in the statistics.",
"default": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "New status of the annotation (rejected).",
"example": "rejected"
},
"note": {
"type": "string",
"format": "uri",
"description": "Link to [Note](/api/note) object.",
"example": "https://example.rossum.app/api/v1/notes/3"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/bboxes": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
]
},
"/api/v1/annotations/{annotationID}/neighbors": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
]
},
"/api/v1/annotations/{annotationID}/time_spent": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
]
},
"/api/v1/annotations/{annotationID}/page_data": {
"get": {
"summary": "Retrieve page spatial data",
"operationId": "annotations_page_data_retrieve",
"tags": [
"Annotation"
],
"description": "Get text content for every page, including position coordinates, considering granularity options like lines, words,\ncharacters, or complete page text content.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "page_numbers",
"in": "query",
"required": false,
"description": "Comma-separated list of page numbers to retrieve. The default is the first 20 pages of the document. Max. 20 page\nnumbers, if there is more, they are silently ignored.\n",
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "granularity",
"in": "query",
"required": true,
"description": "Level of text granularity to return",
"schema": {
"type": "string",
"enum": [
"words",
"lines",
"chars",
"texts",
"barcodes"
],
"example": "words"
}
}
],
"responses": {
"200": {
"description": "Spatial data retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"description": "Array of page results",
"items": {
"type": "object",
"properties": {
"page_number": {
"type": "integer",
"description": "Page number",
"example": 1
},
"granularity": {
"type": "string",
"description": "Granularity level of the data",
"example": "words"
},
"items": {
"type": "array",
"description": "Text items with spatial data",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Extracted text content",
"example": "Invoice"
},
"position": {
"type": "array",
"description": "Coordinates of the item on the given page. In case of `texts` granularity, the result\nitems objects are missing `position` key, since the `text` value is the full page text.\n",
"items": {
"type": "integer"
},
"minItems": 4,
"maxItems": 4,
"example": [
100,
50,
150,
20
]
},
"type": {
"type": "string",
"description": "Type of barcode. This value is present only for granularity `barcodes`."
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/export": {
"get": {
"summary": "Export annotations (cross-queue, GET)",
"description": "Export annotations across multiple queues in XML, CSV, JSON or XLSX format.\nOutput format is negotiated by Accept header or `format` parameter. \nSupported formats are: `csv`, `xml`, `xlsx` and `json`.\nA hard limit of 500 annotations is imposed.\nAnnotations to export must be specified via the `id` query parameter (comma-separated annotation IDs).\n\nFor queue-based export, refer to the [queue export endpoint](/api/queue#export-annotations).\n",
"operationId": "annotations_export",
"tags": [
"Annotation"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (CSV)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/annotations/export?id=1,2,3,4&format=csv&page_size=100'\n"
}
],
"parameters": [
{
"name": "format",
"in": "query",
"description": "Output format.",
"required": false,
"schema": {
"type": "string",
"enum": [
"csv",
"xml",
"json",
"xlsx"
]
}
},
{
"name": "columns",
"in": "query",
"description": "Columns to include in CSV/XLSX output (comma-separated schema_ids and meta-columns).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "prepend_columns",
"in": "query",
"description": "Columns to prepend at the beginning of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "append_columns",
"in": "query",
"description": "Columns to append at the end of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "delimiter",
"in": "query",
"description": "One-character string used to separate fields in CSV.",
"required": false,
"schema": {
"type": "string",
"default": ","
}
},
{
"name": "quote_char",
"in": "query",
"description": "One-character string used to quote fields containing special characters in CSV.",
"required": false,
"schema": {
"type": "string",
"default": "\""
}
},
{
"name": "quoting",
"in": "query",
"description": "Controls when quotes should be generated in CSV.",
"required": false,
"schema": {
"type": "string",
"enum": [
"quote_minimal",
"quote_none",
"quote_all",
"quote_non_numeric"
]
}
},
{
"name": "escape_char",
"in": "query",
"description": "One-character string used by the writer to escape the delimiter in CSV.",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "status",
"in": "query",
"description": "Annotation status filter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "modifier",
"in": "query",
"description": "User id filter.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "arrived_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "arrived_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"$ref": "#/components/parameters/page_size"
},
{
"name": "search",
"in": "query",
"description": "Search filter (limited to 10,000 results).",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/csv": {
"schema": {
"type": "string"
}
},
"application/xml": {
"schema": {
"type": "string"
}
},
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"post": {
"summary": "Export annotations (cross-queue, POST)",
"description": "Export annotations across multiple queues in XML, CSV, JSON or XLSX format.\nSupported formats are: `csv`, `xml`, `xlsx` and `json`.\nA hard limit of 500 annotations is imposed.\nAnnotations to export should be provided either via the `id` query parameter (comma-separated annotation IDs) or \nin the request body as a list of annotation URLs.\n\nFor queue-based export, refer to the [queue export endpoint](/api/queue#export-annotations).\n",
"operationId": "annotations_export_post",
"tags": [
"Annotation"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (JSON with body)",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"annotations\": [\"https://example.rossum.app/api/v1/annotations/315777\", \"https://example.rossum.app/api/v1/annotations/315778\"]}' \\\n 'https://example.rossum.app/api/v1/annotations/export?format=json&append_columns=meta_arrived_at,meta_url,meta_file&prepend_columns=meta_file_name&page_size=2'\n"
}
],
"parameters": [
{
"name": "format",
"in": "query",
"description": "Output format.",
"required": false,
"schema": {
"type": "string",
"enum": [
"csv",
"xml",
"json",
"xlsx"
]
}
},
{
"name": "columns",
"in": "query",
"description": "Columns to include in CSV/XLSX output (comma-separated schema_ids and meta-columns).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "prepend_columns",
"in": "query",
"description": "Columns to prepend at the beginning of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "append_columns",
"in": "query",
"description": "Columns to append at the end of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "delimiter",
"in": "query",
"description": "One-character string used to separate fields in CSV.",
"required": false,
"schema": {
"type": "string",
"default": ","
}
},
{
"name": "quote_char",
"in": "query",
"description": "One-character string used to quote fields containing special characters in CSV.",
"required": false,
"schema": {
"type": "string",
"default": "\""
}
},
{
"name": "quoting",
"in": "query",
"description": "Controls when quotes should be generated in CSV.",
"required": false,
"schema": {
"type": "string",
"enum": [
"quote_minimal",
"quote_none",
"quote_all",
"quote_non_numeric"
]
}
},
{
"name": "escape_char",
"in": "query",
"description": "One-character string used by the writer to escape the delimiter in CSV.",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "status",
"in": "query",
"description": "Annotation status filter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "modifier",
"in": "query",
"description": "User id filter.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "arrived_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "arrived_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"$ref": "#/components/parameters/page_size"
},
{
"name": "search",
"in": "query",
"description": "Search filter (limited to 10,000 results).",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotations": {
"type": "array",
"description": "List of URLs of annotations to export.",
"items": {
"type": "string",
"format": "uri",
"example": "https://example.rossum.app/api/v1/annotations/315777"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/csv": {
"schema": {
"type": "string"
}
},
"application/xml": {
"schema": {
"type": "string"
}
},
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/suggested_recipients": {
"post": {
"summary": "Retrieve suggested email recipients",
"description": "Retrieves annotations suggested email recipients depending on [Queue](/api/queue) suggested recipients settings.",
"operationId": "annotations_suggested_recipients",
"tags": [
"Annotation"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"annotations"
],
"properties": {
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of annotation URLs.",
"example": [
"https://example.rossum.app/api/v1/annotations/314528",
"https://example.rossum.app/api/v1/annotations/314529"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "Specifies where the email is found.",
"example": "email_header"
},
"email": {
"type": "string",
"format": "email",
"description": "Email address of the suggested recipient."
},
"name": {
"type": "string",
"description": "Name of the suggested recipient. Either a value from an email header or a value from parsing the email address.",
"example": "Don Joe"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/rotate": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Rotate annotation",
"description": "Rotate a document.\n\nStatus of the annotation is switched to `importing` and the extraction phase begins over again.\nAfter the new extraction, the value from `rotation_deg` field is copied to pages rotation field `rotation_deg`.\n\n\nThe original pages in the annotation are replaced by new pages after the extraction phase is done.\n\n",
"operationId": "annotations_rotate",
"tags": [
"Annotation"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"rotation_deg"
],
"properties": {
"rotation_deg": {
"type": "integer",
"enum": [
0,
90,
180,
270
],
"description": "States degrees by which the document shall be rotated."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/search": {
"post": {
"summary": "Search annotations",
"description": "Search for annotations matching a complex filter.\n\n\nPlease 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).\n\n\n\nPlease note that only objects of category `datapoint` are returned when sideloading for `content` is active. Objects of other categories are ignored.\n\n\n\nSideloading content for this endpoint is deprecated and will be removed in the near future.\n\n\n### Search Query\nA subset of MongoDB Query Language. Query expressions should be defined as a list under a `$and` key. The following\ncan be used:\n- `` - Matches against annotation attributes according to the `` - see options below.\n- `field..` - Matches against annotation content value according to `` treating it\nas a ``. Possible types: `string | number | date` (in ISO 8601 format). Max. 256 characters long strings\nare allowed.\n\n**The `meta_field` can be one of:**\n\n| Meta Field | Type |\n|-------------------------------------|--------|\n| `annotation` | URL |\n| `arrived_at` | date |\n| `assigned_at` | date |\n| `assignees` | URL |\n| `automated` | bool |\n| `automatically_rejected` | bool |\n| `confirmed_at` | date |\n| `confirmed_by__username` | string |\n| `confirmed_by` | URL |\n| `created_at` | date |\n| `creator__username` | string |\n| `creator` | URL |\n| `deleted_at` | date |\n| `deleted_by__username` | string |\n| `deleted_by` | URL |\n| `document` | URL |\n| `exported_at` | date |\n| `exported_by__username` | string |\n| `exported_by` | URL |\n| `has_email_thread_with_new_replies` | bool |\n| `has_email_thread_with_replies` | bool |\n| `labels` | URL |\n| `messages` | string |\n| `modified_at` | date |\n| `modifier__username` | string |\n| `modifier` | URL |\n| `original_file_name` | string |\n| `purged_at` | date |\n| `purged_by__username` | string |\n| `purged_by` | URL |\n| `queue` | URL |\n| `rejected_at` | date |\n| `rejected_by__username` | string |\n| `rejected_by` | URL |\n| `relations__key` | string |\n| `relations__parent` | URL |\n| `relations__type` | string |\n| `restricted_access` | bool |\n| `rir_poll_id` | string |\n| `status` | string |\n| `workspace` | URL |\n| `email_thread` | URL |\n| `email_sender` | string |\n\n**Search Query Objects**\n\n| Key | Type | Description |\n|------------------------------------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `$startsWith` | string | Matches the start of a value. Must be at least 2 characters long. |\n| `$anyTokenStartsWith` | string | Matches the start of each token within a string. Must be at least 2 characters long. |\n| `$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`. |\n| `$emptyOrMissing` | bool | Matches values that are empty or missing. When false, matches existing non-empty values. |\n| `$eq` | `$ne` | number | string | date | URL | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |\n| `$gt` | `$lt` | `$gte` | `$lte` | number | string | date | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |\n| `$in` | `$nin` | list[number | string | URL] | Default [MQL behavior](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/comparison/) |\n",
"operationId": "annotations_search",
"tags": [
"Annotation"
],
"parameters": [
{
"name": "ordering",
"in": "query",
"description": "Result ordering. Note: `field..` is also supported (where `format` is one of `number`, `date`, `string`).\n",
"required": false,
"schema": {
"type": "string",
"enum": [
"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",
"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"
]
}
},
{
"name": "page_size",
"in": "query",
"description": "Number of results per page. The maximum value is 500. For requests that sideload `content`, the maximum value is limited to 100. Sideloading content for this endpoint is deprecated and will be removed in the near future.",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"maximum": 500
}
},
{
"name": "search_after",
"in": "query",
"description": "Encoded value acting as a cursor (do not try to modify, only for internal purposes).",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/fields"
},
{
"$ref": "#/components/parameters/fields_exclude"
},
{
"$ref": "#/components/parameters/sideload"
},
{
"$ref": "#/components/parameters/content_schema_id"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "object",
"description": "A subset of MongoDB Query Language. If `query_string` is used together with `query`, search is done\nas a conjunction of these expressions (`query_string` AND `query`).\n",
"properties": {
"$and": {
"type": "array",
"description": "List of query definitions to be used for search. See [Search Query](#search-query) section for more details.",
"items": {
"type": "object"
},
"example": [
{
"field.vendor_name.string": {
"$eq": "ACME corp"
}
},
{
"labels": {
"$in": [
"https://example.rossum.app/api/v1/labels/12",
"https://example.rossum.app/api/v1/labels/34"
]
}
}
]
}
}
},
"query_string": {
"type": "object",
"description": "Apply full-text search to datapoint values using a chosen term. The value is searched by its prefix,\nseparately for each term separated by whitespace, in case-insensitive way. Special characters\nat the end of the strings are ignored. For example, when searching for a term `Large drink`,\nall of the following values passed would give a match: `lar#`, `lar dri`, `dri`. We search also\nin the non-extracted page data, if the data are available.\n\nIf `query_string` is used together with `query`, search is done as a conjunction of these expressions\n(`query_string` AND `query`).\n",
"properties": {
"string": {
"type": "string",
"description": "String to be used for full-text search. At least 2 characters need to be passed to apply this search.\nMax. 256 characters long strings are allowed.\n",
"minLength": 2,
"maxLength": 256,
"example": "Large drink"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination_with_total"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/annotation"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"410": {
"description": "Gone - Value of `search_after` is not valid anymore. Retry the search with a different value."
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/search": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"get": {
"summary": "Search text",
"description": "Search for a phrase in the document.",
"operationId": "annotations_search_text",
"tags": [
"Annotation"
],
"parameters": [
{
"name": "phrase",
"in": "query",
"required": true,
"description": "A phrase to search for.",
"schema": {
"type": "string"
}
},
{
"name": "tolerance",
"in": "query",
"required": false,
"description": "Allowed [Edit distance](https://en.wikipedia.org/wiki/Edit_distance) from the search phrase (number of removal,\ninsertion or substitution operations that need to be performed for strings to match). Only used for OCR invoices\n(images, such as png or PDF with scanned images). Default value is computed as `length(phrase)/4`.\n",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rectangle": {
"type": "array",
"items": {
"type": "number"
},
"description": "Bounding box of an occurrence.",
"example": [
67.15157010915198,
545.9286363906203,
87.99106633081445,
563.4617583852776
]
},
"page": {
"type": "integer",
"description": "Page of occurrence.",
"example": 1
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/split": {
"post": {
"summary": "Split annotation",
"operationId": "annotations_split",
"tags": [
"Annotation"
],
"description": "Splits an annotation into multiple separate annotations by reorganizing and possibly also rotating its pages.\nEach resulting annotation will have its own document with the specified pages.\n\nWhen using this endpoint, status of the original annotation is switched to `split`, status of the newly created\nannotations is `importing` and the extraction phase begins over again.\n\nThis endpoint can be used for splitting annotations also from webhook listening to `annotation_content.initialize`\nevent and action.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"documents"
],
"properties": {
"documents": {
"type": "array",
"minItems": 1,
"description": "List of [documents](/api/document) that should be created from the original annotation.",
"items": {
"type": "object",
"required": [
"pages"
],
"properties": {
"pages": {
"type": "array",
"minItems": 1,
"description": "List of [pages](/api/page) to include in this document",
"items": {
"type": "object",
"required": [
"page"
],
"properties": {
"page": {
"type": "string",
"format": "uri",
"description": "URL reference to the page",
"example": "https://example.rossum.app/api/v1/pages/12345"
},
"rotation_deg": {
"type": "integer",
"enum": [
0,
90,
180,
270
],
"description": "Rotation to apply to the page in degrees",
"example": 90
}
}
}
},
"metadata": {
"$ref": "#/components/schemas/edit_metadata"
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Annotation split successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of the created annotation",
"example": "https://example.rossum.app/api/v1/annotations/67890"
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "URL of the created document."
}
],
"example": "https://example.rossum.app/api/v1/documents/54321"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/edit_pages/start": {
"post": {
"summary": "Start edit pages session",
"operationId": "annotations_edit_pages_start",
"tags": [
"Annotation"
],
"description": "Starts editing the annotation and all its child documents (the documents into which the original document was split).\nThe parent annotation must be in the `to_review`, `split` or `reviewing` state (for the calling user). This call\nwill \"lock\" the parent and child annotations from being edited.\n\nIt returns some basic information about the parent annotation and a list of its children. Children to which\nthe current user does not have rights contains only limited information.\n\nIf the parent annotation cannot be \"locked\", an error is returned. If the child annotation cannot be locked, it is\nskipped and sent in a response with value `started=False`.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"responses": {
"200": {
"description": "Edit pages session started successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"parent_annotation": {
"type": "string",
"format": "uri",
"description": "URL of the parent annotation",
"example": "https://example.rossum.app/api/v1/annotations/12345"
},
"children": {
"type": "array",
"description": "List of child annotation objects",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/edit_child_annotation"
},
{
"type": "object",
"properties": {
"started": {
"type": "boolean",
"description": "Whether this child was started for review or not"
}
}
}
]
}
},
"session_timeout": {
"type": "string",
"description": "Session timeout duration format `\"HH:MM:SS\"`",
"example": "01:00:00"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/start": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Start validation",
"description": "Start reviewing annotation by the calling user. Can be called with `statuses` payload to specify allowed statuses for starting annotation.\nReturns `409 Conflict` if annotation fails to be in one of the specified states.\n",
"operationId": "annotations_start",
"tags": [
"Annotation"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statuses": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of allowed states for the starting annotation to be in.",
"default": [
"to_review",
"reviewing",
"postponed",
"confirmed"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of annotation.",
"example": "https://example.rossum.app/api/v1/annotations/12345"
},
"session_timeout": {
"type": "string",
"description": "Session timeout in format HH:MM:SS.",
"example": "01:00:00"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/start_embedded": {
"post": {
"summary": "Start validation for embedded use",
"operationId": "annotations_start_embedded",
"tags": [
"Annotation"
],
"description": "Start embedded annotation.\n\nEmbedded annotation cannot be started by users with admin or organization group admin roles. We strongly recommend\nstarting embedded annotations by users with `annotator_embedded` [user role](/api/user-role) and permissions\nfor the given queue only to limit the scope of actions that user is able to perform to required minimum.\n\nReturns object with url that specifies URL to be used in the browser iframe/popup window. URL includes a token that\nis valid for this document only for a limited period of time.\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"return_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to after annotation is confirmed",
"example": "https://service.com/return"
},
"cancel_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is cancelled",
"example": "https://service.com/cancel"
},
"delete_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is deleted",
"example": "https://service.com/delete"
},
"postpone_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "URL to redirect to when annotation is postponed",
"example": "https://service.com/postpone"
},
"max_token_lifetime_s": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 604800,
"description": "Duration (in seconds) for which the token will be valid. Default is the [queue's](/api/queue)\n`session_timeout.`\n",
"example": 3600
}
}
}
}
}
},
"responses": {
"200": {
"description": "Embedded URL created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Embedded URL with authentication token",
"example": "https://example.rossum.app/embedded/document/12345#authToken=db313f24f5738c8e04635e036ec8a45cdd6d6b03"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/postpone": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Switch to postponed",
"description": "Switch annotation status to `postpone`.\n\n",
"operationId": "annotations_postpone",
"tags": [
"Annotation"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/page_data/translate": {
"post": {
"summary": "Translate page spatial data",
"operationId": "annotations_page_data_translate",
"tags": [
"Annotation"
],
"description": "Get translation for all lines on a page, including position coordinates. Source language of the page is automatically\ndetected. Translated text of a page in a particular language is cached for 60 days.\n \n**Requirements:**\n- Document translations feature must be enabled for the organization\n- User must have translate permissions\n- Page must have OCR data available\n\n**Supported languages:**\n\n| Key | Description |\n|-------|-----------------------|\n| af | Afrikaans |\n| sq | Albanian |\n| am | Amharic |\n| ar | Arabic |\n| hy | Armenian |\n| az | Azerbaijani |\n| bn | Bengali |\n| bs | Bosnian |\n| bg | Bulgarian |\n| ca | Catalan |\n| zh | Chinese (Simplified) |\n| zh-TW | Chinese (Traditional) |\n| hr | Croatian |\n| cs | Czech |\n| da | Danish |\n| fa-AF | Dari |\n| nl | Dutch |\n| en | English |\n| et | Estonian |\n| fa | Farsi (Persian) |\n| tl | Filipino, Tagalog |\n| fi | Finnish |\n| fr | French |\n| fr-CA | French (Canada) |\n| ka | Georgian |\n| de | German |\n| el | Greek |\n| gu | Gujarati |\n| ht | Haitian Creole |\n| ha | Hausa |\n| he | Hebrew |\n| hi | Hindi |\n| hu | Hungarian |\n| is | Icelandic |\n| id | Indonesian |\n| ga | Irish |\n| it | Italian |\n| ja | Japanese |\n| kn | Kannada |\n| kk | Kazakh |\n| ko | Korean |\n| lv | Latvian |\n| lt | Lithuanian |\n| mk | Macedonian |\n| ms | Malay |\n| ml | Malayalam |\n| mt | Maltese |\n| mr | Marathi |\n| mn | Mongolian |\n| no | Norwegian (Bokmål) |\n| ps | Pashto |\n| pl | Polish |\n| pt | Portuguese (Brazil) |\n| pt-PT | Portuguese (Portugal) |\n| pa | Punjabi |\n| ro | Romanian |\n| ru | Russian |\n| sr | Serbian |\n| si | Sinhala |\n| sk | Slovak |\n| sl | Slovenian |\n| so | Somali |\n| es | Spanish |\n| es-MX | Spanish (Mexico) |\n| sw | Swahili |\n| sv | Swedish |\n| ta | Tamil |\n| te | Telugu |\n| th | Thai |\n| tr | Turkish |\n| uk | Ukrainian |\n| ur | Urdu |\n| uz | Uzbek |\n| vi | Vietnamese |\n| cy | Welsh |\n",
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"page_numbers",
"target_language",
"granularity"
],
"properties": {
"page_numbers": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"description": "Single page number to translate (currently only one page at a time is supported)",
"items": {
"type": "integer",
"minimum": 1
},
"example": [
1
]
},
"target_language": {
"type": "string",
"enum": [
"af",
"sq",
"am",
"ar",
"hy",
"az",
"bn",
"bs",
"bg",
"ca",
"zh",
"zh-TW",
"hr",
"cs",
"da",
"fa-AF",
"nl",
"en",
"et",
"fa",
"tl",
"fi",
"fr",
"fr-CA",
"ka",
"de",
"el",
"gu",
"ht",
"ha",
"he",
"hi",
"hu",
"is",
"id",
"ga",
"it",
"ja",
"kn",
"kk",
"ko",
"lv",
"lt",
"mk",
"ms",
"ml",
"mt",
"mr",
"mn",
"no",
"ps",
"pl",
"pt",
"pt-PT",
"pa",
"ro",
"ru",
"sr",
"si",
"sk",
"sl",
"so",
"es",
"es-MX",
"sw",
"sv",
"ta",
"te",
"th",
"tr",
"uk",
"ur",
"uz",
"vi",
"cy"
],
"minLength": 2,
"maxLength": 5,
"description": "Target language code. Either ISO 639-1 format or a combination of ISO 639-1 two-digit language code\nfollowed by an underscore followed by an ISO 3166 2-digit country code.\n",
"example": "es"
},
"granularity": {
"type": "string",
"enum": [
"lines"
],
"description": "Level of text granularity",
"example": "lines"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Translation completed successfully (or retrieved from cache)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"page_number": {
"type": "integer",
"description": "Page number",
"example": 1
},
"granularity": {
"type": "string",
"description": "Granularity level",
"example": "lines"
},
"items": {
"type": "array",
"description": "Translated text items with original positions",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Translated text",
"example": "Factura"
},
"position": {
"type": "array",
"description": "Coordinates of the item on the given page",
"items": {
"type": "integer"
},
"minItems": 4,
"maxItems": 4,
"example": [
100,
50,
150,
20
]
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content": {
"get": {
"summary": "Retrieve annotation content",
"description": "Returns annotation content in a form of datapoint tree.\n\n",
"operationId": "annotations_content",
"tags": [
"Annotation Content"
],
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "array",
"description": "Represents the full content of an annotation, composed of sections and datapoints.\nTop level `content` contains a list of section objects. `results` is currently a copy of content and is deprecated.\n",
"items": {
"$ref": "#/components/schemas/annotation_content_section"
}
},
"results": {
"type": "array",
"deprecated": true
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Update annotation content",
"description": "Update annotation content. The format is the same as for GET, datapoints missing in the\nuploaded content are preserved.\n\n\nPlease note that tuples must contain all children datapoints. Otherwise the behavior\nis undefined (original and updated datapoints may be mixed).\n\n",
"operationId": "annotations_content_partial_update",
"tags": [
"Annotation Content"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/{nodeID}/add_empty": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "nodeID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the multivalue node"
}
],
"post": {
"summary": "Add row to multivalue datapoint",
"description": "Adds a row to a multivalue table. This row will not be connected to the grid and modifications of the grid will not trigger any OCR on the cells of this row.\n",
"operationId": "annotations_content_add_empty",
"tags": [
"Annotation Content"
],
"responses": {
"200": {
"description": "Row added successfully.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/operations": {
"post": {
"summary": "Bulk update annotation content",
"description": "Allows to specify a sequence of operations that should be performed on particular datapoint objects.\n\nTo replace a `datapoint` value (or other supported attribute), use *replace* operation.\nTo add a new row into a table `multivalue`, use *add* operation.\nTo remove a row from a multivalue, use *remove* operation.\n\nPlease note that only `multivalue` children datapoints may be removed.\nPlease note that `section`, `multivalue` and `tuple` should not be updated.\n\n\n",
"operationId": "annotations_content_operations",
"tags": [
"Annotation Content"
],
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bulk_operations_request"
},
"examples": {
"bulk_update_operations": {
"description": "Example showing how to perform multiple operations in a single request:\n- Replace a datapoint value\n- Remove a datapoint\n- Add a new row to a line items table\n",
"value": {
"operations": [
{
"op": "replace",
"id": 198143,
"value": {
"content": {
"value": "John",
"position": [
103,
110,
121,
122
],
"page": 1
},
"hidden": false,
"options": [],
"validation_sources": [
"human"
]
}
},
{
"op": "remove",
"id": 884061
},
{
"op": "add",
"id": 884060,
"value": [
{
"schema_id": "item_description",
"content": {
"page": 1,
"position": [
100,
100,
200,
200
],
"value": "Some description"
}
}
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/{nodeID}/transform_grid_to_datapoints": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "nodeID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the multivalue node"
}
],
"post": {
"summary": "Convert grid to table data",
"description": "Transform grid structure to tabular data of related multivalue object.\n\n\nThis endpoint will be deprecated in the near future. It will be fully removed in the future. Please use the grid operations and partial grid operations endpoints.\n\n",
"operationId": "annotations_content_transform_grid_to_datapoints",
"tags": [
"Annotation Content"
],
"responses": {
"200": {
"description": "All tuple datapoints and their children are returned.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/{multivalueID}/grid_operations": {
"post": {
"summary": "Grid operations",
"description": "This endpoint applies multiple operations on multiple grids for one multivalue and performs OCR if required,\nand updates the multivalue with the resulting grid.\n\nFor `update` operation the position of the grid and its rows and columns can be changed, the column layout\ncan be changed, but the row structure must be unchanged.\n\nThe operations are applied sequentially. The `grid_index` corresponds to the index of the grid parts when\nthe operation is applied. Combining different types of operations is not supported.\n",
"operationId": "annotations_content_grid_operations",
"tags": [
"Annotation Content"
],
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "multivalueID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the multivalue"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/grid_operations_request"
},
"examples": {
"update_grid": {
"description": "Example showing how to update a grid structure for a line items table,\nincluding column positions, schema mappings, and row definitions.\n",
"value": {
"operations": [
{
"op": "update",
"grid_index": 0,
"grid": {
"page": 1,
"columns": [
{
"left_position": 50.5,
"schema_id": "item_description",
"header_texts": [
"Description"
]
},
{
"left_position": 250,
"schema_id": "item_quantity",
"header_texts": [
"Qty"
]
},
{
"left_position": 350,
"schema_id": "item_amount",
"header_texts": [
"Amount"
]
}
],
"rows": [
{
"top_position": 150.5,
"tuple_id": 27801932,
"type": "data",
"tuple_index": 0
},
{
"top_position": 180.5,
"tuple_id": 27801940,
"type": "data",
"tuple_index": 1
}
],
"width": 500,
"height": 200
}
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK - Returns updated multivalue content as a tree, with only updated datapoints",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content_multivalue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/{multivalueID}/grid_parts_operations": {
"post": {
"summary": "Partial update grid",
"description": "Apply multiple operations on a grid and perform OCR on modified cell datapoints. Update the multivalue with the new grid.\n\nOperations are grouped in `rows` operations and `columns` operations.\n\nPossible operations:\n\n| axis | op | required parameters | OCR | Result |\n|---------|-----------|---------------------|------|-----------------------------------------------------|\n| columns | update | schema_id | Yes | Update column datapoints |\n| columns | delete | schema_id | No | Set content to empty for column datapoints |\n| rows | create | row_index | Yes | Insert a new row, create datapoints and perform OCR |\n| rows | update | row_index, tuple_id | Yes | Update datapoints via OCR |\n| rows | delete | tuple_id | No | Delete the tuple associated to this row |\n\nOCR is performed only for rows of extractable type as defined in the multivalue schema by `row_types_to_extract`,\nor by default for rows of type `data` only.\n",
"operationId": "annotations_content_grid_parts_operations",
"tags": [
"Annotation Content"
],
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "multivalueID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the multivalue"
},
{
"name": "full_response",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Use this parameter to get all datapoints in the grid part in the response"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/grid_parts_operations_request"
},
"examples": {
"partial_grid_update": {
"description": "Example showing how to perform partial updates on a grid structure,\nincluding updating a row via OCR and updating a column.\n",
"value": {
"grid_index": 0,
"grid": {
"page": 1,
"columns": [
{
"left_position": 50.5,
"schema_id": "item_description",
"header_texts": [
"Description"
]
},
{
"left_position": 250,
"schema_id": "item_quantity",
"header_texts": [
"Qty"
]
},
{
"left_position": 350,
"schema_id": "item_amount",
"header_texts": [
"Amount"
]
}
],
"rows": [
{
"top_position": 150.5,
"tuple_id": 27801932,
"type": "data",
"tuple_index": 0
},
{
"top_position": 180.5,
"tuple_id": 27801940,
"type": "data",
"tuple_index": 1
}
],
"width": 500,
"height": 200
},
"operations": {
"rows": [
{
"op": "update",
"row_index": 0,
"tuple_id": 27801932,
"schema_id": "item_description"
}
],
"columns": [
{
"op": "update",
"schema_id": "item_amount"
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK - Returns updated multivalue content as a tree. By default, only updated datapoints and updated grid\nare returned. Add `?full_response=true` to get all the datapoints in this grid.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content_multivalue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/{nodeID}/select": {
"post": {
"summary": "Replace annotation content by OCR",
"description": "Replace annotation content by OCR extracted from the rectangle of the document page.\n\nWhen the rectangle size is unsuitable for OCR (any rectangle side is smaller than 4 px),\nrectangle is extended to cover the text that overlaps with the rectangle.\n\n\n",
"operationId": "annotations_content_select",
"tags": [
"Annotation Content"
],
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
},
{
"name": "nodeID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the child node"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/select_request"
},
"examples": {
"select_ocr_request": {
"description": "Request to extract text via OCR from a specific rectangular area on a document page.\n",
"value": {
"rectangle": [
150,
300,
450,
325
],
"page": "https://example.rossum.app/api/v1/pages/32340"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/annotation_content"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/content/validate": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
],
"post": {
"summary": "Validate annotation content",
"description": "Validate the content of an annotation.\nAt first, the content is sent to the validate hook of connected extension.\nThen some standard validations (data `type`, `constraints` are checked) are carried out in Rossum.\nAdditionally, if the annotation's respective queue has enabled delete recommendation conditions,\nthey are evaluated as well.\n\nBy default, messages for hidden datapoints are omitted. The behavior could be changed using the `messages_for_hidden_datapoints=true` query parameter.\n",
"operationId": "annotations_content_validate",
"tags": [
"Annotation Content"
],
"parameters": [
{
"name": "messages_for_hidden_datapoints",
"in": "query",
"description": "Include messages for hidden datapoints",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"actions": {
"type": "array",
"description": "Validation actions. Possible values: `[\"user_update\"]`, `[\"user_update\", \"updated\"]` or `[\"user_update\", \"started\"]`\n",
"items": {
"type": "string",
"enum": [
"user_update",
"updated",
"started"
]
},
"default": [
"user_update"
]
},
"updated_datapoint_ids": {
"type": "array",
"description": "List of IDs of datapoints that were changed since last call of this endpoint.",
"items": {
"type": "integer"
}
}
}
},
"examples": {
"validate_user_update": {
"description": "Request validation after user has updated specific datapoints (e.g., invoice number and total amount).\n",
"value": {
"actions": [
"user_update"
],
"updated_datapoint_ids": [
37507206,
37507215
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Validation results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"description": "Validation messages",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the concerned datapoint; \"all\" for a document-wide issues"
},
"type": {
"type": "string",
"enum": [
"error",
"warning",
"info",
"aggregation"
],
"description": "Message type"
},
"content": {
"type": "string",
"description": "A message shown in UI. Limited to 4096 characters."
},
"detail": {
"type": "object",
"description": "Detail object that gives more context to the message",
"properties": {
"hook_id": {
"type": [
"integer",
"null"
],
"description": "ID of the hook, null for computed fields"
},
"hook_name": {
"type": "string",
"description": "Name of the hook"
},
"request_id": {
"type": "string",
"description": "ID of the request preceding this hook's response"
},
"timestamp": {
"type": "string",
"description": "Timestamp of the request preceding this hook's response"
},
"is_exception": {
"type": "boolean",
"description": "Flag signaling non-200 response from the hook or error during computed field evaluation"
},
"traceback_line_number": {
"type": "integer",
"description": "Line of the error in the computed field code"
},
"source_id": {
"type": "integer",
"description": "ID of the datapoint which created this message"
},
"source_schema_id": {
"type": "string",
"description": "Schema id of the datapoint which created this message"
}
}
},
"aggregation_type": {
"type": "string",
"description": "Type of aggregation (present only in message with type \"aggregation\")"
},
"schema_id": {
"type": "string",
"description": "Identifier of schema datapoint for which is aggregation computed (present only in message with type \"aggregation\")"
}
}
}
},
"updated_datapoints": {
"type": "array",
"description": "The subtrees of datapoints updated from an extension",
"items": {
"type": "object"
}
},
"suggested_operations": {
"type": "array",
"description": "Datapoint operations suggested as a result of validation",
"items": {
"type": "object"
}
},
"matched_trigger_rules": {
"type": "array",
"description": "Delete Recommendation rules that matched",
"items": {
"type": "object"
}
}
}
},
"examples": {
"validation_with_warning": {
"description": "Example response showing a validation warning from a hook about a potential issue with the total amount.\n",
"value": {
"messages": [
{
"id": "37507215",
"type": "warning",
"content": "Total amount seems unusually high for this vendor",
"detail": {
"hook_id": 12345,
"hook_name": "Amount Validation Hook",
"request_id": "0378f1b1-1e6e-4751-884e-c9df6d0777bc",
"timestamp": "2024-12-17T14:20:00Z",
"is_exception": false,
"source_id": 37507215,
"source_schema_id": "amount_total"
}
}
],
"updated_datapoints": [],
"suggested_operations": [],
"matched_trigger_rules": []
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/annotations/{annotationID}/processing_duration": {
"parameters": [
{
"$ref": "#/components/parameters/annotationID"
}
]
},
"/api/v1/audit_logs": {
"get": {
"summary": "List audit logs",
"description": "List audit log records for chosen objects and actions.\n\nOnly admin or organization group admins can access the log records.\n",
"operationId": "audit_logs_list",
"tags": [
"Audit Log"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/object_type"
},
{
"$ref": "#/components/parameters/action"
},
{
"$ref": "#/components/parameters/object_id"
},
{
"$ref": "#/components/parameters/timestamp_before"
},
{
"$ref": "#/components/parameters/timestamp_after"
},
{
"$ref": "#/components/parameters/username"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/audit_log"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/automation_blockers": {
"get": {
"summary": "List automation blockers",
"description": "List all automation blocker objects.",
"operationId": "automation_blockers_list",
"tags": [
"Automation Blocker"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "annotation",
"in": "query",
"description": "ID of an annotation to filter automation blockers by",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/automation_blocker"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/automation_blockers/{id}": {
"get": {
"summary": "Retrieve automation blocker",
"description": "Retrieve a specific automation blocker object.",
"operationId": "automation_blockers_retrieve",
"tags": [
"Automation Blocker"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "A unique integer value identifying this automation blocker.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/automation_blocker"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/connectors": {
"post": {
"summary": "Create connector",
"description": "Create a new connector object.",
"operationId": "connectors_create",
"tags": [
"Connector"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector",
"required": [
"name",
"service_url"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List connectors",
"description": "Retrieve all connector objects.",
"operationId": "connectors_list",
"tags": [
"Connector"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "name",
"in": "query",
"description": "Name of the connector filter",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "service_url",
"in": "query",
"description": "Service URL of the connector filter",
"required": false,
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"service_url",
"-service_url"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/connector"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/connectors/{connectorID}": {
"get": {
"summary": "Retrieve connector",
"description": "Get a connector object.",
"operationId": "connectors_retrieve",
"tags": [
"Connector"
],
"parameters": [
{
"$ref": "#/components/parameters/connectorID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update connector",
"description": "Update connector object.",
"operationId": "connectors_update",
"tags": [
"Connector"
],
"parameters": [
{
"$ref": "#/components/parameters/connectorID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector",
"required": [
"name",
"service_url"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update connector",
"description": "Update part of connector object.",
"operationId": "connectors_partial_update",
"tags": [
"Connector"
],
"parameters": [
{
"$ref": "#/components/parameters/connectorID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/connector"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete connector",
"description": "Delete connector object.",
"operationId": "connectors_delete",
"tags": [
"Connector"
],
"parameters": [
{
"$ref": "#/components/parameters/connectorID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engines": {
"post": {
"summary": "Create dedicated engine",
"description": "Create a new dedicated engine object.\n\n\nTalk with a Rossum representative about enabling this feature. You can create new Dedicated Engine objects. However, no Dedicated Engine will be trained unless Dedicated Engines are part of your agreement.\n\n",
"operationId": "dedicated_engines_create",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine",
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List dedicated engines",
"description": "Retrieve all dedicated engine objects.\n",
"operationId": "dedicated_engines_list",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"status",
"-status"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dedicated_engine"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engines/{dedicatedEngineID}": {
"get": {
"summary": "Retrieve dedicated engine",
"description": "Get a dedicated engine object.\n",
"operationId": "dedicated_engines_retrieve",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update dedicated engine",
"description": "Update dedicated engine object.\n\n\nIf status is not `draft`, the whole engine and its schema become read-only.\n\n",
"operationId": "dedicated_engines_update",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine",
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update dedicated engine",
"description": "Update part of a dedicated engine object.\n\n\nIf status is not `draft`, the whole engine and its schema become read-only.\n\n",
"operationId": "dedicated_engines_partial_update",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete dedicated engine",
"description": "Delete dedicated engine object.\n",
"operationId": "dedicated_engines_delete",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engines/request": {
"post": {
"summary": "Request dedicated engine",
"description": "Request training of a new Dedicated Engine using a form (multipart/form-data).\n\n\nTalk with a Rossum representative about enabling this feature. You can create new Dedicated Engine objects. However, no Dedicated Engine will be trained unless Dedicated Engines are part of your agreement.\n\n",
"operationId": "dedicated_engines_request",
"tags": [
"Dedicated Engine"
],
"deprecated": true,
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_request"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engine_schemas": {
"post": {
"summary": "Create dedicated engine schema",
"description": "Create a new dedicated engine schema object.\n",
"operationId": "dedicated_engine_schemas_create",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema",
"required": [
"content"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List dedicated engine schemas",
"description": "Retrieve all dedicated engine schema objects.\n\n**Please note that Dedicated Engine Schema is an internal API and can be changed without notice.**\n",
"operationId": "dedicated_engine_schemas_list",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engine_schemas/{dedicatedEngineSchemaID}": {
"get": {
"summary": "Retrieve dedicated engine schema",
"description": "Get a dedicated engine schema object.\n",
"operationId": "dedicated_engine_schemas_retrieve",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineSchemaID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update dedicated engine schema",
"description": "Update dedicated engine schema object.\n\n**Please note that Dedicated Engine Schema is an internal API and can be changed without notice.**\n",
"operationId": "dedicated_engine_schemas_update",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineSchemaID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema",
"required": [
"content"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update dedicated engine schema",
"description": "Update part of a dedicated engine schema object.\n\n**Please note that Dedicated Engine Schema is an internal API and can be changed without notice.**\n",
"operationId": "dedicated_engine_schemas_partial_update",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineSchemaID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dedicated_engine_schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete dedicated engine schema",
"description": "Delete a dedicated engine schema object.\n\n**Please note that Dedicated Engine Schema is an internal API and can be changed without notice.**\n",
"operationId": "dedicated_engine_schemas_delete",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/dedicatedEngineSchemaID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engine_schemas/predict": {
"post": {
"summary": "Predict dedicated engine schema",
"description": "Try to predict a dedicated engine schema based on the provided training queue's schemas. The predicted schema is not guaranteed to pass `/v1/dedicated_engine_schemas/validate` check, only the checks done on engine schema save.\n\nReturns 200 and predicted dedicated engine schema.\n",
"operationId": "dedicated_engine_schemas_predict",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/predict_request"
}
}
}
},
"responses": {
"200": {
"description": "Predicted dedicated engine schema",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/predict_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/dedicated_engine_schemas/validate": {
"post": {
"summary": "Validate dedicated engine schema",
"description": "Validate dedicated engine schema object, check for errors. Additionally, to the basic checks done by the CRUD endpoints, this endpoint checks that:\n\n* The declared `engine_output_id`s are unique across the whole schema\n* The mapped Queue datapoints (via `schema_id`s) are of the same type as the declared `type`\n* The mapped Queue datapoints of `enum` type have exactly the same option values declared\n* Different shapes of datapoints are not mixed together\n* The mapped Queue datapoints of Multivalue-Tuple fields are of the same `grid`/`freeform` type\n* When mapping to a single Multivalue-Tuple field, all the datapoints mapped from one Queue must come from a single tabular datapoint\n* Multiple fields do not link to the same Queue Datapoint\n* A mapped field either maps a Queue Datapoint with `null`/empty `rir_field_names` or the `engine_output_id` matches one of the mapped rir-namespaced `rir_field_names` (prefixed by `rir:` or nothing)\n\nReturns 200 and error description in case of validation failure.\n",
"operationId": "dedicated_engine_schemas_validate",
"tags": [
"Dedicated Engine Schema"
],
"deprecated": true,
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/validate_request"
}
}
}
},
"responses": {
"200": {
"description": "Validation result (success or failure with error description)",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Validation result object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/delete_recommendations": {
"post": {
"summary": "Create delete recommendation",
"description": "Create a new delete recommendation object.",
"operationId": "delete_recommendations_create",
"tags": [
"Delete Recommendation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation",
"required": [
"queue",
"triggers"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List delete recommendations",
"description": "Retrieve all delete recommendations objects.",
"operationId": "delete_recommendations_list",
"tags": [
"Delete Recommendation"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/queue"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"queue",
"-queue"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/delete_recommendations/{deleteRecommendationID}": {
"get": {
"summary": "Retrieve delete recommendation",
"description": "Get a delete recommendation object.",
"operationId": "delete_recommendations_retrieve",
"tags": [
"Delete Recommendation"
],
"parameters": [
{
"$ref": "#/components/parameters/deleteRecommendationID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update delete recommendation",
"description": "Update a delete recommendation object.",
"operationId": "delete_recommendations_update",
"tags": [
"Delete Recommendation"
],
"parameters": [
{
"$ref": "#/components/parameters/deleteRecommendationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation",
"required": [
"organization",
"queue",
"triggers"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update delete recommendation",
"description": "Update a part of a delete recommendation object.",
"operationId": "delete_recommendations_partial_update",
"tags": [
"Delete Recommendation"
],
"parameters": [
{
"$ref": "#/components/parameters/deleteRecommendationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_recommendation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete delete recommendation",
"description": "Remove a delete recommendation object.",
"operationId": "delete_recommendations_delete",
"tags": [
"Delete Recommendation"
],
"parameters": [
{
"$ref": "#/components/parameters/deleteRecommendationID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents": {
"post": {
"summary": "Create document",
"operationId": "documents_create",
"description": "Create a new document object.\n\nUse this API call to create a document without an annotation. Suitable for creating documents for mime types that cannot be extracted by Rossum. Only one document can be created per request.\n\nThe supported mime types are the same as for document import.\n",
"tags": [
"Document"
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/documents_create"
}
},
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (multipart/form-data)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n-F content=@document.pdf \\\n-F metadata='{\"project\":\"Market ABC\"}' \\\n-F parent='https://elis.rossum.ai/api/v1/documents/456700' \\\n'https://elis.rossum.ai/api/v1/documents'\n"
},
{
"lang": "python",
"label": "Python (multipart/form-data)",
"source": "import requests\n\nurl = 'https://elis.rossum.ai/api/v1/documents'\ntoken = 'db313f24f5738c8e04635e036ec8a45cdd6d6b03'\n\nheaders = {\n 'Authorization': f'Bearer {token}',\n}\n\nfiles = {\n 'content': ('document.pdf', open('document.pdf', 'rb'), 'application/pdf'),\n}\n\ndata = {\n 'metadata': '{\"project\":\"Market ABC\"}',\n 'parent': 'https://elis.rossum.ai/api/v1/documents/456700'\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\n\nprint(response.status_code)\nprint(response.json())\n\nfiles['content'][1].close()\n"
},
{
"lang": "shell",
"label": "cURL (binary)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -H 'Content-Disposition: attachment; filename=\"document.pdf\"' \\\n --data-binary @document.pdf \\\n 'https://elis.rossum.ai/api/v1/documents'\n"
},
{
"lang": "shell",
"label": "cURL (binary - UTF-8)",
"source": "# UTF-8 filename must be URL encoded\ncurl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -H \"Content-Disposition: attachment; filename*=utf-8''document%20%F0%9F%8E%81.pdf\" \\\n --data-binary @file.pdf \\\n 'https://elis.rossum.ai/api/v1/documents'\n"
},
{
"lang": "python",
"label": "Python (binary)",
"source": "import requests\n\nurl = 'https://elis.rossum.ai/api/v1/documents'\ntoken = 'db313f24f5738c8e04635e036ec8a45cdd6d6b03'\nfile_path = 'document.pdf'\n\nheaders = {\n 'Authorization': f'Bearer {token}',\n 'Content-Type': 'application/octet-stream',\n 'Content-Disposition': 'attachment; filename=\"document.pdf\"',\n}\n\nwith open(file_path, 'rb') as f:\n response = requests.post(url, headers=headers, data=f)\n\nprint(response.status_code)\nprint(response.json())\n"
}
],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "This error object can have any number of properties, and their names and types are not predefined.",
"example": {
"detail": "Missing filename. Request should include a Content-Disposition header with a filename parameter.",
"code": "parse_error"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List documents",
"description": "Returns paginated response with a list of document objects.\n",
"operationId": "documents_list",
"tags": [
"Document"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/email"
},
{
"$ref": "#/components/parameters/creator"
},
{
"$ref": "#/components/parameters/created_at_before"
},
{
"$ref": "#/components/parameters/created_at_after"
},
{
"$ref": "#/components/parameters/arrived_at_before-2"
},
{
"$ref": "#/components/parameters/arrived_at_after-2"
},
{
"$ref": "#/components/parameters/original_file_name"
},
{
"$ref": "#/components/parameters/attachment_status"
},
{
"$ref": "#/components/parameters/parent"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"arrived_at",
"-arrived_at",
"created_at",
"-created_at",
"original_file_name",
"-original_file_name",
"mime_type",
"-mime_type",
"attachment_status",
"-attachment_status"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/document"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents/{documentID}": {
"get": {
"summary": "Retrieve document",
"description": "Get a document object.\n",
"operationId": "documents_retrieve",
"tags": [
"Document"
],
"parameters": [
{
"$ref": "#/components/parameters/documentID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update document",
"description": "Update part of a document object.\n",
"operationId": "documents_partial_update",
"tags": [
"Document"
],
"parameters": [
{
"$ref": "#/components/parameters/documentID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete document",
"description": "Delete document object.\n",
"operationId": "documents_delete",
"tags": [
"Document"
],
"parameters": [
{
"$ref": "#/components/parameters/documentID"
}
],
"responses": {
"204": {
"description": "Document successfully deleted."
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"description": "Document cannot be deleted due to existing annotation reference.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Document is still referenced."
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents/{documentID}/content": {
"get": {
"summary": "Retrieve document content",
"description": "Get original document content (e.g. PDF file).\n\nTo download multiple documents in one archive, refer to documents download object.\n",
"operationId": "documents_content_retrieve",
"tags": [
"Document"
],
"parameters": [
{
"$ref": "#/components/parameters/documentID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/original/{DocumentS3Name}": {
"get": {
"summary": "Retrieve original document",
"description": "Get original document content (e.g. PDF file).\n\n\nNote that this endpoint was intended to access document content, but is now deprecated. Use [content](/api/document#documents_content) endpoint instead.\n\n",
"operationId": "original_content",
"tags": [
"Document"
],
"deprecated": true,
"parameters": [
{
"name": "DocumentS3Name",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Internal S3 name of the document",
"example": "272c2f01ae84a4e19a421cb432e490bb"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/document_relations": {
"post": {
"summary": "Create document relation",
"description": "Create a new document relation object.",
"operationId": "document_relations_create",
"tags": [
"Document Relation"
],
"x-beta": true,
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation",
"required": [
"type",
"annotation"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List document relations",
"description": "Retrieve all document relation objects.",
"operationId": "document_relations_list",
"tags": [
"Document Relation"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/document_relation_type"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/key"
},
{
"$ref": "#/components/parameters/documents"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"type",
"-type",
"annotation",
"-annotation"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/document_relation"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/document_relations/{documentRelationID}": {
"get": {
"summary": "Retrieve document relation",
"description": "Get a document relation object.",
"operationId": "document_relations_retrieve",
"tags": [
"Document Relation"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/documentRelationID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update document relation",
"description": "Update document relation object.",
"operationId": "document_relations_update",
"tags": [
"Document Relation"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/documentRelationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation",
"required": [
"type",
"annotation"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update document relation",
"description": "Update part of a document relation object.",
"operationId": "document_relations_partial_update",
"tags": [
"Document Relation"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/documentRelationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/document_relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete document relation",
"description": "Delete a document relation object with empty related documents. If some documents still participate in the relation,\nthe caller must first delete those documents or update the document relation before deleting it.\n",
"operationId": "document_relations_delete",
"tags": [
"Document Relation"
],
"x-beta": true,
"parameters": [
{
"$ref": "#/components/parameters/documentRelationID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents/downloads": {
"post": {
"summary": "Create download",
"description": "Create a new download object.\n",
"operationId": "documents_downloads_create",
"tags": [
"Documents Download"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/documents_download",
"required": [
"documents"
]
}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"headers": {
"Location": {
"description": "URL of the created [task](/api/task)",
"schema": {
"type": "string",
"format": "uri"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the created [task](/api/task)",
"example": "https://example.rossum.app/api/v1/tasks/1"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents/downloads/{documentsDownloadID}": {
"get": {
"summary": "Retrieve download",
"description": "Get a download object.\n",
"operationId": "documents_downloads_retrieve",
"tags": [
"Documents Download"
],
"parameters": [
{
"$ref": "#/components/parameters/documentsDownloadID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/documents_download"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/documents/downloads/{documentsDownloadID}/content": {
"get": {
"summary": "Retrieve download content",
"description": "Get archive with original document files.\n",
"operationId": "documents_downloads_content_retrieve",
"tags": [
"Documents Download"
],
"parameters": [
{
"$ref": "#/components/parameters/documentsDownloadID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary",
"description": "Archive with original document files"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/emails": {
"get": {
"summary": "List emails",
"description": "Retrieve all emails objects.",
"operationId": "emails_list",
"tags": [
"Email"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/created_at_before-2"
},
{
"$ref": "#/components/parameters/created_at_after-2"
},
{
"$ref": "#/components/parameters/subject"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/inbox"
},
{
"$ref": "#/components/parameters/documents-2"
},
{
"$ref": "#/components/parameters/from__email"
},
{
"$ref": "#/components/parameters/from__name"
},
{
"$ref": "#/components/parameters/to"
},
{
"$ref": "#/components/parameters/last_thread_email_created_at_before"
},
{
"$ref": "#/components/parameters/last_thread_email_created_at_after"
},
{
"$ref": "#/components/parameters/email_type"
},
{
"$ref": "#/components/parameters/email_thread"
},
{
"$ref": "#/components/parameters/has_documents"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"created_at",
"-created_at",
"subject",
"-subject",
"queue",
"-queue",
"inbox",
"-inbox",
"from__email",
"-from__email",
"from__name",
"-from__name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/emails/{emailID}": {
"get": {
"summary": "Retrieve email",
"description": "Get an email object.",
"operationId": "emails_retrieve",
"tags": [
"Email"
],
"parameters": [
{
"$ref": "#/components/parameters/emailID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update email",
"description": "Update email object.",
"operationId": "emails_update",
"tags": [
"Email"
],
"parameters": [
{
"$ref": "#/components/parameters/emailID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email",
"required": [
"queue",
"inbox"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update email",
"description": "Update part of email object.",
"operationId": "emails_partial_update",
"tags": [
"Email"
],
"parameters": [
{
"$ref": "#/components/parameters/emailID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/emails/import": {
"post": {
"summary": "Import email",
"description": "Import an email as raw data. Calling this endpoint starts an asynchronous process of creating\nan email object and importing its contents to the specified recipient inbox in Rossum. This endpoint\ncan be used only by `admin` and `organization_group_admin` roles and email can be imported only to\ninboxes within the organization. The caller of this endpoint will be specified as the `creator` of the email.\nThe email sender specified in the `from` header will still receive any automated notifications targeted to the\nemail recipients.\n\nImport email endpoint is asynchronous and response contains created task\nurl. Further information about the import status may be acquired by retrieving\nthe email object or the task (for more information, please refer to [task](/api/task.)\n",
"operationId": "emails_import",
"tags": [
"Email"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"raw_message": {
"type": "string",
"format": "binary",
"description": "Raw email data."
},
"recipient": {
"type": "string",
"format": "email",
"description": "Email address of the inbox where the email will be imported."
},
"metadata": {
"type": "string",
"description": "JSON object with metadata to be set on created annotations.",
"example": "{\"source\":\"rossum\",\"batch_id\":\"12345\"}"
},
"values": {
"type": "string",
"description": "JSON object with values to be set on created annotations. All keys must start with the `emails_import:` prefix (e.g., `emails_import:customer_id`).",
"example": "{\"emails_import:customer_id\":\"CUST-001\",\"emails_import:order_number\":\"ORD-456\"}"
}
},
"required": [
"raw_message",
"recipient"
]
}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the created [task](/api/task)",
"example": "https://example.rossum.app/api/v1/tasks/1"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/emails/{emailID}/content": {
"get": {
"summary": "Retrieve email content",
"description": "Retrieve content of email.\n\n**Email content is unprocessed, unsanitized content and may contain possibly dangerous attachments.\nBe cautious while working with it.**\n",
"operationId": "emails_content_retrieve",
"tags": [
"Email"
],
"parameters": [
{
"$ref": "#/components/parameters/emailID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/emails/send": {
"post": {
"summary": "Send email",
"description": "Send email to specified recipients. The number of emails that can be sent is limited (10 for trials accounts).\n\nAt least one email in `to`, `cc`, `bcc` must be filled. The total number of recipients (`to`, `cc` and `bcc` together) cannot exceed 40.\n\nIf the related annotation has `null` email thread, it will be linked to the [email thread](/api/email-thread) related to the email created.\n\n### Template values\nThe object `template_values` is used to create an outgoing email. Key `subject` is used to fill an email subject and `message` is used to fill a body of the email (it may contain a subset of HTML). Values may contain other placeholders that are either built-in (see below) or specified in the `template_values`. For placeholders referring to annotations, the annotations from `related_annotations` attribute are used for filling in correct values.\n\n### List of built-in placeholders\n \n| Placeholder | Description | Can be used in automation |\n|----------------------------------------|--------------------------------------------------------------------|---------------------------|\n| organization_name | Name of the organization. | True |\n| app_url | App root url | True |\n| user_name | Username of the user sending the email. | False |\n| current_user_fullname | Full name of user sending the email. | False |\n| current_user_email | Email address of the user sending the email. | False |\n| parent_email_subject | Subject of the email we are replying to. | True |\n| sender_email | Email address of the author of the incoming email. | True |\n| annotation.document.original_file_name | Filenames of the documents belonging to the related annotation(s) | True |\n| annotation.content.value.{schema_id} | Content value of datapoints from email related annotation(s) | True |\n| annotation.id | IDs of the related annotation(s) | True |\n| annotation.url | Urls of the related annotation(s) | True |\n| annotation.assignee_email | Emails of the assigned users to the related annotation(s) | True |\n",
"operationId": "emails_send",
"tags": [
"Email"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/send_email_request"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the created email",
"example": "https://example.rossum.app/api/v1/emails/1234"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/email_templates": {
"post": {
"summary": "Create email template",
"description": "Create new email template object.",
"operationId": "email_templates_create",
"tags": [
"Email Template"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template",
"required": [
"name",
"queue"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List email templates",
"description": "Retrieve all email template objects.",
"operationId": "email_templates_list",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/type"
},
{
"$ref": "#/components/parameters/name"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_template"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/email_templates/{emailTemplateID}": {
"get": {
"summary": "Retrieve email template",
"description": "Get an email template object.",
"operationId": "email_templates_retrieve",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/emailTemplateID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update email template",
"description": "Update email template object.",
"operationId": "email_templates_update",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/emailTemplateID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template",
"required": [
"name",
"queue"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update email template",
"description": "Update part of an email template object.",
"operationId": "email_templates_partial_update",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/emailTemplateID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_template"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete email template",
"description": "Delete an email template object.",
"operationId": "email_templates_delete",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/emailTemplateID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/email_templates/{emailTemplateID}/render": {
"post": {
"summary": "Render email template",
"description": "The rendered email template can be requested via the render endpoint. \n\nInside the `to`, `cc` and `bcc` attributes template variables can be used instead of the email field of the email address object.\n",
"operationId": "email_templates_render",
"tags": [
"Email Template"
],
"parameters": [
{
"$ref": "#/components/parameters/emailTemplateID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/render_request"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/render_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/email_threads": {
"get": {
"summary": "List email threads",
"description": "Retrieve all email thread objects.",
"operationId": "email_threads_list",
"tags": [
"Email Thread"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/created_at_before"
},
{
"$ref": "#/components/parameters/created_at_after"
},
{
"$ref": "#/components/parameters/has_root_email"
},
{
"$ref": "#/components/parameters/has_replies"
},
{
"$ref": "#/components/parameters/has_new_replies"
},
{
"$ref": "#/components/parameters/last_email_created_at_before"
},
{
"$ref": "#/components/parameters/last_email_created_at_after"
},
{
"$ref": "#/components/parameters/recent_with_no_documents_not_replied"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"created_at",
"-created_at",
"last_email_created_at",
"-last_email_created_at",
"subject",
"-subject",
"from__email",
"-from__email",
"from__name",
"-from__name",
"queue",
"-queue"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_thread"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/email_threads/{emailThreadID}": {
"get": {
"summary": "Retrieve email thread",
"description": "Get an email thread object.",
"operationId": "email_threads_retrieve",
"tags": [
"Email Thread"
],
"parameters": [
{
"$ref": "#/components/parameters/emailThreadID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_thread"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update email thread",
"description": "Update email thread object.",
"operationId": "email_threads_update",
"tags": [
"Email Thread"
],
"parameters": [
{
"$ref": "#/components/parameters/emailThreadID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_thread",
"required": [
"has_new_replies"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_thread"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update email thread",
"description": "Update part of email thread object.",
"operationId": "email_threads_partial_update",
"tags": [
"Email Thread"
],
"parameters": [
{
"$ref": "#/components/parameters/emailThreadID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_thread"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/email_thread"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engine_fields": {
"post": {
"summary": "Create engine field",
"description": "Create a new engine field object.",
"operationId": "engine_fields_create",
"tags": [
"Engine Field"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field",
"required": [
"engine",
"name",
"label",
"type"
]
},
"examples": {
"create_engine_field": {
"description": "Example request to create a new engine field for vendor name.\n",
"value": {
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "vendor_name",
"label": "Vendor Name",
"type": "string",
"subtype": null,
"pre_trained_field_id": "sender_name",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field"
},
"examples": {
"created_engine_field": {
"description": "Response after successfully creating a new engine field.\n",
"value": {
"id": 10,
"url": "https://example.rossum.app/api/v1/engine_fields/10",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "vendor_name",
"label": "Vendor Name",
"type": "string",
"subtype": null,
"pre_trained_field_id": "sender_name",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List engine fields",
"description": "Retrieve all engine field objects.",
"operationId": "engine_fields_list",
"tags": [
"Engine Field"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/engine"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/used"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"engine",
"-engine",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/engine_field"
}
}
}
},
"examples": {
"engine_fields_list": {
"description": "Example response showing multiple engine fields for an invoice processing engine.\n",
"value": {
"pagination": {
"total": 15,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 3,
"url": "https://example.rossum.app/api/v1/engine_fields/3",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "document_id",
"label": "DocumentID",
"type": "string",
"subtype": "string",
"pre_trained_field_id": "document_id",
"tabular": false,
"multiline": "false"
},
{
"id": 4,
"url": "https://example.rossum.app/api/v1/engine_fields/4",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "amount_total",
"label": "Total Amount",
"type": "number",
"subtype": "amount",
"pre_trained_field_id": "amount_total",
"tabular": false,
"multiline": "false"
},
{
"id": 5,
"url": "https://example.rossum.app/api/v1/engine_fields/5",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "date_issue",
"label": "Issue Date",
"type": "date",
"subtype": null,
"pre_trained_field_id": "date_issue",
"tabular": false,
"multiline": "false"
}
]
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engine_fields/{engineFieldID}": {
"get": {
"summary": "Retrieve engine field",
"description": "Retrieve an engine field object.",
"operationId": "engine_fields_retrieve",
"tags": [
"Engine Field"
],
"parameters": [
{
"$ref": "#/components/parameters/engineFieldID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field"
},
"examples": {
"engine_field_response": {
"description": "Example response showing a document ID field configuration.\n",
"value": {
"id": 3,
"url": "https://example.rossum.app/api/v1/engine_fields/3",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "document_id",
"label": "DocumentID",
"type": "string",
"subtype": "string",
"pre_trained_field_id": "document_id",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update engine field",
"description": "Update engine field object.",
"operationId": "engine_fields_update",
"tags": [
"Engine Field"
],
"parameters": [
{
"$ref": "#/components/parameters/engineFieldID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field",
"required": [
"engine",
"name",
"label",
"type"
]
},
"examples": {
"update_engine_field": {
"description": "Example request to update an engine field's label and subtype.\n",
"value": {
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "document_id",
"label": "Invoice Number",
"type": "string",
"subtype": "alphanumeric",
"pre_trained_field_id": "document_id",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field"
},
"examples": {
"updated_engine_field": {
"description": "Response after successfully updating the engine field.\n",
"value": {
"id": 3,
"url": "https://example.rossum.app/api/v1/engine_fields/3",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "document_id",
"label": "Invoice Number",
"type": "string",
"subtype": "alphanumeric",
"pre_trained_field_id": "document_id",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update engine field",
"description": "Update part of an engine field object.",
"operationId": "engine_fields_partial_update",
"tags": [
"Engine Field"
],
"parameters": [
{
"$ref": "#/components/parameters/engineFieldID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field"
},
"examples": {
"partial_update_engine_field": {
"description": "Example request to update only the label of an engine field.\n",
"value": {
"label": "Invoice ID"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine_field"
},
"examples": {
"patched_engine_field": {
"description": "Response after successfully patching the engine field label.\n",
"value": {
"id": 3,
"url": "https://example.rossum.app/api/v1/engine_fields/3",
"engine": "https://example.rossum.app/api/v1/engines/8",
"name": "document_id",
"label": "Invoice ID",
"type": "string",
"subtype": "string",
"pre_trained_field_id": "document_id",
"tabular": false,
"multiline": "false"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete engine field",
"description": "Delete engine field object.",
"operationId": "engine_fields_delete",
"tags": [
"Engine Field"
],
"parameters": [
{
"$ref": "#/components/parameters/engineFieldID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engine_fields/pre_trained_fields": {
"get": {
"summary": "List pre-trained fields",
"description": "Get list of possible pre_trained_field_id fields that can be used when creating engine fields.\n\n| name | label | type | subtype | tabular | description |\n|------------------------------|----------------------------|--------|---------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| account_num | Bank Account | string | alphanumeric | False | Bank account number. Whitespaces are stripped. |\n| bank_num | Sort Code | string | alphanumeric | False | Sort code. Numerical code of the bank. |\n| iban | IBAN | string | iban | False | Bank account number in IBAN format. |\n| bic | BIC/SWIFT | string | alphanumeric | False | Bank BIC or SWIFT code. |\n| const_sym | Constant Symbol | string | alphanumeric | False | Statistical code on payment order. |\n| spec_sym | Specific Symbol | string | alphanumeric | False | Payee id on the payment order, or similar. |\n| var_sym | Variable symbol | string | numeric | False | In some countries used by the supplier to match the payment received against the invoice. Possible non-numeric characters are stripped. |\n| terms | Terms | string | | False | Payment terms as written on the document (e.g. \"45 days\", \"upon receipt\"). |\n| payment_method | Payment method | string | | False | Payment method defined on a document (e.g. 'Cheque', 'Pay order', 'Before delivery') |\n| customer_id | Customer Number | string | alphanumeric | False | The number by which the customer is registered in the system of the supplier. Whitespaces are stripped. |\n| date_due | Date Due | date | period_end | False | The due date of the invoice. |\n| date_issue | Issue Date | date | period_begin | False | Date of issue of the document. |\n| date_uzp | Tax Point Date | date | period_end | False | The date of taxable event. |\n| document_id | Document Identifier | string | alphanumeric | False | Document number. Whitespaces are stripped. |\n| order_id | Order Number | string | alphanumeric | False | Purchase order identification (Order Numbers not captured as \"sender_order_id\"). Whitespaces are stripped. |\n| recipient_address | Recipient Address | string | | False | Address of the customer. |\n| recipient_dic | Recipient Tax Number | string | vat_number | False | Tax identification number of the customer. Whitespaces are stripped. |\n| recipient_ic | Recipient Company ID | string | vat_number | False | Company identification number of the customer. Possible non-numeric characters are stripped. |\n| recipient_name | Recipient Name | string | | False | Name of the customer. |\n| recipient_vat_id | Recipient VAT Number | string | vat_number | False | Customer VAT Number |\n| recipient_delivery_name | Recipient Delivery Name | string | | False | Name of the recipient to whom the goods will be delivered. |\n| recipient_delivery_address | Recipient Delivery Address | string | | False | Address of the recipient where the goods will be delivered. |\n| sender_address | Supplier Address | string | | False | Address of the supplier. |\n| sender_dic | Supplier Tax Number | string | vat_number | False | Tax identification number of the supplier. Whitespaces are stripped. |\n| sender_ic | Supplier Company ID | string | vat_number | False | Business/organization identification number of the supplier. Possible non-numeric characters are stripped. |\n| sender_name | Supplier Name | string | | False | Name of the supplier. |\n| sender_vat_id | Supplier VAT Number | string | vat_number | False | VAT identification number of the supplier. |\n| sender_email | Supplier Email | string | | False | Email of the sender. |\n| sender_order_id | Supplier's Order ID | string | | False | Internal order ID in the suppliers system. |\n| delivery_note_id | Delivery Note ID | string | | False | Delivery note ID defined on the invoice. |\n| supply_place | Place of Supply | string | | False | Place of supply (the name of the city or state where the goods will be supplied). |\n| currency | Currency | enum | | False | The currency which the invoice is to be paid in. Possible values: CZK, DKK, EUR, GBP, NOK, SEK, HUF, USD, AUD, INR, CHF, CNY, JPY, PLN, RON, RUB or other. May be also in lowercase. |\n| document_type | Document Type | enum | | False | Possible values: credit_note, debit_note, tax_invoice (most typical), proforma, receipt, delivery_note, order or other. |\n| language | Language | enum | | False | The language which the document was written in. Values are ISO 639-3 language codes, e.g.: eng, fra, deu, zho. See Languages Supported By Rossum |\n| payment_method_type | Payment Method Type | enum | | False | Payment method used for the transaction. Possible values: card, cash. |\n| amount_due | Amount Due | number | amount | False | Final amount including tax to be paid after deducting all discounts and advances. |\n| amount_rounding | Amount Rounding | number | amount | False | Remainder after rounding amount_total. |\n| amount_total | Total Amount | number | amount | False | Subtotal over all items, including tax. |\n| amount_paid | Amount paid | number | amount | False | Amount paid already. |\n| amount_total_base | Tax Base Total | number | amount | False | Base amount for tax calculation. |\n| amount_total_tax | Tax Total | number | amount | False | Total tax amount. |\n| tax_detail_base | Tax Base | number | amount | True | Sum of tax bases for items with the same tax rate. |\n| tax_detail_rate | Tax Rate | number | rate | True | One of the tax rates in the tax breakdown. |\n| tax_detail_tax | Tax Amount | number | amount | True | Sum of taxes for items with the same tax rate. |\n| tax_detail_total | Tax Total | number | amount | True | Total amount including tax for all items with the same tax rate. |\n| tax_detail_code | Tax Code | string | alphanumeric | True | Text on document describing tax code of the tax rate (e.g. 'GST', 'CGST', 'DPH', 'TVA'). If multiple tax rates belong to one tax code on the document, the tax code will be assigned only to the first tax rate. (in future such tax code will be distributed to all matching tax rates.) |\n| table_column_code | Item Code/ID | string | alphanumeric | True | Can be the SKU, EAN, a custom code (string of letters/numbers) or even just the line number. |\n| table_column_description | Item Description | string | | True | Line item description. Can be multi-line with details. |\n| table_column_quantity | Item Quantity | number | | True | Quantity of the item. |\n| table_column_uom | Item Unit of Measure | string | | True | Unit of measure of the item (kg, container, piece, gallon, ...). |\n| table_column_rate | Item Rate | number | rate | True | Tax rate for the line item. |\n| table_column_tax | Item Tax | number | amount | True | Tax amount for the line. Rule of thumb: tax = rate * amount_base. |\n| table_column_amount_base | Amount Base | number | amount | True | Unit price without tax. (This is the primary unit price extracted.) |\n| table_column_amount | Amount | number | amount | True | Unit price with tax. Rule of thumb: amount = amount_base + tax. |\n| table_column_amount_total_base | Amount Total Base | number | amount | True | The total amount to be paid for all the items excluding the tax. Rule of thumb: amount_total_base = amount_base * quantity. |\n| table_column_amount_total | Amount Total | number | amount | True | The total amount to be paid for all the items including the tax. Rule of thumb: amount_total = amount * quantity. |\n| table_column_other | Other | string | | True | Unrecognized data type. |\n| barcode_qrcode | QR Code | string | | False | |\n| barcode_ean2 | EAN-2 | string | | False | |\n| barcode_ean5 | EAN-5 | string | | False | |\n| barcode_ean8 | EAN-8 | string | | False | |\n| barcode_ean13 | EAN-13 | string | | False | |\n| barcode_code39 | Code 39 | string | | False | |\n| barcode_code93 | Code 93 | string | | False | |\n| barcode_code128 | Code 128 | string | | False | |\n| barcode_isbn10 | ISBN-10 | string | | False | |\n| barcode_isbn13 | ISBN-13 | string | | False | |\n| barcode_upca | UPC-A | string | | False | |\n| barcode_upce | UPC-E | string | | False | |\n| barcode_databar | DataBar | string | | False | |\n| barcode_databar_exp | DataBar Expanded | string | | False | |\n| barcode_codabar | Codabar | string | | False | |\n| barcode_pdf417 | PDF417 | string | | False | |\n| barcode_sqcode | SQCode | string | | False | |\n| barcode_i25 | Interleaved 2 of 5 | string | | False | |\n",
"operationId": "engine_fields_pre_trained_fields",
"tags": [
"Engine Field"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/pre_trained_field"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engines": {
"post": {
"summary": "Create engine",
"description": "Create a new engine object.",
"operationId": "engines_create",
"tags": [
"Engine"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine",
"required": [
"name",
"type"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List engines",
"description": "Retrieve all engine objects.",
"operationId": "engines_list",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/engine_type"
},
{
"$ref": "#/components/parameters/agenda_id"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"type",
"-type",
"agenda_id",
"-agenda_id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/engine"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engines/{engineID}": {
"get": {
"summary": "Retrieve engine",
"description": "Retrieve an engine object.",
"operationId": "engines_retrieve",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update engine",
"description": "Update engine object.",
"operationId": "engines_update",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine",
"required": [
"name",
"type",
"organization"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update engine",
"description": "Update part of an engine object.",
"operationId": "engines_partial_update",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete engine",
"description": "Delete engine object. Only engines without any attached queues can be deleted.",
"operationId": "engines_delete",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engines/{engineID}/check_template_compatibility": {
"post": {
"summary": "Check engine template schema compatibility",
"description": "This endpoint checks whether the schema on the queue of the template organization whose name is provided in the request body is compatible with this engine. See available templates in [organization](/api/organization#create-organization).\n",
"operationId": "engines_check_template_compatibility",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/template_compatibility_request"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/template_compatibility_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engines/{engineID}/duplicate": {
"post": {
"summary": "Duplicate engine",
"description": "This endpoint duplicates an existing engine configuration. You must specify name for the new engine. \nAll the other attributes (and also engine fields) would be duplicated (except for `agenda_id` which will be generated).\n",
"operationId": "engines_duplicate",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/duplicate_request"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/engines/{engineID}/queue_stats": {
"get": {
"summary": "Retrieve engine queue statistics",
"description": "Get queue statistics for an engine. Related queues may be sideloaded.\n",
"operationId": "engines_queue_stats",
"tags": [
"Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/engineID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "sideload",
"in": "query",
"description": "Sideload related objects",
"required": false,
"schema": {
"type": "string",
"enum": [
"queues"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/queue_stats"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/generic_engines": {
"get": {
"summary": "List generic engines",
"description": "Retrieve all generic engine objects.\n",
"operationId": "generic_engines_list",
"tags": [
"Generic Engine"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/generic_engine"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/generic_engines/{genericEngineID}": {
"parameters": [
{
"$ref": "#/components/parameters/genericEngineID"
}
],
"get": {
"summary": "Retrieve generic engine",
"description": "Get a generic engine object.",
"operationId": "generic_engines_retrieve",
"tags": [
"Generic Engine"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/generic_engine"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/generic_engine_schemas": {
"get": {
"summary": "List generic engine schemas",
"description": "Retrieve all generic engine schema objects.\n\n**Internal API Warning**: Please note that Generic Engine Schema is an internal API and can be changed without notice.\n",
"operationId": "generic_engine_schemas_list",
"tags": [
"Generic Engine Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/generic_engine_schema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/generic_engine_schemas/{genericEngineSchemaID}": {
"get": {
"summary": "Retrieve generic engine schema",
"description": "Get a generic engine schema object.\n\n**Internal API Warning**: Please note that Generic Engine Schema is an internal API and can be changed without notice.\n",
"operationId": "generic_engine_schemas_retrieve",
"tags": [
"Generic Engine Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/genericEngineSchemaID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/generic_engine_schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks": {
"post": {
"summary": "Create hook",
"description": "Create a new hook object.",
"operationId": "hooks_create",
"tags": [
"Hook"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_w_required"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List hooks",
"description": "Retrieve all hook objects.",
"operationId": "hooks_list",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/hook_type"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/active"
},
{
"$ref": "#/components/parameters/config_url"
},
{
"$ref": "#/components/parameters/config_app_url"
},
{
"$ref": "#/components/parameters/extension_source"
},
{
"$ref": "#/components/parameters/events"
},
{
"$ref": "#/components/parameters/search-2"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"type",
"-type",
"active",
"-active",
"config_url",
"-config_url",
"config_app_url",
"-config_app_url",
"events",
"-events"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hook"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}": {
"get": {
"summary": "Retrieve hook",
"description": "Get a hook object.",
"operationId": "hooks_retrieve",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update hook",
"description": "Update hook object.",
"operationId": "hooks_update",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_w_required"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update hook",
"description": "Update part of hook object.",
"operationId": "hooks_partial_update",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete hook",
"description": "Delete hook object.",
"operationId": "hooks_delete",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/create": {
"post": {
"summary": "Create hook from template",
"description": "Create a new hook object with the option to use a referenced hook template as a base.",
"operationId": "hooks_create_from_template",
"tags": [
"Hook"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_w_required"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}/duplicate": {
"post": {
"summary": "Duplicate hook",
"description": "Duplicate a hook object.\n`hook.queues` is not copied by default, but can be copied using the `copy_queues` option. Duplicated hook is always inactive (`hook.active = False`).\n",
"operationId": "hooks_duplicate",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the duplicated hook."
},
"copy_secrets": {
"type": "boolean",
"default": false,
"description": "Whether to copy secrets."
},
"copy_dependencies": {
"type": "boolean",
"default": false,
"description": "Whether to copy dependencies. If enabled, this option copies the dependency relations of the original hook.\nIt duplicates the `run_after` references to preserve which hooks the original hook depended on, and it also\nupdates all hooks that previously depended on the original hook to reference the new duplicated one. This\nensures that both dependency directions—\"runs after\" and \"is run after by\"—are correctly maintained.\n"
},
"copy_queues": {
"type": "boolean",
"default": false,
"description": "Whether to copy queue assignments from the original hook to the duplicated hook."
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}/generate_payload": {
"post": {
"summary": "Generate hook payload",
"description": "Users can use this endpoint to test the hook on a payload of specific events and actions.\n\nThe token used for calling the endpoint is returned as `rossum_authorization_token` regardless of the `token_owner` of the hook.\nValues in `secrets` are redacted for security reasons. The payload for email events from this endpoint may differ from the original hook payload in the file ids, height, width, and format of email addresses in headers.\n",
"operationId": "hooks_generate_payload",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "Hook's [action](/guides/extensions#webhook-extension).",
"example": "scheduled"
},
"event": {
"type": "string",
"description": "Hook's [event](/guides/extensions#webhook-extension).",
"example": "invocation"
},
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of related Annotation object. Required for annotation_status and annotation_content events.",
"example": "https://example.rossum.app/api/v1/annotations/1"
},
"previous_status": {
"type": "string",
"description": "A previous status of the document. See [Annotation Lifecycle](/guides/annotation-lifecycle) for a list of supported values. Required for annotation_status and annotation_content events.",
"example": "to_review"
},
"status": {
"type": "string",
"description": "Status of the document. See [Annotation Lifecycle](/guides/annotation-lifecycle) for a list of supported values. Required for annotation_status and annotation_content events.",
"example": "confirmed"
},
"email": {
"allOf": [
{
"$ref": "#/components/schemas/email_url"
},
{
"description": "URL of the arriving email. Required for email event."
}
]
},
"upload": {
"type": "string",
"format": "uri",
"description": "URL of an upload instance. Required for upload event.",
"example": "https://example.rossum.app/api/v1/uploads/1"
}
},
"required": [
"action",
"event"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Hook payload for specific event and action.",
"properties": {
"request_id": {
"type": "string",
"description": "Request ID.",
"example": "ae7bc8dd-73bd-489b-a3d2-f5514b209591"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp.",
"example": "2020-01-01T00:00:00.000000Z"
},
"base_url": {
"type": "string",
"format": "uri",
"description": "Base URL.",
"example": "https://example.rossum.app"
},
"rossum_authorization_token": {
"type": "string",
"description": "Authorization token.",
"example": "1024873d424a007d8eebff7b3684d283abdf7d0d"
},
"hook": {
"type": "string",
"format": "uri",
"description": "Hook URL.",
"example": "https://example.rossum.app/api/v1/hooks/1500"
},
"settings": {
"type": "object",
"description": "Hook settings.",
"example": {
"example_target_service_type": "SFTP",
"example_target_hostname": "sftp.elis.rossum.ai"
}
},
"secrets": {
"type": "object",
"description": "Hook secrets (values redacted).",
"example": {
"username": "[redacted...]",
"password": "[redacted...]"
}
},
"action": {
"type": "string",
"description": "Action.",
"example": "scheduled"
},
"event": {
"type": "string",
"description": "Event.",
"example": "invocation"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}/secrets_keys": {
"get": {
"summary": "Retrieve secret keys list",
"description": "Retrieve all secrets in a list (only keys are retrieved, values are encrypted in DB and aren't possible to obtain via API).",
"operationId": "hooks_secrets_keys_list",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of hook secrets keys.",
"example": [
"secret_key1",
"secret_key2"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}/test": {
"post": {
"summary": "Test hook",
"description": "Test a hook with custom payload. Test endpoint will return result generated by the specified Hook which would be normally processed by Rossum.",
"operationId": "hooks_test",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"config": {
"type": "object",
"description": "You can override default [configuration](/api/hook) of hook being executed. The `runtime` attribute is required for function hook if custom config is set.",
"example": {
"insecure_ssl": true,
"code": "exports.rossum_hook_request_handler = ..."
}
},
"payload": {
"type": "object",
"description": "Payload sent to the Hook, please note only [supported](/guides/extensions#webhook-extension) combination of `action` and `event` can be passed.",
"example": {
"action": "started",
"event": "annotation_content",
"annotation": {},
"document": {},
"settings": {}
}
}
},
"required": [
"payload"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "object",
"description": "Response from the hook.",
"example": {
"messages": [],
"operations": []
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"description": "Conflict - Test function is not ready yet, request should be retried after 10 seconds.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"example": "Test function is not ready yet"
}
}
}
}
}
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/{hookID}/invoke": {
"post": {
"summary": "Trigger manual hook",
"description": "Invoke the hook with custom payload. The payload will be added to the standard `invocation` event hook request and sent to the hook. The hook response is returned in the invocation response payload.\n\n\nValues for standard json hook response attributes (`request_id`, `action`, ...) will NOT be overwritten.\n\n\n\nAttribute `timeout_s` in hook `config` for this endpoint `POST /v1/hooks/{id}/invoke` will be overwritten by default value of 30.\n\n",
"operationId": "hooks_invoke",
"tags": [
"Hook"
],
"parameters": [
{
"$ref": "#/components/parameters/hookID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Object with properties to be merged into the invocation payload.",
"example": {
"SAP_ID": "1234",
"DB_COLUMN": "SAP"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Hook response merged with invocation response payload."
}
}
}
},
"400": {
"description": "Bad Request - Not having proper event and action in hook object or non-json response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"example": "Hook must have proper event and action configuration"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/runs": {
"get": {
"summary": "List hook runs",
"description": "List recent hook runs with optional filters and pagination.\n\nThe logs are sorted by the `start` timestamp in descending order.\n\nThe retention policy for the logs is set to 7 days.\n",
"operationId": "hooks_runs_list",
"tags": [
"Hook Run"
],
"parameters": [
{
"$ref": "#/components/parameters/request_id"
},
{
"$ref": "#/components/parameters/uuid"
},
{
"$ref": "#/components/parameters/hook"
},
{
"$ref": "#/components/parameters/timestamp_before-2"
},
{
"$ref": "#/components/parameters/timestamp_after-2"
},
{
"$ref": "#/components/parameters/start_before"
},
{
"$ref": "#/components/parameters/start_after"
},
{
"$ref": "#/components/parameters/status-2"
},
{
"$ref": "#/components/parameters/status_code"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/email-2"
},
{
"$ref": "#/components/parameters/search-3"
},
{
"$ref": "#/components/parameters/page_size-2"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_logs_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/runs/{runUuid}/logs": {
"get": {
"summary": "List hook run logs",
"description": "List progress logs related to the specific hook run. The logs are sorted by the `timestamp` in ascending order.\n",
"operationId": "hooks_runs_logs_list",
"tags": [
"Hook Run"
],
"parameters": [
{
"$ref": "#/components/parameters/runUuid"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the log entry.",
"example": "2023-09-23T12:00:00.000000Z"
},
"details": {
"type": "string",
"description": "Log details.",
"example": "Master Hub data update started"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hooks/logs": {
"get": {
"summary": "List hook call logs",
"deprecated": true,
"description": "**⚠️ Deprecated**: Use [List hook runs](#tag/Hook-Run/operation/hooks_runs_list) instead.\n\nList all the logs from all running hooks with optional filters and pagination.\n\nThe logs are sorted by the `start` timestamp in descending order.\n",
"operationId": "hooks_logs_list",
"tags": [
"Hook Run"
],
"parameters": [
{
"$ref": "#/components/parameters/request_id"
},
{
"$ref": "#/components/parameters/log_level"
},
{
"$ref": "#/components/parameters/hook"
},
{
"$ref": "#/components/parameters/timestamp_before-2"
},
{
"$ref": "#/components/parameters/timestamp_after-2"
},
{
"$ref": "#/components/parameters/start_before"
},
{
"$ref": "#/components/parameters/start_after"
},
{
"$ref": "#/components/parameters/status-2"
},
{
"$ref": "#/components/parameters/status_code"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/email-2"
},
{
"$ref": "#/components/parameters/search-3"
},
{
"$ref": "#/components/parameters/page_size-2"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_logs_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hook_templates": {
"get": {
"summary": "List hook templates",
"description": "Retrieve all hook template objects.",
"operationId": "list-hook-templates",
"tags": [
"Hook Template"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"order",
"-order"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hook_template"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/hook_templates/{hookTemplateID}": {
"get": {
"summary": "Retrieve hook template",
"description": "Get a hook template object.",
"operationId": "retrieve-hook-template",
"tags": [
"Hook Template"
],
"parameters": [
{
"$ref": "#/components/parameters/hookTemplateID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hook_template"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/inboxes": {
"post": {
"summary": "Create inbox",
"description": "Create a new inbox object.\n",
"operationId": "inboxes_create",
"tags": [
"Inbox"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox",
"required": [
"name",
"email_prefix",
"queues"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List inboxes",
"description": "Retrieve all inbox objects.\n",
"operationId": "inboxes_list",
"tags": [
"Inbox"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/inbox_email_address"
},
{
"$ref": "#/components/parameters/email_prefix"
},
{
"$ref": "#/components/parameters/bounce_email_to"
},
{
"$ref": "#/components/parameters/bounce_unprocessable_attachments"
},
{
"$ref": "#/components/parameters/bounce_postponed_annotations"
},
{
"$ref": "#/components/parameters/bounce_deleted_annotations"
},
{
"$ref": "#/components/parameters/bounce_email_with_no_attachments"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"email",
"-email",
"email_prefix",
"-email_prefix",
"bounce_email_to",
"-bounce_email_to"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/inbox"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/inboxes/{inboxID}": {
"get": {
"summary": "Retrieve inbox",
"description": "Get an inbox object.\n",
"operationId": "inboxes_retrieve",
"tags": [
"Inbox"
],
"parameters": [
{
"$ref": "#/components/parameters/inboxID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update inbox",
"description": "Update inbox object.\n",
"operationId": "inboxes_update",
"tags": [
"Inbox"
],
"parameters": [
{
"$ref": "#/components/parameters/inboxID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox",
"required": [
"name",
"email_prefix",
"queues"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update inbox",
"description": "Update a part of inbox object.\n",
"operationId": "inboxes_partial_update",
"tags": [
"Inbox"
],
"parameters": [
{
"$ref": "#/components/parameters/inboxID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbox"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete inbox",
"description": "Delete inbox object.\n",
"operationId": "inboxes_delete",
"tags": [
"Inbox"
],
"parameters": [
{
"$ref": "#/components/parameters/inboxID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/labels": {
"post": {
"summary": "Create label",
"description": "Create a new label object.",
"operationId": "labels_create",
"tags": [
"Label"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label",
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List labels",
"description": "List all label objects.",
"operationId": "labels_list",
"tags": [
"Label"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/label"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/labels/{labelID}": {
"get": {
"summary": "Retrieve label",
"description": "Retrieve a label object.",
"operationId": "labels_retrieve",
"tags": [
"Label"
],
"parameters": [
{
"$ref": "#/components/parameters/labelID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update label",
"description": "Update label object.",
"operationId": "labels_update",
"tags": [
"Label"
],
"parameters": [
{
"$ref": "#/components/parameters/labelID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label",
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update label",
"description": "Update part of label object.",
"operationId": "labels_partial_update",
"tags": [
"Label"
],
"parameters": [
{
"$ref": "#/components/parameters/labelID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete label",
"description": "Delete label object.",
"operationId": "labels_delete",
"tags": [
"Label"
],
"parameters": [
{
"$ref": "#/components/parameters/labelID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/labels/apply": {
"post": {
"summary": "Add/remove annotation labels",
"description": "Add/Remove labels on annotations.",
"operationId": "labels_apply",
"tags": [
"Label"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/apply_request"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/memberships": {
"post": {
"summary": "Create membership",
"description": "Create a membership object.",
"operationId": "memberships_create",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership",
"required": [
"user",
"organization"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List memberships",
"description": "Retrieve all membership objects.",
"operationId": "memberships_list",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/user"
},
{
"$ref": "#/components/parameters/organization"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/membership"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/memberships/{membershipID}": {
"get": {
"summary": "Retrieve membership",
"description": "Get a membership object.",
"operationId": "memberships_retrieve",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/membershipID"
},
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update membership",
"description": "Update a membership object.",
"operationId": "memberships_update",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/membershipID"
},
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership",
"required": [
"user",
"organization"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update membership",
"description": "Update a part of membership object.",
"operationId": "memberships_partial_update",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/membershipID"
},
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete membership",
"description": "Delete a membership object.",
"operationId": "memberships_delete",
"tags": [
"Membership"
],
"parameters": [
{
"$ref": "#/components/parameters/membershipID"
},
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations": {
"get": {
"summary": "List organizations",
"description": "Retrieve all organization objects.\n",
"operationId": "organizations_list",
"tags": [
"Organization"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/0"
},
{
"$ref": "#/components/parameters/1"
},
{
"$ref": "#/components/parameters/2"
},
{
"name": "include_membership_organizations",
"in": "query",
"description": "Include organizations that user is either in or is connected to through membership.",
"schema": {
"type": "boolean",
"default": false
},
"example": true
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/organization"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"get": {
"summary": "Retrieve organization",
"description": "Get an organization object.\n",
"operationId": "organizations_retrieve",
"tags": [
"Organization"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update organization",
"description": "Update organization object. Writable fields are `ui_settings`, `metadata`, and `settings`; all other fields are read-only.",
"operationId": "organizations_update",
"tags": [
"Organization"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update organization",
"description": "Update part of organization object. Writable fields are `ui_settings`, `metadata`, and `settings`; all other fields are read-only.",
"operationId": "organizations_partial_update",
"tags": [
"Organization"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/create": {
"post": {
"summary": "Create organization",
"description": "Create new organization and related objects (workspace, queue, user, schema, inbox, domain).\n\nYou need a `create_key` in order to create an organization. Please contact [support@rossum.ai](mailto:support@rossum.ai) to obtain one.\n\nSelected `template_name` affects default schema and extracted fields. Please note that the demo templates may be updated as new features are introduced.\n\nList of available templates:\n\n| Template name | Description | Is demo |\n|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------|\n| Empty Organization Template | Empty organization, suitable for further customization | no |\n| CZ Demo Template | Czech standard invoices | yes |\n| Tax Invoice EU Demo Template | VAT Invoices, Credit Notes, Debit Notes, Purchase/Sales Orders, Receipts, and Pro Formas coming from the EU | yes |\n| Tax Invoice US Demo Template | Tax Invoices, Credit Notes, Debit Notes, Purchase/Sales Orders, Receipts, and Pro Formas coming from the US | yes |\n| Tax Invoice UK Demo Template | VAT Invoices, Credit Notes, Debit Notes, Purchase/Sales Orders, Receipts, and Pro Formas coming from the UK, India, Canada, or Australia | yes |\n| Delivery Note Demo Template | Delivery Notes | yes |\n| Tax Invoice CN Demo Template | governmental Tax Invoices from Mainland China (fapiaos) | yes |\n| Certificates of Analysis Demo Template | Certificates of Analysis that are quality control documents common in the food and beverage industry | yes |\n",
"operationId": "organizations_create",
"tags": [
"Organization"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organizations_create"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"organization",
"key",
"domain",
"code"
],
"properties": {
"organization": {
"$ref": "#/components/schemas/organization"
},
"key": {
"type": "string",
"description": "Authentication token for the newly created user.",
"example": "e7c4ddd996d8e92bdf780b9f0dfe8e4cd17f0c6e"
},
"domain": {
"type": "string",
"description": "Domain of the newly created organization.",
"example": "example.rossum.app"
},
"code": {
"type": "string",
"description": "One-time login token for the newly created user.",
"example": "abc123def456"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/billing_history/export": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"get": {
"summary": "Export organization billing history",
"description": "Download the data provided by the billing history response resource in a CSV output.\n",
"operationId": "organizations_billing_history_export",
"tags": [
"Organization"
],
"responses": {
"200": {
"description": "OK - CSV file download",
"content": {
"text/csv": {
"schema": {
"type": "string",
"description": "CSV file containing billing history data.",
"example": "begin_date,end_date,purchased_pages,billable_pages,non_billable_pages,purchased_documents,billable_documents,non_billable_documents,extracted_pages_with_learning,extracted_pages_without_learning,split_pages_with_learning,split_pages_without_learning,extracted_documents_with_learning,extracted_documents_without_learning,split_documents_with_learning,split_documents_without_learning,ocr_only_pages,ocr_only_documents,purchased_extracted_pages_with_learning,purchased_extracted_pages_without_learning,purchased_split_pages_with_learning,purchased_split_pages_without_learning,purchased_extracted_documents_with_learning,purchased_extracted_documents_without_learning,purchased_split_documents_with_learning,purchased_split_documents_without_learning,purchased_ocr_only_pages,purchased_ocr_only_documents\n2021-01-01,2022-12-31,555,34735,100,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0\n"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/billing_stats/export": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"post": {
"summary": "Export organization billing stats",
"description": "Download the data provided by the billing stats response resource in a CSV output.\n",
"operationId": "organizations_billing_stats_export",
"tags": [
"Organization"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"$ref": "#/components/schemas/billing_filters_base"
},
"group_by": {
"$ref": "#/components/schemas/group_by_base"
}
}
},
"examples": {
"billing_stats_export_request": {
"description": "Request to export billing statistics for a specific queue over a fiscal year period, grouped by month.\n",
"value": {
"filters": {
"queues": [
"https://example.rossum.app/api/v1/queues/12345"
],
"begin_date": "2021-10-01",
"end_date": "2022-09-30"
},
"group_by": [
"month"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK - CSV file download",
"content": {
"text/csv": {
"schema": {
"type": "string",
"description": "CSV file containing billing stats data.",
"example": "begin_date,end_date,billable_pages,non_billable_pages,billable_documents,non_billable_documents\n2021-10-01,2021-10-31,27,0,32,0\n2021-11-01,2021-11-30,159,0,147,9\n"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/membership_token": {
"post": {
"summary": "Generate organization token",
"description": "Generate token for access to membership and primary organizations. If the user is a group administrator, token can be generated for any organization in his organization group.\n",
"operationId": "auth_membership_token",
"tags": [
"Organization"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"organization"
],
"properties": {
"organization": {
"type": "string",
"format": "uri",
"description": "URL to the organization to which the token will have access.",
"example": "https://example.rossum.app/api/v1/organizations/406"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Authorization token belonging to requested organization.",
"example": "b6dde6e6280c697bc4afac7f920c5cee8c9c9t7d"
},
"organization": {
"type": "string",
"format": "uri",
"description": "Organization URL.",
"example": "https://example.rossum.app/api/v1/organizations/406"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/billing": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"post": {
"summary": "Retrieve organization billing (deprecated)",
"description": "In order to obtain an overview of the billed items, you can get basic billing statistics.\n\n\nThis endpoint is deprecated in favor of billing stats for organization and may return inaccurate results.\n\n\n\nPlease note that data are accurate starting on June 1st 2021.\n\n",
"operationId": "organizations_billing",
"deprecated": true,
"tags": [
"Organization"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"description": "Filters used for the computation of billed items counts.",
"properties": {
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Filter billed items for the specified queues to be counted to the report.",
"example": [
"https://example.rossum.app/api/v1/queues/8199"
]
},
"begin_date": {
"type": "string",
"format": "date",
"description": "Filter billed items that was issued **since** the specified date.",
"example": "2021-08-01"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Filter billed items that was issued **up to** the specified date.",
"example": "2021-08-31"
}
}
},
"group_by": {
"type": "array",
"items": {
"type": "string",
"enum": [
"queue"
]
},
"description": "List of attributes by which the `series` is to be grouped.",
"example": [
"queue"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"series": {
"type": "array",
"description": "Series contain information grouped by fields defined in group_by. Only grouping by queue is allowed.\nThe data are wrapped in values object, and accompanied by the values of attributes that were used for grouping.\n",
"items": {
"type": "object",
"properties": {
"begin_date": {
"type": "string",
"format": "date",
"description": "Start date of the documents with billed items within the group.",
"example": "2019-02-01"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Final date of the documents with billed items within the group.",
"example": "2019-02-01"
},
"queue": {
"type": "string",
"format": "uri",
"description": "Queue of billed pages or documents.",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"values": {
"type": "object",
"description": "Contains the data of totals list grouped by queue and date.",
"properties": {
"header_fields_per_page": {
"type": "integer",
"description": "Number of pages that were processed by Rossum AI Engine and where only header fields were supposed to be captured.",
"example": 2
},
"header_fields_per_document": {
"type": "integer",
"description": "Number of documents that were processed by Rossum AI Engine and where only header fields were supposed to be captured.",
"example": 5
},
"header_fields_and_line_items_per_page": {
"type": "integer",
"description": "Number of pages that were processed by Rossum AI Engine and where line item fields were supposed to be captured.",
"example": 9
},
"header_fields_and_line_items_per_document": {
"type": "integer",
"description": "Number of documents that were processed by Rossum AI Engine and where line item fields were supposed to be captured.",
"example": 20
}
}
}
}
}
},
"totals": {
"type": "object",
"description": "Summary information for the whole period (between begin_date and end_date).",
"properties": {
"header_fields_per_page": {
"type": "integer",
"description": "Number of pages that were processed by Rossum AI Engine and where only header fields were supposed to be captured.",
"example": 8
},
"header_fields_per_document": {
"type": "integer",
"description": "Number of documents that were processed by Rossum AI Engine and where only header fields were supposed to be captured.",
"example": 16
},
"header_fields_and_line_items_per_page": {
"type": "integer",
"description": "Number of pages that were processed by Rossum AI Engine and where line item fields were supposed to be captured.",
"example": 20
},
"header_fields_and_line_items_per_document": {
"type": "integer",
"description": "Number of documents that were processed by Rossum AI Engine and where line item fields were supposed to be captured.",
"example": 43
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/billing_history": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"get": {
"summary": "Retrieve organization billing history",
"description": "Retrieve billing history with entries corresponding to individual contracted periods. The value `purchased_documents` or `purchased_pages` define the period billing unit.\n",
"operationId": "organizations_billing_history",
"tags": [
"Organization"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/billing_period"
},
{
"type": "object",
"properties": {
"values": {
"$ref": "#/components/schemas/billing_history_values"
}
}
}
]
}
},
"totals": {
"$ref": "#/components/schemas/billing_history_totals"
},
"updated_at": {
"type": "string",
"format": "date",
"description": "Date when the billing history was last updated.",
"example": "2022-09-01"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/billing_stats": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
],
"post": {
"summary": "Retrieve organization billing stats",
"description": "In order to obtain an overview of the billed items, you can get basic billing statistics.\n\nThe billing unit (pages or documents) is defined in the contract.\n\n",
"operationId": "organizations_billing_stats",
"tags": [
"Organization"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"$ref": "#/components/schemas/billing_filters_base"
},
"group_by": {
"$ref": "#/components/schemas/group_by_base"
},
"order_by": {
"$ref": "#/components/schemas/order_by"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/billing_period"
},
{
"type": "object",
"properties": {
"organization": {
"type": "string",
"format": "uri",
"description": "Billed pages or documents Organization.",
"example": "https://example.rossum.app/api/v1/organizations/406"
},
"queue": {
"type": "string",
"format": "uri",
"description": "Billed pages or documents Queue.",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"values": {
"type": "object",
"description": "Contains the data of totals list grouped by the group_by.",
"properties": {
"billable_documents": {
"type": "integer",
"description": "Number of documents billed.",
"example": 13
},
"billable_pages": {
"type": "integer",
"description": "Number of pages billed.",
"example": 7
},
"non_billable_documents": {
"type": "integer",
"description": "Number of documents that were received but not billed.",
"example": 0
},
"non_billable_pages": {
"type": "integer",
"description": "Number of pages that were received but not billed.",
"example": 0
}
}
}
}
}
]
}
},
"totals": {
"type": "object",
"description": "Summary information for the whole period (between begin_date and end_date).",
"properties": {
"billable_documents": {
"type": "integer",
"description": "Number of documents billed.",
"example": 21288
},
"billable_pages": {
"type": "integer",
"description": "Number of pages billed.",
"example": 30204
},
"non_billable_documents": {
"type": "integer",
"description": "Number of documents that were received but not billed.",
"example": 81
},
"non_billable_pages": {
"type": "integer",
"description": "Number of pages that were received but not billed.",
"example": 5649
}
}
},
"updated_at": {
"type": "string",
"format": "date",
"description": "Date when the billing stats were last updated.",
"example": "2022-09-01"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organizations/{organizationID}/limits": {
"parameters": [
{
"$ref": "#/components/parameters/organizationID"
}
]
},
"/api/v1/organization_groups": {
"get": {
"summary": "List organization groups",
"description": "Retrieve all organization group objects. Typically, there would only be one result.",
"operationId": "organization_groups_list",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/organization_group"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}": {
"get": {
"summary": "Retrieve organization group",
"description": "Get an organization group object.",
"operationId": "organization_groups_retrieve",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization_group"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/billing_history/export": {
"get": {
"summary": "Export organization group billing history",
"description": "Download the data provided by the billing history response resource in a CSV output.\n",
"operationId": "organization_groups_billing_history_export",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"text/csv": {
"schema": {
"type": "string",
"example": "begin_date,end_date,purchased_pages,billable_pages,non_billable_pages,purchased_documents,billable_documents,non_billable_documents,extracted_pages_with_learning,extracted_pages_without_learning,split_pages_with_learning,split_pages_without_learning,extracted_documents_with_learning,extracted_documents_without_learning,split_documents_with_learning,split_documents_without_learning,ocr_only_pages,ocr_only_documents,purchased_extracted_pages_with_learning,purchased_extracted_pages_without_learning,purchased_split_pages_with_learning,purchased_split_pages_without_learning,purchased_extracted_documents_with_learning,purchased_extracted_documents_without_learning,purchased_split_documents_with_learning,purchased_split_documents_without_learning,purchased_ocr_only_pages,purchased_ocr_only_documents\n2021-01-01,2022-12-31,555,34735,100,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0\n2020-01-01,2021-12-31,0,0,0,111,10209,123,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0\n"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/billing_stats/export": {
"post": {
"summary": "Export organization group billing stats",
"description": "Download the data provided by the billing stats response resource in a CSV output.\n",
"operationId": "organization_groups_billing_stats_export",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"$ref": "#/components/schemas/billing_filters_org_group"
},
"group_by": {
"$ref": "#/components/schemas/group_by_stats_group"
},
"order_by": {
"$ref": "#/components/schemas/order_by"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"text/csv": {
"schema": {
"type": "string",
"example": "begin_date,end_date,billable_pages,non_billable_pages,billable_documents,non_billable_documents\n2021-10-01,2021-10-31,27,0,32,0\n2021-11-01,2021-11-30,159,0,147,9\n2021-12-01,2021-12-31,41,0,20,0\n"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/organizations": {
"get": {
"summary": "List organization group organizations",
"description": "Get organizations for an organization group object. Returned objects contain subset of organization attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_organizations_list",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/membership_organization"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/queues": {
"get": {
"summary": "List organization group queues",
"description": "Get queues for an organization group object. Returned objects contain subset of queue attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_queues_list",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "organization",
"in": "query",
"description": "Filter queues by organization",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/membership_queue"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/users": {
"get": {
"summary": "List organization group users",
"description": "Get users for an organization group object. Returned objects contain subset of user attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_users_list",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/membership_user"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/workspaces": {
"get": {
"summary": "List organization group workspaces",
"description": "Get workspaces for an organization group object. Returned objects contain subset of workspace attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_workspaces_list",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "organization",
"in": "query",
"description": "Filter workspaces by organization",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/membership_workspace"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/organizations/{organizationID}": {
"get": {
"summary": "Retrieve organization",
"description": "Get organization for an organization group object. Returned object contains subset of organization attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_organizations_retrieve",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/organizationID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership_organization"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/billing_history": {
"get": {
"summary": "Retrieve organization billing history group",
"description": "Retrieve billing history with entries corresponding to individual contracted periods. The value `purchased_documents` or `purchased_pages` define the period billing unit.\n",
"operationId": "organization_groups_billing_history",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/billing_period"
},
{
"type": "object",
"properties": {
"organization_group": {
"allOf": [
{
"$ref": "#/components/schemas/organization_group_url"
},
{
"description": "Organization group URL. (Only present for organization groups)"
}
]
},
"values": {
"$ref": "#/components/schemas/billing_history_values"
}
}
}
]
}
},
"totals": {
"$ref": "#/components/schemas/billing_history_totals"
},
"updated_at": {
"type": "string",
"format": "date",
"description": "Date when the billing history was last updated.",
"example": "2022-09-01"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/billing_stats": {
"post": {
"summary": "Retrieve organization billing stats group",
"description": "Download billing stats report for an organization group.\n\n**Limitations**:\n- `filter.queues` can only be used when `filter.organizations` contains a single organization\n- `filter.queues` cannot be used for `group_by=organization`\n",
"operationId": "organization_groups_billing_stats",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"$ref": "#/components/schemas/billing_filters_org_group"
},
"group_by": {
"$ref": "#/components/schemas/group_by_stats_group"
},
"order_by": {
"$ref": "#/components/schemas/order_by"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/billing_period"
},
{
"type": "object",
"properties": {
"organization": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Organization URL.",
"example": "https://example.rossum.app/api/v1/organizations/406"
},
"organization_group": {
"allOf": [
{
"$ref": "#/components/schemas/organization_group_url"
},
{
"description": "Organization group URL. (Only present for organization groups)"
}
]
},
"queue": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Queue URL (null for historically deleted queues).",
"example": "https://example.rossum.app/api/v1/queues/8199"
},
"values": {
"$ref": "#/components/schemas/billing_history_values"
}
}
}
]
}
},
"totals": {
"$ref": "#/components/schemas/billing_history_totals"
},
"updated_at": {
"type": "string",
"format": "date",
"description": "Date when the billing stats were last updated.",
"example": "2022-09-01"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/queues/{queueID}": {
"get": {
"summary": "Retrieve queue",
"description": "Get queue for an organization group object. Returned object contains subset of queue attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_queues_retrieve",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/queueID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership_queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/users/{userID}": {
"get": {
"summary": "Retrieve user",
"description": "Get user for an organization group object. Returned object contains subset of user attributes.\n\n\nThe endpoint provides read-only view for users with the `organization_group_admin` role for managing memberships.\n\n",
"operationId": "organization_groups_users_retrieve",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/userID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership_user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/organization_groups/{organizationGroupID}/workspaces/{workspaceID}": {
"get": {
"summary": "Retrieve workspace",
"description": "Get workspace for an organization group object. Returned object contains subset of workspace attributes.\n\n\nPlease note that direct access to the API requires you to login using Rossum credentials. User must have `organization_group_admin` role.\n\n",
"operationId": "organization_groups_workspaces_retrieve",
"tags": [
"Organization Group"
],
"parameters": [
{
"$ref": "#/components/parameters/organizationGroupID"
},
{
"$ref": "#/components/parameters/workspaceID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/membership_workspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/pages": {
"get": {
"summary": "List pages",
"description": "Retrieve all page objects.",
"operationId": "pages_list",
"tags": [
"Page"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id-2"
},
{
"$ref": "#/components/parameters/annotation-2"
},
{
"$ref": "#/components/parameters/number"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"number",
"-number",
"s3_name",
"-s3_name"
]
}
}
],
"responses": {
"200": {
"description": "Returns paginated response with a list of page objects.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/page_object"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/pages/{pageID}": {
"get": {
"summary": "Retrieve page",
"description": "Get a page object.",
"operationId": "pages_retrieve",
"tags": [
"Page"
],
"parameters": [
{
"$ref": "#/components/parameters/pageID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/page_object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues": {
"post": {
"summary": "Create queue",
"description": "Create a new queue object.",
"operationId": "queues_create",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Test Queue\", \"workspace\": \"https://example.rossum.app/api/v1/workspaces/7540\", \"schema\": \"https://example.rossum.app/api/v1/schemas/31336\", \"generic_engine\": \"https://example.rossum.app/api/v1/generic_engines/9876\"}' \\\n 'https://example.rossum.app/api/v1/queues'\n"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue",
"required": [
"name",
"schema"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List queues",
"description": "Retrieve all queue objects.",
"operationId": "queues_list",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues?workspace=7540&ordering=name'\n"
}
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/workspace"
},
{
"$ref": "#/components/parameters/inbox-2"
},
{
"$ref": "#/components/parameters/connector"
},
{
"$ref": "#/components/parameters/webhooks"
},
{
"$ref": "#/components/parameters/hooks"
},
{
"$ref": "#/components/parameters/locale"
},
{
"$ref": "#/components/parameters/dedicated_engine"
},
{
"$ref": "#/components/parameters/generic_engine"
},
{
"$ref": "#/components/parameters/deleting"
},
{
"$ref": "#/components/parameters/automation_level"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering. Supported ordering - `id`, `name`, `workspace`, `connector`, `webhooks`, `schema`, `inbox`, `locale`.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"workspace",
"-workspace",
"connector",
"-connector",
"webhooks",
"-webhooks",
"schema",
"-schema",
"inbox",
"-inbox",
"locale",
"-locale"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/queue"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}": {
"get": {
"summary": "Retrieve queue",
"description": "Get a queue object.",
"operationId": "queues_retrieve",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8198'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update queue",
"description": "Update queue object.",
"operationId": "queues_update",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X PUT -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"My Queue\", \"workspace\": \"https://example.rossum.app/api/v1/workspaces/7540\", \"schema\": \"https://example.rossum.app/api/v1/schemas/31336\", \"generic_engine\": \"https://example.rossum.app/api/v1/generic_engines/9876\"}' \\\n 'https://example.rossum.app/api/v1/queues/8236'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue",
"required": [
"name",
"schema"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update queue",
"description": "Update part of queue object.",
"operationId": "queues_partial_update",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X PATCH -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"New Queue\"}' \\\n 'https://example.rossum.app/api/v1/queues/8236'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete queue",
"description": "Delete queue object. Calling this endpoint will schedule the queue to be asynchronously deleted.\n",
"operationId": "queues_delete",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X DELETE -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "delete_after",
"in": "query",
"description": "The queue deletion will be postponed by the given time delta.",
"required": false,
"schema": {
"type": "string",
"format": "duration",
"default": "24:00:00"
}
}
],
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/from_template": {
"post": {
"summary": "Create queue from template",
"description": "Create new queue object from template organization.",
"operationId": "queues_from_template",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Test queue\", \"template_name\": \"EU Demo Template\", \"workspace\": \"https://example.rossum.app/api/v1/workspaces/489\", \"include_documents\": false}' \\\n 'https://example.rossum.app/api/v1/queues/from_template'\n"
}
],
"parameters": [
{
"name": "legacy",
"in": "query",
"description": "If you want to create queue from template with legacy engines. Otherwise the next generation engine will be created.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"template_name",
"workspace"
],
"properties": {
"name": {
"type": "string",
"description": "Name of a queue."
},
"template_name": {
"type": "string",
"description": "Template to use for new queue."
},
"workspace": {
"type": "string",
"format": "uri",
"description": "ID of a workspace."
},
"include_documents": {
"type": "boolean",
"description": "Whether to copy documents from the template queue."
},
"engine": {
"type": "string",
"format": "uri",
"description": "Engine to be attached to the queue."
}
}
},
"examples": {
"create_queue_from_template": {
"value": {
"name": "Invoice Processing - ACME Corp",
"template_name": "EU Invoice Template",
"workspace": "https://example.rossum.app/api/v1/workspaces/489",
"include_documents": true,
"engine": "https://example.rossum.app/api/v1/engines/8"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/duplicate": {
"post": {
"summary": "Duplicate queue",
"description": "Duplicate a queue object.",
"operationId": "queues_duplicate",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Duplicate Queue\", \"copy_extensions_settings\": true, \"copy_email_settings\": true, \"copy_automation_setting\": true, \"copy_permissions\": true, \"copy_rules_and_actions\": true}' \\\n 'https://example.rossum.app/api/v1/queues/8236/duplicate'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the duplicated queue."
},
"copy_extensions_settings": {
"type": "boolean",
"description": "Whether to copy hooks.",
"default": true
},
"copy_email_settings": {
"type": "boolean",
"description": "Whether to copy email notifications settings.",
"default": true
},
"copy_delete_recommendations": {
"type": "boolean",
"description": "Whether to copy delete recommendations.",
"default": true
},
"copy_automation_settings": {
"type": "boolean",
"description": "Whether to copy automation level, automation settings and `automation_enabled` queue settings.",
"default": true
},
"copy_permissions": {
"type": "boolean",
"description": "Whether to copy users and memberships.",
"default": true
},
"copy_rules_and_actions": {
"type": "boolean",
"description": "Whether to copy rules.",
"default": true
}
}
},
"examples": {
"duplicate_queue_full": {
"value": {
"name": "Invoice Processing - ACME Corp (Copy)",
"copy_extensions_settings": true,
"copy_email_settings": true,
"copy_delete_recommendations": true,
"copy_automation_settings": true,
"copy_permissions": true,
"copy_rules_and_actions": true
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/queue"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/export": {
"get": {
"summary": "Export annotations",
"description": "Export annotations from the queue in XML, CSV, JSON or XLSX format.\n\nOutput format is negotiated by Accept header or `format` parameter. Supported formats are: `csv`, `xml`, `xlsx` and `json`.\n\nCalling GET will give you results for all the annotations with any of the selected status.\n",
"operationId": "queues_export",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"id": "curl-csv-columns",
"label": "cURL (CSV with columns)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?format=csv&columns=meta_file_name,document_id,date_issue,sender_name,amount_total&id=315777,315778'\n"
},
{
"lang": "shell",
"id": "curl-csv-prepend-append",
"label": "cURL (CSV with prepend/append)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?format=csv&prepend_columns=meta_file_name&append_columns=meta_url&id=315777,315778'\n"
},
{
"lang": "shell",
"id": "curl-csv-pagination",
"label": "cURL (CSV with pagination)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?format=csv&status=exported&page=1&page_size=1000'\n"
},
{
"lang": "shell",
"id": "curl-xml",
"label": "cURL (XML)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?format=xml&status=exported'\n"
},
{
"lang": "shell",
"id": "curl-json-date-filter",
"label": "cURL (JSON with date filter)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?format=json&status=exported&arrived_at_after=2019-10-13&arrived_at_before=2019-10-14'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "format",
"in": "query",
"description": "Output format.",
"required": false,
"schema": {
"type": "string",
"enum": [
"csv",
"xml",
"json",
"xlsx"
]
}
},
{
"name": "columns",
"in": "query",
"description": "Columns to include in CSV/XLSX output (comma-separated schema_ids and meta-columns).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "prepend_columns",
"in": "query",
"description": "Columns to prepend at the beginning of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "append_columns",
"in": "query",
"description": "Columns to append at the end of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "delimiter",
"in": "query",
"description": "One-character string used to separate fields in CSV.",
"required": false,
"schema": {
"type": "string",
"default": ","
}
},
{
"name": "quote_char",
"in": "query",
"description": "One-character string used to quote fields containing special characters in CSV.",
"required": false,
"schema": {
"type": "string",
"default": "\""
}
},
{
"name": "quoting",
"in": "query",
"description": "Controls when quotes should be generated in CSV.",
"required": false,
"schema": {
"type": "string",
"enum": [
"quote_minimal",
"quote_none",
"quote_all",
"quote_non_numeric"
]
}
},
{
"name": "escape_char",
"in": "query",
"description": "One-character string used by the writer to escape the delimiter in CSV.",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "status",
"in": "query",
"description": "Annotation status filter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "modifier",
"in": "query",
"description": "User id filter.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "arrived_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "arrived_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "search",
"in": "query",
"description": "Search filter (limited to 10,000 results).",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/csv": {
"schema": {
"type": "string"
}
},
"application/xml": {
"schema": {
"type": "string"
}
},
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"post": {
"summary": "Export annotations (POST)",
"description": "Export annotations from the queue in XML, CSV, JSON or XLSX format.\n\nCalling POST is useful if you are using `confirmed` state (`queue.use_confirmed_state = true`). Without specifying `to_status`, annotations will stay in their current status. If called on annotations that are already in `exporting` or `exported` status, POST call will only download the data, it will not move the annotations to a different state.\n",
"operationId": "queues_export_post",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"id": "curl-change-status-to-exporting",
"label": "cURL (change status to exporting)",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/export?to_status=exporting&status=confirmed'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "format",
"in": "query",
"description": "Output format.",
"required": false,
"schema": {
"type": "string",
"enum": [
"csv",
"xml",
"json",
"xlsx"
]
}
},
{
"name": "to_status",
"in": "query",
"description": "Status of annotations under export is switched to defined `to_status` state. This parameter is only valid with POST method, `status` can be changed only to `exporting` or `exported`. Annotations with current status `exported` or `exporting` are left untouched.",
"required": false,
"schema": {
"type": "string",
"enum": [
"exporting",
"exported"
]
}
},
{
"name": "columns",
"in": "query",
"description": "Columns to include in CSV/XLSX output (comma-separated schema_ids and meta-columns).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "prepend_columns",
"in": "query",
"description": "Columns to prepend at the beginning of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "append_columns",
"in": "query",
"description": "Columns to append at the end of CSV/XLSX output.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "delimiter",
"in": "query",
"description": "One-character string used to separate fields in CSV.",
"required": false,
"schema": {
"type": "string",
"default": ","
}
},
{
"name": "quote_char",
"in": "query",
"description": "One-character string used to quote fields containing special characters in CSV.",
"required": false,
"schema": {
"type": "string",
"default": "\""
}
},
{
"name": "quoting",
"in": "query",
"description": "Controls when quotes should be generated in CSV.",
"required": false,
"schema": {
"type": "string",
"enum": [
"quote_minimal",
"quote_none",
"quote_all",
"quote_non_numeric"
]
}
},
{
"name": "escape_char",
"in": "query",
"description": "One-character string used by the writer to escape the delimiter in CSV.",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "status",
"in": "query",
"description": "Annotation status filter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "modifier",
"in": "query",
"description": "User id filter.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "arrived_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "arrived_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "exported_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_before",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "export_failed_at_after",
"in": "query",
"description": "ISO 8601 timestamp filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"name": "search",
"in": "query",
"description": "Search filter (limited to 10,000 results).",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/csv": {
"schema": {
"type": "string"
}
},
"application/xml": {
"schema": {
"type": "string"
}
},
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/upload": {
"post": {
"summary": "Import document (deprecated)",
"description": "**Deprecated**: Please note that this upload endpoint is deprecated in favor of [create upload](/api/upload#create-upload) endpoint.\n\nUploads a document to the queue (starting in the importing state). This creates a document object and an empty annotation object.\n\nThe file can be sent as a part of multipart/form-data or, alternatively, in the request body. Multiple files upload is supported, the total size of the data uploaded may not exceed 40 MB. UTF-8 filenames are supported.\n\nYou can also specify additional properties using form field:\n- metadata could be passed using `metadata` form field. Metadata will be set to newly created annotation object.\n- values could be passed using `values` form field. It may be used to initialize datapoint values by setting the value of `rir_field_names` in the schema.\n\nUpload endpoint also supports basic authentication to enable easy integration with third-party systems.\n",
"operationId": "queues_upload",
"deprecated": true,
"tags": [
"Queue"
],
"security": [
{
"BearerAuth": []
},
{
"BasicAuth": []
}
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (multipart/form-data)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document.pdf \\\n 'https://example.rossum.app/api/v1/queues/8236/upload'\n"
},
{
"lang": "shell",
"label": "cURL (binary)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -H 'Content-Disposition: attachment; filename=document.pdf' --data-binary @file.pdf \\\n 'https://example.rossum.app/api/v1/queues/8236/upload'\n"
},
{
"lang": "shell",
"label": "cURL (multiple files)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document1.pdf -F content=@document2.pdf \\\n 'https://example.rossum.app/api/v1/queues/8236/upload'\n"
},
{
"lang": "shell",
"label": "cURL (basic auth)",
"source": "curl -u 'east-west-trading-co@example.rossum.app:secret' \\\n -F content=@document.pdf \\\n 'https://example.rossum.app/api/v1/queues/8236/upload'\n"
},
{
"lang": "shell",
"label": "cURL (with metadata and values)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document.pdf \\\n -F values='{\"upload:organization_unit\":\"Sales\"}' \\\n -F metadata='{\"project\":\"Market ABC\"}' \\\n 'https://example.rossum.app/api/v1/queues/8236/upload'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"description": "Files to upload."
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"values": {
"type": "object",
"description": "Values to initialize datapoint values."
}
}
}
},
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of created annotation."
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "URL of created document."
}
]
}
}
}
},
"annotation": {
"type": "string",
"format": "uri",
"deprecated": true,
"description": "(Obsolete) URL of first created annotation."
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "(Obsolete) URL of first created document.",
"deprecated": true
}
]
}
}
},
"examples": {
"upload_response": {
"value": {
"results": [
{
"annotation": "https://example.rossum.app/api/v1/annotations/315123",
"document": "https://example.rossum.app/api/v1/documents/215789"
}
],
"annotation": "https://example.rossum.app/api/v1/annotations/315123",
"document": "https://example.rossum.app/api/v1/documents/215789"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/upload/{filename}": {
"post": {
"summary": "Import document with filename (deprecated)",
"description": "**Deprecated**: Please note that this upload endpoint is deprecated in favor of [create upload](/api/upload#create-upload) endpoint.\n\nUploads a document to the queue with filename specified in URL (starting in the importing state). This creates a document object and an empty annotation object.\n\nUTF-8 filenames must be URL encoded.\n\nUpload endpoint also supports basic authentication to enable easy integration with third-party systems.\n",
"operationId": "queues_upload_filename",
"deprecated": true,
"tags": [
"Queue"
],
"security": [
{
"BearerAuth": []
},
{
"BasicAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "filename",
"in": "path",
"description": "Filename for the uploaded document (UTF-8 filename must be URL encoded)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"annotation",
"document"
],
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "URL of created annotation."
},
"document": {
"$ref": "#/components/schemas/document_url",
"description": "URL of created document."
}
}
}
},
"annotation": {
"type": "string",
"format": "uri",
"deprecated": true,
"description": "(Obsolete) URL of first created annotation."
},
"document": {
"$ref": "#/components/schemas/document_url",
"description": "(Obsolete) URL of first created document.",
"deprecated": true
}
}
},
"examples": {
"upload_response": {
"value": {
"results": [
{
"annotation": "https://example.rossum.app/api/v1/annotations/315123",
"document": "https://example.rossum.app/api/v1/documents/215789"
}
],
"annotation": "https://example.rossum.app/api/v1/annotations/315123",
"document": "https://example.rossum.app/api/v1/documents/215789"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/related_objects_counts": {
"get": {
"summary": "Retrieve related object counts",
"description": "\nThis is an internal API method that can change without notice.\n\n\nGet counts of selected related objects for a queue.\n",
"operationId": "queues_related_objects_counts",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X GET -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n 'https://example.rossum.app/api/v1/queues/8236/related_objects_counts'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emails": {
"type": "integer",
"description": "Number of email objects related to the queue."
},
"annotations": {
"type": "integer",
"description": "Number of annotation objects related to the queue (purged annotations are excluded from this count)."
},
"trained_dedicated_engines": {
"type": "integer",
"description": "Number of dedicated engines using the queue for training."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/suggested_recipients": {
"post": {
"summary": "Retrieve suggested email recipients",
"description": "Retrieves suggested email recipients depending on Queues suggested recipients settings.",
"operationId": "queues_suggested_recipients",
"tags": [
"Queue"
],
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL",
"source": "curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \\\n -d '{\"annotations\": [\"https://example.rossum.app/api/v1/annotations/315777\", \"https://example.rossum.app/api/v1/annotations/78590\"], \"email_threads\": [\"https://.rossum.app/api/v1/email_threads/7524\"]}' \\\n 'https://example.rossum.app/api/v1/queues/246/suggested_recipients'\n"
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of annotation urls."
},
"email_threads": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of email thread urls."
}
}
},
"examples": {
"suggested_recipients_request": {
"value": {
"annotations": [
"https://example.rossum.app/api/v1/annotations/315777",
"https://example.rossum.app/api/v1/annotations/315778"
],
"email_threads": [
"https://example.rossum.app/api/v1/email_threads/7524"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "Specifies where the email is found.",
"example": "email_header"
},
"email": {
"type": "string",
"format": "email",
"description": "Email address of the suggested recipient.",
"example": "don.joe@corp.us"
},
"name": {
"type": "string",
"description": "Name of the suggested recipient. Either a value from an email header or a value from parsing the email address.",
"example": "Don Joe"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/queues/{id}/next": {
"post": {
"summary": "Start validation",
"description": "\nThis endpoint is INTERNAL and may change in the future.\n\n\nStart reviewing the next available annotation from the queue by the calling user.\n",
"operationId": "queues_next",
"tags": [
"Queue"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "Queue ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotation_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "List of annotation ids to select from (optional)."
},
"statuses": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of allowed statuses (optional)."
}
}
},
"examples": {
"start_next_annotation": {
"value": {
"annotation_ids": [
315123,
315124,
315125
],
"statuses": [
"to_review",
"reviewing"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"annotation": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of started annotation. If there is no annotation to start, this will be `null`."
},
"session_timeout": {
"type": "string",
"description": "Session timeout in format HH:MM:SS."
}
}
},
"examples": {
"start_next_annotation_response": {
"value": {
"annotation": "https://example.rossum.app/api/v1/annotations/315123",
"session_timeout": "01:00:00"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/relations": {
"post": {
"summary": "Create relation",
"description": "Create a new relation object.",
"operationId": "relations_create",
"tags": [
"Relation"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation",
"required": [
"type",
"annotations"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List relations",
"description": "Retrieve all relation objects (annotations from queues not with `active` status are excluded).\n",
"operationId": "relations_list",
"tags": [
"Relation"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/relation_type"
},
{
"$ref": "#/components/parameters/parent-2"
},
{
"$ref": "#/components/parameters/key-2"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"type",
"-type",
"parent",
"-parent",
"key",
"-key"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/relation"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/relations/{relationID}": {
"get": {
"summary": "Retrieve relation",
"description": "Get a relation object.\n",
"operationId": "relations_retrieve",
"tags": [
"Relation"
],
"parameters": [
{
"$ref": "#/components/parameters/relationID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation"
}
}
}
},
"304": {
"$ref": "#/components/responses/304_not_modified"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update relation",
"description": "Update relation object.\n",
"operationId": "relations_update",
"tags": [
"Relation"
],
"parameters": [
{
"$ref": "#/components/parameters/relationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation",
"required": [
"type",
"annotations"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update relation",
"description": "Update part of relation object.\n",
"operationId": "relations_partial_update",
"tags": [
"Relation"
],
"parameters": [
{
"$ref": "#/components/parameters/relationID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relation"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete relation",
"description": "Delete relation object.\n",
"operationId": "relations_delete",
"tags": [
"Relation"
],
"parameters": [
{
"$ref": "#/components/parameters/relationID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/rules": {
"post": {
"summary": "Create rule",
"description": "Create a new rule object.",
"operationId": "rules_create",
"tags": [
"Rule"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule",
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List rules",
"description": "List all rules objects.",
"operationId": "rules_list",
"tags": [
"Rule"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/queue-2"
},
{
"$ref": "#/components/parameters/enabled"
},
{
"$ref": "#/components/parameters/linked"
},
{
"$ref": "#/components/parameters/actions"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/organization"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name",
"organization",
"-organization"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/rule"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/rules/{ruleID}": {
"get": {
"summary": "Retrieve rule",
"description": "Retrieve a rule object.",
"operationId": "rules_retrieve",
"tags": [
"Rule"
],
"parameters": [
{
"$ref": "#/components/parameters/ruleID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update rule",
"description": "Update rule object.",
"operationId": "rules_update",
"tags": [
"Rule"
],
"parameters": [
{
"$ref": "#/components/parameters/ruleID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule",
"required": [
"name",
"schema"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update rule",
"description": "Update part of rule object.",
"operationId": "rules_partial_update",
"tags": [
"Rule"
],
"parameters": [
{
"$ref": "#/components/parameters/ruleID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete rule",
"description": "Delete rule object.",
"operationId": "rules_delete",
"tags": [
"Rule"
],
"parameters": [
{
"$ref": "#/components/parameters/ruleID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/rules_execution_logs": {
"get": {
"summary": "List rules execution logs",
"description": "List rules execution logs with optional filters and pagination.\n\nReturns paginated rule execution records (controlled by `page_size`), including trigger conditions, evaluation results, and executed actions.\n",
"operationId": "rules_execution_logs_list",
"tags": [
"Rules Execution Log"
],
"parameters": [
{
"$ref": "#/components/parameters/created_at_after"
},
{
"$ref": "#/components/parameters/created_at_before"
},
{
"$ref": "#/components/parameters/rule"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/request_id-2"
},
{
"$ref": "#/components/parameters/execution_result"
},
{
"$ref": "#/components/parameters/trigger_event"
},
{
"$ref": "#/components/parameters/search-4"
},
{
"$ref": "#/components/parameters/page_size-2"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rules_execution_logs_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/schemas": {
"post": {
"summary": "Create schema",
"description": "Create a new schema object.",
"operationId": "schemas_create",
"tags": [
"Schema"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema_w_required"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List schemas",
"description": "Retrieve all schema objects.",
"operationId": "schemas_list",
"tags": [
"Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"$ref": "#/components/parameters/queue"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/schema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/schemas/{schemaID}": {
"get": {
"summary": "Retrieve schema",
"description": "Get a schema object.\n",
"operationId": "schemas_retrieve",
"tags": [
"Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/schemaID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"304": {
"$ref": "#/components/responses/304_not_modified"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update schema",
"description": "Update schema object. See [Updating schema](/guides/document-schema#updating-schema) for more details about consequences of schema update.",
"operationId": "schemas_update",
"tags": [
"Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/schemaID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema_w_required"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update schema",
"description": "Update part of schema object. See [Updating schema](/guides/document-schema#updating-schema) for more details about consequences of schema update.\n\n\nThis request can only change top-level properties of the [schema](/api/schema) object.\nPartial update of [schema content](/guides/document-schema#schema-content) is not available. To update a part\nof the schema content, send the whole schema content in the request,\ncontaining the new changes you would like to apply to the original schema.\n\n",
"operationId": "schemas_partial_update",
"tags": [
"Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/schemaID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete schema",
"description": "Delete schema object.\n\n\nIn case the schema is linked to some objects, like queue or annotation,\nthe deletion is not possible and the request will fail with 409 status code.\n\n",
"operationId": "schemas_delete",
"tags": [
"Schema"
],
"parameters": [
{
"$ref": "#/components/parameters/schemaID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"description": "The deletion is not possible because the schema is linked to some objects, like queue or annotation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Conflict."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "conflict_status"
}
}
}
}
}
},
"412": {
"$ref": "#/components/responses/412_precondition_failed"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/schemas/from_template": {
"post": {
"summary": "Create schema from template",
"description": "Create new schema object from template organization, see available templates in [organization](/api/organization.)",
"operationId": "schemas_create_from_template",
"tags": [
"Schema"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the new schema"
},
"template_name": {
"type": "string",
"description": "Name of the template to use"
}
},
"required": [
"name",
"template_name"
]
},
"examples": {
"create_schema_from_template": {
"value": {
"name": "ACME Corp Invoice Schema",
"template_name": "EU Invoice Template"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schema"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/schemas/validate": {
"post": {
"summary": "Validate schema",
"description": "Validate schema object, check for errors.\n\n",
"operationId": "schemas_validate",
"tags": [
"Schema"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"type": "object"
},
"description": "Schema content to validate"
},
"id": {
"type": "integer",
"description": "Schema ID (required for Aurora engines)"
},
"url": {
"type": "string",
"format": "uri",
"description": "Schema URL (required for Aurora engines)"
}
},
"required": [
"content"
]
},
"examples": {
"validate_schema_request": {
"value": {
"content": [
{
"category": "section",
"id": "invoice_details",
"label": "Invoice Details",
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Document ID",
"type": "string"
},
{
"category": "datapoint",
"id": "date_issue",
"label": "Invoice Date",
"type": "date"
}
]
}
],
"id": 12345,
"url": "https://example.rossum.app/api/v1/schemas/12345"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Validation result (An error description in case of validation failure).",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/suggested_edits": {
"post": {
"summary": "Create suggested edit",
"description": "Create a new suggested edit object.\n",
"operationId": "suggested_edits_create",
"tags": [
"Suggested Edit"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit",
"required": [
"annotation",
"documents"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List suggested edits",
"description": "Retrieve all suggested edit objects.\n",
"operationId": "suggested_edits_list",
"tags": [
"Suggested Edit"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"annotation",
"-annotation"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/suggested_edit"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/suggested_edits/{suggestedEditID}": {
"get": {
"summary": "Retrieve suggested edit",
"description": "Get a suggested edit object.\n",
"operationId": "suggested_edits_retrieve",
"tags": [
"Suggested Edit"
],
"parameters": [
{
"$ref": "#/components/parameters/suggestedEditID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update suggested edit",
"description": "Update suggested edit object.\n",
"operationId": "suggested_edits_update",
"tags": [
"Suggested Edit"
],
"parameters": [
{
"$ref": "#/components/parameters/suggestedEditID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit",
"required": [
"annotation",
"documents"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update suggested edit",
"description": "Update part of suggested edit object.\n",
"operationId": "suggested_edits_partial_update",
"tags": [
"Suggested Edit"
],
"parameters": [
{
"$ref": "#/components/parameters/suggestedEditID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/suggested_edit"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete suggested edit",
"description": "Delete suggested edit object.\n",
"operationId": "suggested_edits_delete",
"tags": [
"Suggested Edit"
],
"parameters": [
{
"$ref": "#/components/parameters/suggestedEditID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/tasks/{taskID}": {
"get": {
"summary": "Retrieve task",
"description": "Get a task object.\n\n**Response Behavior:**\n- If the task has status `running` or `failed`, the endpoint returns status `200` with the task object.\n- If the task has status `succeeded` and `no_redirect` parameter is not set or is `false`, the endpoint redirects with status `303` to the newly created object (URL provided in `result_url`).\n- If the task has status `succeeded` and `no_redirect=true` is passed, the endpoint returns the task object with status `200`.\n",
"operationId": "tasks_retrieve",
"tags": [
"Task"
],
"parameters": [
{
"$ref": "#/components/parameters/taskID"
},
{
"name": "no_redirect",
"in": "query",
"description": "If true, prevents redirect to the created object and returns the task object instead.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "OK - Returns the task object. This response is returned when:\n- Task status is `running` or `failed`\n- Task status is `succeeded` and `no_redirect=true` parameter was passed\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/task"
},
"examples": {
"running": {
"value": {
"id": 24,
"url": "https://example.rossum.app/api/v1/tasks/24",
"type": "documents_download",
"status": "running",
"expires_at": "2021-09-11T09:59:00.000000Z",
"detail": null,
"content": {
"file_name": "my-archive.zip"
}
}
},
"succeeded": {
"value": {
"id": 1,
"url": "https://example.rossum.app/api/v1/tasks/1",
"type": "documents_download",
"status": "succeeded",
"expires_at": "2021-09-11T09:59:00.000000Z",
"detail": null,
"content": {
"file_name": "my-archive.zip"
},
"result_url": "https://example.rossum.app/api/v1/documents/downloads/1"
}
}
}
}
}
},
"303": {
"description": "See Other - Redirects to the newly created object when task status is `succeeded` and `no_redirect` parameter is not set.\nThe URL of the created object is provided in the `Location` header and matches the `result_url` field from the task object.\n",
"headers": {
"Location": {
"description": "URL of the created object.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/triggers": {
"post": {
"summary": "Create trigger",
"description": "Create new trigger object.\n",
"operationId": "triggers_create",
"tags": [
"Trigger"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger",
"required": [
"queue",
"event"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List triggers",
"description": "Retrieve all trigger objects.\n",
"operationId": "triggers_list",
"tags": [
"Trigger"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id-2"
},
{
"$ref": "#/components/parameters/event"
},
{
"$ref": "#/components/parameters/queue"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"event",
"-event"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/trigger"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/triggers/{triggerID}": {
"get": {
"summary": "Retrieve trigger",
"description": "Get a trigger object.\n",
"operationId": "triggers_retrieve",
"tags": [
"Trigger"
],
"parameters": [
{
"$ref": "#/components/parameters/triggerID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update trigger",
"description": "Update trigger object.\n",
"operationId": "triggers_update",
"tags": [
"Trigger"
],
"parameters": [
{
"$ref": "#/components/parameters/triggerID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger",
"required": [
"queue",
"event"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update trigger",
"description": "Update part of a trigger object.\n",
"operationId": "triggers_partial_update",
"tags": [
"Trigger"
],
"parameters": [
{
"$ref": "#/components/parameters/triggerID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trigger"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete trigger",
"description": "Delete a trigger object.\n\n\nTrigger of `email_with_no_processable_attachments` event cannot be deleted.\n\n",
"operationId": "triggers_delete",
"tags": [
"Trigger"
],
"parameters": [
{
"$ref": "#/components/parameters/triggerID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/uploads": {
"post": {
"summary": "Create upload",
"description": "Uploads a document to the queue specified as query parameter (starting in the importing state).\n\nMultiple files upload is supported, the total size of the data uploaded may not exceed 40 MB.\nUTF-8 filenames are supported, see examples.\n\nThe file can be sent as a part of multipart/form-data or, alternatively, in the\nrequest body.\n\nThe `{filename}` parameter in the URL path only works when sending the file in the request body using `--data-binary`.\nWhen uploading via multipart/form-data, the filename is automatically extracted from the form field and the `{filename}` \nparameter in the URL is ignored. Use the `Content-Disposition` header or specify the filename in the form field instead.\n\nYou can also specify additional properties using form field:\n\n- Metadata could be passed using `metadata` form field. Metadata will\nbe set to newly created annotation object.\n- Values could be passed using `values` form field. It may\nbe used to initialize datapoint values by setting the value of\n`rir_field_names` in the schema.\n\nFor example `upload:organization_unit` field may be referenced in a schema like this:\n```json\n{\n \"category\": \"datapoint\",\n \"id\": \"organization_unit\", \n \"label\": \"Org unit\",\n \"type\": \"string\",\n \"rir_field_names\": [\"upload:organization_unit\"]\n}\n```\n\nThe endpoint is asynchronous and response contains created task url. Further information about the import status may be acquired by retrieving the upload object or the task (for more information, please refer to task).\n",
"operationId": "uploads_create",
"tags": [
"Upload"
],
"security": [
{
"BearerAuth": []
},
{
"BasicAuth": []
}
],
"parameters": [
{
"name": "queue",
"in": "query",
"description": "ID of the target queue for the upload.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 8236
},
{
"name": "reject_identical",
"in": "query",
"description": "When enabled, upload checks for identical documents within a given organization. \nIf such document is found, upload fails with status 409. The check is performed \nbased on file name and file content. Only one file is allowed when `reject_identical` is set to `true`.\n",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"format": "binary",
"description": "The file(s) to upload. Multiple files are supported."
},
"metadata": {
"type": "string",
"description": "JSON string containing metadata to be set on the newly created annotation object.",
"example": "{\"project\":\"Market ABC\"}"
},
"values": {
"type": "string",
"description": "JSON string containing values to initialize datapoint values.",
"example": "{\"upload:organization_unit\":\"Sales\"}"
}
},
"required": [
"content"
]
}
},
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (multipart/form-data)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document.pdf \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
},
{
"lang": "shell",
"label": "cURL (binary)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -H 'Content-Disposition: attachment; filename=document.pdf' --data-binary @file.pdf \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
},
{
"lang": "shell",
"label": "cURL (binary - UTF-8)",
"source": "# UTF-8 filename must be URL encoded\ncurl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -H \"Content-Disposition: attachment; filename*=utf-8''document%20%F0%9F%8E%81.pdf\" \\\n --data-binary @file.pdf \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
},
{
"lang": "shell",
"label": "cURL (multiple files)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document1.pdf -F content=@document2.pdf \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
},
{
"lang": "shell",
"label": "cURL (with metadata and values)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n -F content=@document.pdf \\\n -F values='{\"upload:organization_unit\":\"Sales\"}' \\\n -F metadata='{\"project\":\"Market ABC\"}' \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
},
{
"lang": "shell",
"label": "cURL (basic authentication)",
"source": "curl -u 'east-west-trading-co@example.rossum.app:secret' \\\n -F content=@document.pdf \\\n 'https://example.rossum.app/api/v1/uploads?queue=8236'\n"
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "url",
"description": "URL of the created [task](/api/task) for tracking upload progress.",
"example": "https://example.rossum.app/api/v1/tasks/315509"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/uploads/{uploadID}": {
"get": {
"summary": "Retrieve upload",
"description": "Returns upload object.\n",
"operationId": "uploads_retrieve",
"tags": [
"Upload"
],
"parameters": [
{
"$ref": "#/components/parameters/uploadID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/upload"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/uploads/{filename}": {
"post": {
"summary": "Create upload with filename",
"description": "Uploads a document to the queue specified as query parameter with filename specified in the URL path.\nUTF-8 filenames are supported and must be URL encoded.\n\nThe file should be sent in the request body. The total size of the data uploaded may not exceed 40 MB.\n\nThe endpoint is asynchronous and response contains created task url. Further information about the import status may be acquired by retrieving the upload object or the task (for more information, please refer to task).\n",
"operationId": "uploads_create_with_filename",
"tags": [
"Upload"
],
"security": [
{
"BearerAuth": []
},
{
"BasicAuth": []
}
],
"parameters": [
{
"name": "filename",
"in": "path",
"description": "The filename for the uploaded document. UTF-8 filenames must be URL encoded.",
"required": true,
"schema": {
"type": "string"
},
"example": "document%20%F0%9F%8E%81.pdf"
},
{
"name": "queue",
"in": "query",
"description": "ID of the target queue for the upload.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 8236
},
{
"name": "reject_identical",
"in": "query",
"description": "When enabled, upload checks for identical documents within a given organization. \nIf such document is found, upload fails with status 409. The check is performed \nbased on file name and file content. Only one file is allowed when `reject_identical` is set to `true`.\n",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"requestBody": {
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"format": "binary",
"description": "The file to upload."
},
"metadata": {
"type": "string",
"description": "JSON string containing metadata to be set on the newly created annotation object.",
"example": "{\"project\":\"Market ABC\"}"
},
"values": {
"type": "string",
"description": "JSON string containing values to initialize datapoint values.",
"example": "{\"upload:organization_unit\":\"Sales\"}"
}
},
"required": [
"content"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "shell",
"label": "cURL (binary)",
"source": "curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \\\n --data-binary @file.pdf \\\n 'https://example.rossum.app/api/v1/uploads/document%20%F0%9F%8E%81.pdf?queue=8236'\n"
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "url",
"description": "URL of the created task for tracking upload progress.",
"example": "https://example.rossum.app/api/v1/tasks/315509"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/users": {
"post": {
"summary": "Create user",
"description": "Create a new user object.\n\n\nFor security reasons, it is better to create users without a specified password.\nSuch users have an invalid password.\nLater, they can set their password after using [reset-password endpoint](/api/user#change-password).\n\n",
"operationId": "users_create",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user",
"required": [
"username",
"organization"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List users",
"description": "Retrieve all user objects.",
"operationId": "users_list",
"tags": [
"User"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/organization"
},
{
"$ref": "#/components/parameters/username-2"
},
{
"$ref": "#/components/parameters/first_name"
},
{
"$ref": "#/components/parameters/last_name"
},
{
"$ref": "#/components/parameters/user_email_address"
},
{
"$ref": "#/components/parameters/is_active"
},
{
"$ref": "#/components/parameters/last_login"
},
{
"$ref": "#/components/parameters/groups"
},
{
"$ref": "#/components/parameters/queue"
},
{
"$ref": "#/components/parameters/deleted"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"username",
"-username",
"first_name",
"-first_name",
"last_name",
"-last_name",
"email",
"-email",
"last_login",
"-last_login",
"date_joined",
"-date_joined",
"deleted",
"-deleted",
"not_deleted",
"-not_deleted"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/user"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/users/{userID}": {
"get": {
"summary": "Retrieve user",
"description": "Get a user object.",
"operationId": "users_retrieve",
"tags": [
"User"
],
"parameters": [
{
"$ref": "#/components/parameters/userID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update user",
"description": "Update user object.",
"operationId": "users_update",
"tags": [
"User"
],
"parameters": [
{
"$ref": "#/components/parameters/userID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user",
"required": [
"username",
"organization"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update user",
"description": "Update part of user object.",
"operationId": "users_partial_update",
"tags": [
"User"
],
"parameters": [
{
"$ref": "#/components/parameters/userID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete user",
"description": "Soft-delete a user - marking a user as deleted, without a possibility of reversing the deletion.\n\nThe following rules apply to user soft-deletion:\n\n* A regular user can delete self and nobody else\n* An organization admin can delete other users within the organization, including other admins\n * For trial organizations, the admin deleting self actually means the whole trial organization will be deleted\n * For non-trial organization\n * The last admin cannot be deleted via API, but must instead create a ticket with support\n * If the organization has an organization group admin, the admin can delete self but the org will be preserved\n* An organization group admin\n * Cannot be deleted via API\n * Can remove any organization admin or regular user\n",
"operationId": "users_delete",
"tags": [
"User"
],
"parameters": [
{
"$ref": "#/components/parameters/userID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/login": {
"post": {
"summary": "Login",
"description": "Authenticate with username and password to obtain an access token.\n\nThe returned `key` can be used for Bearer (or Token) authentication in subsequent requests:\n\n```\nAuthorization: Bearer \n```\n\nThe token expires after a configurable period (default 162 hours). When it expires,\nre-authenticate to obtain a new token.\n",
"operationId": "users_login",
"tags": [
"User"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string",
"description": "Username (email address) of the user to log in.",
"example": "east-west-trading-co@example.rossum.app"
},
"password": {
"type": "string",
"format": "password",
"description": "Password of the user."
},
"max_token_lifetime_s": {
"type": "number",
"description": "Duration (in seconds) for which the token will be valid. Default is 162 hours, which is also the maximum.",
"example": 3600
}
}
},
"examples": {
"login_request": {
"summary": "Basic login",
"value": {
"username": "east-west-trading-co@example.rossum.app",
"password": "aCo2ohghBo8Oghai"
}
},
"login_with_custom_lifetime": {
"summary": "Login with custom token lifetime",
"value": {
"username": "east-west-trading-co@example.rossum.app",
"password": "aCo2ohghBo8Oghai",
"max_token_lifetime_s": 3600
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"key",
"domain"
],
"properties": {
"key": {
"type": "string",
"description": "Access token to use for authentication.",
"example": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"
},
"domain": {
"type": "string",
"description": "The domain the token was issued for.",
"example": "acme-corp.app.rossum.ai"
}
}
},
"examples": {
"login_response": {
"value": {
"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03",
"domain": "acme-corp.app.rossum.ai"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/password/change": {
"post": {
"summary": "Change password",
"description": "Change password of current user.\n\nDue to security reasons, user passwords cannot be set directly using the\nstandard CRUD operations. Instead, the following endpoints can be used for\nresetting and changing passwords.\n\nPassword requirements:\n* Length: 12–64 characters\n* May not be similar to username\n* May not contain common words\n* May not be numeric only\n* Must pass complexity check\n",
"operationId": "users_password_change",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/password_change"
},
"examples": {
"change_password_request": {
"value": {
"new_password1": "MyNewSecurePassword",
"new_password2": "MyNewSecurePassword",
"old_password": "MyOldPassword"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/password/reset": {
"post": {
"summary": "Reset password",
"description": "Reset password to a users specified by their emails.\nThe users are sent an email with a verification URL leading to web form, where they can set their password.\n",
"operationId": "users_password_reset",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/password_reset"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"example": "Password reset e-mail has been sent."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/user": {
"get": {
"summary": "Retrieve current user",
"description": "Get user object for the currently authorized user.",
"operationId": "users_auth_current",
"tags": [
"User"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update current user",
"description": "Update the currently authorized user. Fields `organization`, `groups`, and `queues`\nare read-only at this endpoint; use [update user](#tag/User/operation/users_update) to modify them.\n",
"operationId": "users_auth_update",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/user"
}
],
"required": [
"username"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update current user",
"description": "Update part of the currently authorized user. Fields `organization`, `groups`, and `queues`\nare read-only at this endpoint; use [partial update user](#tag/User/operation/users_partial_update) to modify them.\n",
"operationId": "users_auth_partial_update",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/auth/password/score": {
"post": {
"summary": "Retrieve password score",
"description": "Score to allow users to see how strong their password is from 0 (risky password) to 4 (strong password).\n",
"operationId": "users_password_score",
"tags": [
"User"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/password_score"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/password_score_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/groups": {
"get": {
"summary": "List user roles",
"description": "Retrieve all user role objects.",
"operationId": "user_roles_list",
"tags": [
"User Role"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/name"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/user_role"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/groups/{userRoleID}": {
"get": {
"summary": "Retrieve user role",
"description": "Get a user role object.",
"operationId": "user_roles_retrieve",
"tags": [
"User Role"
],
"parameters": [
{
"$ref": "#/components/parameters/userRoleID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user_role"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflows": {
"get": {
"summary": "List workflows",
"description": "Retrieve all workflow objects.\n\nSupported filters: `id`, `queue`\n\nSupported ordering: `id`\n\nFor additional info please refer to [filters and ordering](/guides/overview#filters-and-ordering).\n",
"operationId": "workflows_list",
"tags": [
"Workflow"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/queue"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflow"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflows/{workflowID}": {
"parameters": [
{
"$ref": "#/components/parameters/workflowID"
}
],
"get": {
"summary": "Retrieve workflow",
"description": "Get a workflow object.",
"operationId": "workflows_retrieve",
"tags": [
"Workflow"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workflow"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_activities": {
"get": {
"summary": "List workflow activities",
"description": "Retrieve all workflow activity objects.",
"operationId": "workflow_activities_list",
"tags": [
"Workflow Activity"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/workflow_run"
},
{
"$ref": "#/components/parameters/created_at_before"
},
{
"$ref": "#/components/parameters/created_at_after"
},
{
"$ref": "#/components/parameters/assignees-2"
},
{
"$ref": "#/components/parameters/action-2"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflow_activity"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_activities/{workflowActivityID}": {
"parameters": [
{
"$ref": "#/components/parameters/workflowActivityID"
}
],
"get": {
"summary": "Retrieve workflow activity",
"description": "Get a workflow activity object.",
"operationId": "workflow_activities_retrieve",
"tags": [
"Workflow Activity"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workflow_activity"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_runs": {
"get": {
"summary": "List workflow runs",
"description": "Retrieve all workflow run objects.",
"operationId": "workflow_runs_list",
"tags": [
"Workflow Run"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/current_step"
},
{
"$ref": "#/components/parameters/workflow_status"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflow_run"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_runs/{workflowRunID}": {
"get": {
"summary": "Retrieve workflow run",
"description": "Get a workflow run object.",
"operationId": "workflow_runs_retrieve",
"tags": [
"Workflow Run"
],
"parameters": [
{
"$ref": "#/components/parameters/workflowRunID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workflow_run"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_runs/{workflowRunID}/reset": {
"post": {
"summary": "Reset workflow run",
"description": "Resetting the workflow run leads to:\n- change its workflow status to `in_review`\n- empty annotation's `assignees`\n- set the annotation status to `to_review`\n- create workflow activity of action `pushed_back`\n\n\nResetting is allowed only for workflow runs with related annotation in `in_workflow` state. See [Annotation Lifecycle](/guides/annotation-lifecycle) for more information about states.\n\n",
"operationId": "workflow_runs_reset",
"tags": [
"Workflow Run"
],
"parameters": [
{
"$ref": "#/components/parameters/workflowRunID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reset_request"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reset_response"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_steps": {
"get": {
"summary": "List workflow steps",
"description": "Retrieve all workflow step objects.",
"operationId": "workflow_steps_list",
"tags": [
"Workflow Step"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/workflow"
},
{
"$ref": "#/components/parameters/mode"
},
{
"$ref": "#/components/parameters/workflow_step_type"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflow_step"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workflow_steps/{workflowStepID}": {
"get": {
"summary": "Retrieve workflow step",
"description": "Get a workflow step object.",
"operationId": "workflow_steps_retrieve",
"tags": [
"Workflow Step"
],
"parameters": [
{
"$ref": "#/components/parameters/workflowStepID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workflow_step"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workspaces": {
"post": {
"summary": "Create workspace",
"description": "Create a new workspace object.",
"operationId": "workspaces_create",
"tags": [
"Workspace"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace",
"required": [
"name",
"organization"
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"get": {
"summary": "List workspaces",
"description": "Retrieve all workspace objects.",
"operationId": "workspaces_list",
"tags": [
"Workspace"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/id"
},
{
"name": "name",
"in": "query",
"description": "Name of the workspace filter",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "organization",
"in": "query",
"description": "ID of an organization to filter workspaces by",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"id",
"-id",
"name",
"-name"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workspace"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/workspaces/{workspaceID}": {
"parameters": [
{
"$ref": "#/components/parameters/workspaceID"
}
],
"get": {
"summary": "Retrieve workspace",
"description": "Get a workspace object.",
"operationId": "workspaces_retrieve",
"tags": [
"Workspace"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"put": {
"summary": "Update workspace",
"description": "Update workspace object.",
"operationId": "workspaces_update",
"tags": [
"Workspace"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace",
"required": [
"name",
"organization"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update workspace",
"description": "Update part of workspace object.",
"operationId": "workspaces_partial_update",
"tags": [
"Workspace"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/workspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete workspace",
"description": "Delete workspace object.\n\n_Note: Please note that only empty workspaces without queues can be deleted.\nTo delete a non-empty workspace, first delete all related queues._\n",
"operationId": "workspaces_delete",
"tags": [
"Workspace"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"description": "Conflict - workspace is not empty",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "This error object can have any number of properties, and their names and types are not predefined.",
"example": {
"detail": "Cannot delete workspace East West Trading Co because it contains queues with ids: [...].",
"code": "conflict_referenced"
}
}
}
}
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/internal/notes": {
"get": {
"summary": "List notes",
"description": "List all note objects.\n\n**⚠️ Deprecated**: Please note that note object and all endpoints related to it are deprecated.\n",
"operationId": "notes_list",
"deprecated": true,
"tags": [
"Note"
],
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/annotation"
},
{
"$ref": "#/components/parameters/creator"
},
{
"name": "ordering",
"in": "query",
"description": "Result ordering.",
"required": false,
"schema": {
"type": "string",
"enum": [
"modified_at",
"-modified_at",
"created_at",
"-created_at"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pagination",
"results"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/note"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
},
"/api/v1/internal/notes/{noteID}": {
"put": {
"summary": "Update note",
"description": "Update note object.\n\n**⚠️ Deprecated**: Please note that note object and all endpoints related to it are deprecated.\n",
"operationId": "notes_update",
"deprecated": true,
"tags": [
"Note"
],
"parameters": [
{
"$ref": "#/components/parameters/noteID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/note",
"required": [
"content",
"type",
"annotation"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/note"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"patch": {
"summary": "Partial update note",
"description": "Update part of note object.\n\n**⚠️ Deprecated**: Please note that note object and all endpoints related to it are deprecated.\n",
"operationId": "notes_partial_update",
"deprecated": true,
"tags": [
"Note"
],
"parameters": [
{
"$ref": "#/components/parameters/noteID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/note"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/note"
}
}
}
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"413": {
"$ref": "#/components/responses/413_payload_too_large"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
},
"delete": {
"summary": "Delete note",
"description": "Delete note object.\n\n**⚠️ Deprecated**: Please note that note object and all endpoints related to it are deprecated.\n",
"operationId": "notes_delete",
"deprecated": true,
"tags": [
"Note"
],
"parameters": [
{
"$ref": "#/components/parameters/noteID"
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"$ref": "#/components/responses/400_user_error"
},
"401": {
"$ref": "#/components/responses/401_unauthorized"
},
"403": {
"$ref": "#/components/responses/403_forbidden"
},
"404": {
"$ref": "#/components/responses/404_not_found"
},
"409": {
"$ref": "#/components/responses/409_conflict"
},
"429": {
"$ref": "#/components/responses/429_too_many_requests"
},
"500": {
"$ref": "#/components/responses/500_server_error"
},
"502": {
"$ref": "#/components/responses/502_bad_gateway"
},
"503": {
"$ref": "#/components/responses/503_service_unavailable"
},
"504": {
"$ref": "#/components/responses/504_gateway_timeout"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "Bearer"
},
"BasicAuth": {
"type": "http",
"scheme": "basic",
"description": "HTTP Basic Authentication"
}
},
"parameters": {
"0": {
"name": "id",
"in": "query",
"description": "Filter by organization ID.",
"schema": {
"type": "integer"
},
"example": 406
},
"1": {
"name": "name",
"in": "query",
"description": "Filter by organization name.",
"schema": {
"type": "string"
},
"example": "East West Trading Co"
},
"2": {
"name": "active_token",
"in": "query",
"description": "Filter by active token. Indicates what organization does the active token belong to.",
"schema": {
"type": "string"
}
},
"page_size": {
"name": "page_size",
"in": "query",
"description": "Number of results per page",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 20,
"maximum": 100
}
},
"cursor": {
"name": "cursor",
"in": "query",
"description": "A value used for cursor-based pagination. Obtain this value from the `next` or `previous` URLs in a paginated response. Do not construct cursor values manually.",
"required": false,
"schema": {
"type": "string"
}
},
"id": {
"name": "id",
"in": "query",
"description": "Object ID(s) filter",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"status": {
"name": "status",
"in": "query",
"description": "Annotation status, multiple values may be separated using a comma. See [Annotation Lifecycle](/guides/annotation-lifecycle) for available statuses.",
"required": false,
"schema": {
"type": "string",
"example": "to_review,reviewing"
}
},
"modifier": {
"name": "modifier",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"confirmed_by": {
"name": "confirmed_by",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"deleted_by": {
"name": "deleted_by",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"exported_by": {
"name": "exported_by",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"purged_by": {
"name": "purged_by",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"rejected_by": {
"name": "rejected_by",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"assignees": {
"name": "assignees",
"in": "query",
"description": "User ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"labels": {
"name": "labels",
"in": "query",
"description": "Label ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"document": {
"name": "document",
"in": "query",
"description": "The [document](/api/document) id.",
"required": false,
"schema": {
"type": "integer"
}
},
"queue": {
"name": "queue",
"in": "query",
"description": "Queue ID(s) filter",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"queue__workspace": {
"name": "queue__workspace",
"in": "query",
"description": "List of [workspace](/api/workspace) ids separated by a comma.",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
"relations__parent": {
"name": "relations__parent",
"in": "query",
"description": "ID of parent annotation defined in related [Relation](/api/relation) object.",
"required": false,
"schema": {
"type": "integer"
}
},
"relations__type": {
"name": "relations__type",
"in": "query",
"description": "Type of [Relation](/api/relation) that annotation belongs to.",
"required": false,
"schema": {
"type": "string"
}
},
"relations__key": {
"name": "relations__key",
"in": "query",
"description": "Key of [Relation](/api/relation) that annotation belongs to.",
"required": false,
"schema": {
"type": "string"
}
},
"arrived_at_before": {
"name": "arrived_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `arrived_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"arrived_at_after": {
"name": "arrived_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `arrived_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"assigned_at_before": {
"name": "assigned_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `assigned_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"assigned_at_after": {
"name": "assigned_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `assigned_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"confirmed_at_before": {
"name": "confirmed_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `confirmed_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"confirmed_at_after": {
"name": "confirmed_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `confirmed_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"modified_at_before": {
"name": "modified_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `modified_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"modified_at_after": {
"name": "modified_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `modified_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"deleted_at_before": {
"name": "deleted_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `deleted_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"deleted_at_after": {
"name": "deleted_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `deleted_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"exported_at_before": {
"name": "exported_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `exported_at_before=2019-11-14 22:00:00`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"exported_at_after": {
"name": "exported_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `exported_at_after=2019-11-14 12:00:00`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"export_failed_at_before": {
"name": "export_failed_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `export_failed_at_before=2019-11-14 22:00:00`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"export_failed_at_after": {
"name": "export_failed_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `export_failed_at_after=2019-11-14 12:00:00`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"purged_at_before": {
"name": "purged_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `purged_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"purged_at_after": {
"name": "purged_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `purged_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"rejected_at_before": {
"name": "rejected_at_before",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `rejected_at_before=2019-11-15`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"rejected_at_after": {
"name": "rejected_at_after",
"in": "query",
"description": "ISO 8601 timestamp (e.g. `rejected_at_after=2019-11-14`).",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"restricted_access": {
"name": "restricted_access",
"in": "query",
"description": "Boolean.",
"required": false,
"schema": {
"type": "boolean"
}
},
"automated": {
"name": "automated",
"in": "query",
"description": "Boolean.",
"required": false,
"schema": {
"type": "boolean"
}
},
"has_email_thread_with_replies": {
"name": "has_email_thread_with_replies",
"in": "query",
"description": "Boolean (related email thread contains more than one `incoming` emails).",
"required": false,
"schema": {
"type": "boolean"
}
},
"has_email_thread_with_new_replies": {
"name": "has_email_thread_with_new_replies",
"in": "query",
"description": "Boolean (related email thread contains unread `incoming` email).",
"required": false,
"schema": {
"type": "boolean"
}
},
"search": {
"name": "search",
"in": "query",
"description": "If this filter is used, annotations are filtered based on full-text search in annotation's datapoint values,\noriginal file name, modifier user email and messages.\n\nSome special characters are ignored in the search term. \n\nThe results are limited to 10,000, any annotations over this limit will not be possible to list. We suggest\nnarrowing down the search query if there are this many results. \n\nPlease beware that updates of the annotation search data are done asynchronously and are eventually consistent.\nSearch may return inconsistent results temporarily (for a few seconds).\n",
"required": false,
"schema": {
"type": "string",
"maxLength": 256
}
},
"fields": {
"name": "fields",
"in": "query",
"required": false,
"description": "Comma-separated list of attributes to be **included** in the response. See the\n[Query Field Filtering](/api/annotation#query-field-filtering) section for detailed explanation and available options.\n",
"schema": {
"type": "string"
}
},
"fields_exclude": {
"name": "fields!",
"in": "query",
"required": false,
"description": "Comma-separated list of attributes to be **excluded** from the response. See the\n[Query Field Filtering](/api/annotation#query-field-filtering) section for detailed explanation and available options.\n",
"schema": {
"type": "string"
}
},
"sideload": {
"name": "sideload",
"in": "query",
"required": false,
"description": "Comma-separated list of related objects to sideload (e.g., `modifiers,documents,content`). See the\n[Sideloading](/api/annotation#sideloading) section for detailed explanation and available options.\n",
"schema": {
"type": "string"
}
},
"content_schema_id": {
"name": "content.schema_id",
"in": "query",
"required": false,
"description": "Filter sideloaded content by schema_id (comma-separated list).",
"schema": {
"type": "string"
}
},
"annotationID": {
"name": "annotationID",
"in": "path",
"description": "Annotation ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"object_type": {
"name": "object_type",
"in": "query",
"description": "Type of the object on which the action was performed. Available types are `document`, `annotation`, `user`",
"required": true,
"schema": {
"type": "string",
"enum": [
"document",
"annotation",
"user"
]
}
},
"action": {
"name": "action",
"in": "query",
"description": "Type of the action performed.\n\nEach `object_type` supports filtering by different actions:\n\n| object_type | Available actions |\n|-------------|-------------------|\n| document | create |\n| annotation | update-status |\n| user | create, delete, purge, update, destroy, app_load, reset-password, change-password |\n\n\n`app_load` value represents records of when `api/v1/auth/user` endpoint was called.\n\n",
"required": false,
"schema": {
"type": "string"
},
"example": "change_password"
},
"object_id": {
"name": "object_id",
"in": "query",
"description": "ID of the object on which the action was performed",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"timestamp_before": {
"name": "timestamp_before",
"in": "query",
"description": "Filter for log entries before the given timestamp",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"timestamp_after": {
"name": "timestamp_after",
"in": "query",
"description": "Filter for log entries after the given timestamp",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"username": {
"name": "username",
"in": "query",
"description": "Username of the user that performed the action",
"required": false,
"schema": {
"type": "string"
}
},
"connectorID": {
"name": "connectorID",
"in": "path",
"description": "A unique integer value identifying this connector.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"dedicatedEngineID": {
"name": "dedicatedEngineID",
"in": "path",
"required": true,
"description": "ID of the dedicated engine",
"schema": {
"type": "integer",
"format": "int64"
},
"example": 3000
},
"dedicatedEngineSchemaID": {
"name": "dedicatedEngineSchemaID",
"in": "path",
"description": "A unique integer value identifying this dedicated engine schema.",
"required": true,
"schema": {
"type": "integer"
}
},
"deleteRecommendationID": {
"name": "deleteRecommendationID",
"in": "path",
"description": "ID of the delete recommendation",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"email": {
"name": "email",
"in": "query",
"description": "ID(s) of email object(s)",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"creator": {
"name": "creator",
"in": "query",
"description": "ID(s) of user(s) that created the object",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"created_at_before": {
"name": "created_at_before",
"in": "query",
"description": "Created before filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"created_at_after": {
"name": "created_at_after",
"in": "query",
"description": "Created after filter.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"arrived_at_before-2": {
"name": "arrived_at_before",
"in": "query",
"description": "Same as `created_at_before`.",
"required": false,
"deprecated": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
"arrived_at_after-2": {
"name": "arrived_at_after",
"in": "query",
"description": "Same as `created_at_after`.",
"required": false,
"deprecated": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
"original_file_name": {
"name": "original_file_name",
"in": "query",
"description": "Name of the document filter",
"required": false,
"schema": {
"type": "string"
}
},
"attachment_status": {
"name": "attachment_status",
"in": "query",
"description": "Attachment status filter",
"required": false,
"schema": {
"$ref": "#/components/schemas/document_attachment_status"
}
},
"parent": {
"name": "parent",
"in": "query",
"description": "ID of parent document filter",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"documentID": {
"name": "documentID",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"document_relation_type": {
"name": "type",
"in": "query",
"description": "Relation type. Multiple values may be separated using a comma.",
"required": false,
"schema": {
"type": "string",
"enum": [
"export",
"einvoice"
]
}
},
"annotation": {
"name": "annotation",
"in": "query",
"description": "Annotation ID(s) filter",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"key": {
"name": "key",
"in": "query",
"description": "Document relation key",
"required": false,
"schema": {
"type": "string"
}
},
"documents": {
"name": "documents",
"in": "query",
"description": "ID of related document. Multiple values may be separated using a comma.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"documentRelationID": {
"name": "documentRelationID",
"in": "path",
"description": "Document relation ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"documentsDownloadID": {
"name": "documentsDownloadID",
"in": "path",
"description": "A unique integer value identifying this documents download.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"created_at_before-2": {
"name": "created_at_before",
"in": "query",
"description": "Filter emails created before this date",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"created_at_after-2": {
"name": "created_at_after",
"in": "query",
"description": "Filter emails created after this date",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"subject": {
"name": "subject",
"in": "query",
"description": "Filter by email subject",
"required": false,
"schema": {
"type": "string"
}
},
"inbox": {
"name": "inbox",
"in": "query",
"description": "Filter by inbox ID",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"documents-2": {
"name": "documents",
"in": "query",
"description": "Filter by document ID",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"from__email": {
"name": "from__email",
"in": "query",
"description": "Filter by sender email address",
"required": false,
"schema": {
"type": "string",
"format": "email"
}
},
"from__name": {
"name": "from__name",
"in": "query",
"description": "Filter by sender name",
"required": false,
"schema": {
"type": "string"
}
},
"to": {
"name": "to",
"in": "query",
"description": "Filter by recipient email address",
"required": false,
"schema": {
"type": "string",
"format": "email"
}
},
"last_thread_email_created_at_before": {
"name": "last_thread_email_created_at_before",
"in": "query",
"description": "Filter emails with last thread email created before this date",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"last_thread_email_created_at_after": {
"name": "last_thread_email_created_at_after",
"in": "query",
"description": "Filter emails with last thread email created after this date",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"email_type": {
"name": "type",
"in": "query",
"description": "Filter by email type",
"required": false,
"schema": {
"type": "string",
"enum": [
"incoming",
"outgoing"
]
}
},
"email_thread": {
"name": "email_thread",
"in": "query",
"description": "Filter by email thread ID",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"has_documents": {
"name": "has_documents",
"in": "query",
"description": "Filter emails that have or don't have documents",
"required": false,
"schema": {
"type": "boolean"
}
},
"emailID": {
"name": "emailID",
"in": "path",
"description": "Email ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 1234
},
"type": {
"name": "type",
"in": "query",
"description": "Type of the email template to filter by",
"required": false,
"schema": {
"type": "string",
"enum": [
"rejection",
"rejection_default",
"email_with_no_processable_attachments",
"custom"
]
}
},
"name": {
"name": "name",
"in": "query",
"description": "Object name filter",
"required": false,
"schema": {
"type": "string"
}
},
"emailTemplateID": {
"name": "emailTemplateID",
"in": "path",
"description": "A unique integer value identifying this email template.",
"required": true,
"schema": {
"type": "integer"
}
},
"has_root_email": {
"name": "has_root_email",
"in": "query",
"description": "Filter only email threads with a root email.",
"required": false,
"schema": {
"type": "boolean"
}
},
"has_replies": {
"name": "has_replies",
"in": "query",
"description": "Filter only email threads with two and more emails with type `incoming`.",
"required": false,
"schema": {
"type": "boolean"
}
},
"has_new_replies": {
"name": "has_new_replies",
"in": "query",
"description": "Filter only email threads with unread emails with type `incoming`.",
"required": false,
"schema": {
"type": "boolean"
}
},
"last_email_created_at_before": {
"name": "last_email_created_at_before",
"in": "query",
"description": "Filter only email threads with the last email in the thread created before given timestamp.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"last_email_created_at_after": {
"name": "last_email_created_at_after",
"in": "query",
"description": "Filter only email threads with the last email in the thread created after given timestamp.",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"recent_with_no_documents_not_replied": {
"name": "recent_with_no_documents_not_replied",
"in": "query",
"description": "Filter only email threads with root email that arrived in the last 14 days with no attachment processed by Rossum, excluding those with `rejected` label, without any reply and when root email has been read.",
"required": false,
"schema": {
"type": "boolean"
}
},
"emailThreadID": {
"name": "emailThreadID",
"in": "path",
"description": "ID of the email thread",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"engine": {
"name": "engine",
"in": "query",
"description": "Filter by engine URL or ID.",
"required": false,
"schema": {
"type": "string"
},
"example": "https://example.rossum.app/api/v1/engines/8"
},
"used": {
"name": "used",
"in": "query",
"description": "Filter engine fields used (or not used) in any schema in queues using this engine.",
"required": false,
"schema": {
"type": "boolean"
},
"example": true
},
"engineFieldID": {
"name": "engineFieldID",
"in": "path",
"required": true,
"description": "Engine field ID",
"schema": {
"type": "integer",
"format": "int64"
},
"example": 123
},
"engine_type": {
"name": "type",
"in": "query",
"description": "Type of the engine to filter by",
"required": false,
"schema": {
"type": "string",
"enum": [
"extractor",
"splitter"
]
}
},
"agenda_id": {
"name": "agenda_id",
"in": "query",
"description": "Agenda ID of the engine to filter by",
"required": false,
"schema": {
"type": "string"
}
},
"engineID": {
"name": "engineID",
"in": "path",
"description": "ID of the engine",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 3
},
"genericEngineID": {
"name": "genericEngineID",
"in": "path",
"description": "ID of the generic engine.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"genericEngineSchemaID": {
"name": "genericEngineSchemaID",
"in": "path",
"required": true,
"description": "A unique integer value identifying this generic engine schema.",
"schema": {
"type": "integer"
}
},
"hook_type": {
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"webhook",
"function"
]
},
"description": "Filter by hook type.",
"example": "webhook"
},
"active": {
"name": "active",
"in": "query",
"schema": {
"type": "boolean"
},
"description": "Filter by active status.",
"example": true
},
"config_url": {
"name": "config_url",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by configuration URL.",
"example": "https://myq.east-west-trading.com"
},
"config_app_url": {
"name": "config_app_url",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by configuration app URL.",
"example": "https://myq.east-west-trading.com"
},
"extension_source": {
"name": "extension_source",
"in": "query",
"schema": {
"type": "string",
"enum": [
"custom",
"rossum_store"
]
},
"description": "Filter by extension source.",
"example": "custom"
},
"events": {
"name": "events",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by events.",
"example": "annotation_status.changed"
},
"search-2": {
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by `name` (case-insensitive) or `id` simultaneously",
"example": "Hook Foo"
},
"hookID": {
"name": "hookID",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "A unique integer value identifying this hook.",
"example": 1500
},
"request_id": {
"name": "request_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Match the specified `request_id`.",
"example": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
},
"uuid": {
"name": "uuid",
"in": "query",
"schema": {
"type": "string"
},
"description": "Match the given hook run UUID (or multiple UUIDs, comma-separated).",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"hook": {
"name": "hook",
"in": "query",
"schema": {
"type": "integer"
},
"description": "Match given the hook id (or multiple ids).",
"example": 1500
},
"timestamp_before-2": {
"name": "timestamp_before",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Filter for log entries before given timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"timestamp_after-2": {
"name": "timestamp_after",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Filter for log entries after given timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"start_before": {
"name": "start_before",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Filter for log entries before given start timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"start_after": {
"name": "start_after",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Filter for log entries after given start timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"status-2": {
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"waiting",
"running",
"completed",
"cancelled",
"failed"
]
},
"description": "Match the log entry `status` (or multiple statuses).",
"example": "completed"
},
"status_code": {
"name": "status_code",
"in": "query",
"schema": {
"type": "integer"
},
"description": "Match the response `status_code` (or multiple).",
"example": 200
},
"email-2": {
"name": "email",
"in": "query",
"schema": {
"type": "integer"
},
"description": "Match the given email id (or multiple ids).",
"example": 1
},
"search-3": {
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"description": "Full text filter across all the log entry fields.",
"example": "error"
},
"page_size-2": {
"name": "page_size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 100
},
"description": "Maximum number of results per page (between 1 and 100, defaults to 100).",
"example": 50
},
"runUuid": {
"name": "runUuid",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "The ID of the hook run.",
"example": "d5d021b3-cb12-4253-9f5f-6e8101fe1f42"
},
"log_level": {
"name": "log_level",
"in": "query",
"schema": {
"type": "string"
},
"description": "Match the specified log level (or multiple log levels).",
"example": "INFO"
},
"hookTemplateID": {
"name": "hookTemplateID",
"in": "path",
"description": "A unique integer value identifying this hook template.",
"required": true,
"schema": {
"type": "integer"
}
},
"inbox_email_address": {
"name": "email",
"in": "query",
"description": "Email filter",
"required": false,
"schema": {
"type": "string"
}
},
"email_prefix": {
"name": "email_prefix",
"in": "query",
"description": "Email prefix filter",
"required": false,
"schema": {
"type": "string"
}
},
"bounce_email_to": {
"name": "bounce_email_to",
"in": "query",
"description": "Bounce email to filter",
"deprecated": true,
"required": false,
"schema": {
"type": "string"
}
},
"bounce_unprocessable_attachments": {
"name": "bounce_unprocessable_attachments",
"in": "query",
"description": "Bounce unprocessable attachments filter",
"deprecated": true,
"required": false,
"schema": {
"type": "boolean"
}
},
"bounce_postponed_annotations": {
"name": "bounce_postponed_annotations",
"in": "query",
"description": "Bounce postponed annotations filter",
"deprecated": true,
"required": false,
"schema": {
"type": "boolean"
}
},
"bounce_deleted_annotations": {
"name": "bounce_deleted_annotations",
"in": "query",
"description": "Bounce deleted annotations filter",
"deprecated": true,
"required": false,
"schema": {
"type": "boolean"
}
},
"bounce_email_with_no_attachments": {
"name": "bounce_email_with_no_attachments",
"in": "query",
"description": "Bounce emails with no attachment extracted.",
"deprecated": true,
"required": false,
"schema": {
"type": "boolean"
}
},
"inboxID": {
"name": "inboxID",
"in": "path",
"description": "ID of the inbox",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"labelID": {
"name": "labelID",
"in": "path",
"description": "A unique integer value identifying this label.",
"required": true,
"schema": {
"type": "integer"
}
},
"organizationGroupID": {
"name": "organizationGroupID",
"in": "path",
"description": "A unique integer value identifying organization group.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"user": {
"name": "user",
"in": "query",
"description": "ID of a user to filter memberships by",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"organization": {
"name": "organization",
"in": "query",
"description": "Organization ID(s) filter",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
},
"style": "form",
"explode": false
},
"membershipID": {
"name": "membershipID",
"in": "path",
"description": "A unique integer value identifying this membership.",
"required": true,
"schema": {
"type": "integer"
}
},
"organizationID": {
"name": "organizationID",
"in": "path",
"required": true,
"description": "A unique integer value identifying the organization.",
"schema": {
"type": "integer"
},
"example": 406
},
"queueID": {
"name": "queueID",
"in": "path",
"required": true,
"description": "A unique integer value identifying this queue.",
"schema": {
"type": "integer"
}
},
"userID": {
"name": "userID",
"in": "path",
"description": "User ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 10775
},
"workspaceID": {
"name": "workspaceID",
"in": "path",
"description": "ID of a workspace.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"id-2": {
"name": "id",
"in": "query",
"description": "Filter by a list of ids, e.g. `?id=1,2,3`",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"annotation-2": {
"name": "annotation",
"in": "query",
"description": "Filter by a list of annotation IDs",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"number": {
"name": "number",
"in": "query",
"description": "Filter by a list of page numbers, e.g. `?number=1,2`",
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"pageID": {
"name": "pageID",
"in": "path",
"required": true,
"description": "A unique integer value identifying this page.",
"schema": {
"type": "integer",
"format": "int64"
}
},
"workspace": {
"name": "workspace",
"in": "query",
"description": "ID of a workspace.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"inbox-2": {
"name": "inbox",
"in": "query",
"description": "ID of an inbox.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"connector": {
"name": "connector",
"in": "query",
"description": "ID of a connector.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"webhooks": {
"name": "webhooks",
"in": "query",
"description": "IDs of hooks.",
"required": false,
"schema": {
"type": "string"
}
},
"hooks": {
"name": "hooks",
"in": "query",
"description": "IDs of hooks.",
"required": false,
"schema": {
"type": "string"
}
},
"locale": {
"name": "locale",
"in": "query",
"description": "Queue object locale.",
"required": false,
"schema": {
"type": "string"
}
},
"dedicated_engine": {
"name": "dedicated_engine",
"in": "query",
"description": "ID of a dedicated engine.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"generic_engine": {
"name": "generic_engine",
"in": "query",
"description": "ID of a generic engine.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"deleting": {
"name": "deleting",
"in": "query",
"description": "Bool filter - queue is being deleted (`delete_after` is set).",
"required": false,
"schema": {
"type": "boolean"
}
},
"automation_level": {
"name": "automation_level",
"in": "query",
"description": "Filter by automation level. Supports comma-separated values (e.g. `always,confident`).",
"required": false,
"schema": {
"type": "string",
"enum": [
"always",
"confident",
"never"
]
}
},
"relation_type": {
"name": "type",
"in": "query",
"description": "Relation type. Multiple values may be separated using a comma.",
"required": false,
"schema": {
"type": "string",
"enum": [
"edit",
"attachment",
"duplicate"
]
}
},
"parent-2": {
"name": "parent",
"in": "query",
"description": "ID of parent annotation. Multiple values may be separated using a comma.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"key-2": {
"name": "key",
"in": "query",
"description": "Relation key",
"required": false,
"schema": {
"type": "string"
}
},
"relationID": {
"name": "relationID",
"in": "path",
"description": "A unique integer value identifying this relation.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"queue-2": {
"name": "queue",
"in": "query",
"description": "List rules by queue ids.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"enabled": {
"name": "enabled",
"in": "query",
"description": "List only enabled/disabled rules.",
"required": false,
"schema": {
"type": "boolean"
}
},
"linked": {
"name": "linked",
"in": "query",
"description": "List only linked/unlinked rules (linked rules have more than one queue connected).",
"required": false,
"schema": {
"type": "boolean"
}
},
"actions": {
"name": "actions",
"in": "query",
"description": "Comma separated list of action types (e.g. show_message,change_queue).",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"ruleID": {
"name": "ruleID",
"in": "path",
"description": "A unique integer value identifying this rule.",
"required": true,
"schema": {
"type": "integer"
}
},
"rule": {
"name": "rule",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by rule ID (or multiple IDs, comma-separated).",
"example": "123,456"
},
"request_id-2": {
"name": "request_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by exact request ID.",
"example": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
},
"execution_result": {
"name": "execution_result",
"in": "query",
"schema": {
"type": "string",
"enum": [
"success",
"failure",
"partial_success"
]
},
"description": "Filter by execution result (or multiple values, comma-separated).",
"example": "success"
},
"trigger_event": {
"name": "trigger_event",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by trigger event (or multiple events, comma-separated).",
"example": "annotation_imported"
},
"search-4": {
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"description": "Full text search across log entry fields.",
"example": "invoice"
},
"schemaID": {
"name": "schemaID",
"in": "path",
"description": "Schema ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 31336
},
"suggestedEditID": {
"name": "suggestedEditID",
"in": "path",
"required": true,
"description": "ID of the suggested edit",
"schema": {
"type": "integer",
"format": "int64"
}
},
"taskID": {
"name": "taskID",
"in": "path",
"description": "Task ID.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"event": {
"name": "event",
"in": "query",
"description": "Event filter",
"required": false,
"schema": {
"type": "string"
}
},
"triggerID": {
"name": "triggerID",
"in": "path",
"description": "Trigger ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 1234
},
"uploadID": {
"name": "uploadID",
"in": "path",
"description": "Upload ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"username-2": {
"name": "username",
"in": "query",
"description": "Username filter",
"required": false,
"schema": {
"type": "string"
}
},
"first_name": {
"name": "first_name",
"in": "query",
"description": "First name filter",
"required": false,
"schema": {
"type": "string"
}
},
"last_name": {
"name": "last_name",
"in": "query",
"description": "Last name filter",
"required": false,
"schema": {
"type": "string"
}
},
"user_email_address": {
"name": "email",
"in": "query",
"description": "Email filter",
"required": false,
"schema": {
"type": "string"
}
},
"is_active": {
"name": "is_active",
"in": "query",
"description": "Filter by active/inactive status",
"required": false,
"schema": {
"type": "boolean"
}
},
"last_login": {
"name": "last_login",
"in": "query",
"description": "Last login date filter",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
"groups": {
"name": "groups",
"in": "query",
"description": "Filter by user groups",
"required": false,
"schema": {
"type": "string"
}
},
"deleted": {
"name": "deleted",
"in": "query",
"description": "Filter by deleted status",
"required": false,
"schema": {
"type": "boolean"
}
},
"userRoleID": {
"name": "userRoleID",
"in": "path",
"description": "A unique integer value identifying this user role.",
"required": true,
"schema": {
"type": "integer"
}
},
"workflowID": {
"name": "workflowID",
"in": "path",
"description": "Workflow ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"workflow_run": {
"name": "workflow_run",
"in": "query",
"description": "ID of a workflow run to filter workflow activities by",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"assignees-2": {
"name": "assignees",
"in": "query",
"description": "ID of a user to filter workflow activities by assignees",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"action-2": {
"name": "action",
"in": "query",
"description": "Filter workflow activities by action type",
"required": false,
"schema": {
"type": "string",
"enum": [
"step_started",
"step_completed",
"approved",
"rejected",
"workflow_started",
"workflow_completed",
"reassigned"
]
}
},
"workflowActivityID": {
"name": "workflowActivityID",
"in": "path",
"description": "ID of a workflow activity.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
"current_step": {
"name": "current_step",
"in": "query",
"description": "ID of the current workflow step to filter by",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
"workflow_status": {
"name": "workflow_status",
"in": "query",
"description": "Status of the workflow run to filter by",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
}
},
"workflowRunID": {
"name": "workflowRunID",
"in": "path",
"description": "A unique integer value identifying this workflow run.",
"required": true,
"schema": {
"type": "integer"
}
},
"workflow": {
"name": "workflow",
"in": "query",
"description": "ID of the workflow to filter workflow steps by",
"required": false,
"schema": {
"type": "integer"
}
},
"mode": {
"name": "mode",
"in": "query",
"description": "Mode of the workflow step to filter by",
"required": false,
"schema": {
"type": "string",
"enum": [
"any",
"all",
"auto"
]
}
},
"workflow_step_type": {
"name": "type",
"in": "query",
"description": "Type of the workflow step to filter by",
"required": false,
"schema": {
"type": "string",
"enum": [
"approval"
]
}
},
"workflowStepID": {
"name": "workflowStepID",
"in": "path",
"description": "A unique integer value identifying this workflow step.",
"required": true,
"schema": {
"type": "integer"
}
},
"noteID": {
"name": "noteID",
"in": "path",
"description": "Note ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
},
"schemas": {
"pagination": {
"type": "object",
"properties": {
"next": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "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.",
"example": null
},
"previous": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "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.",
"example": null
}
}
},
"document_url": {
"type": "string",
"format": "uri",
"description": "Document URL.",
"example": "https://example.rossum.app/api/v1/documents/456700"
},
"queue_url": {
"type": "string",
"format": "uri",
"description": "Queue URL.",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"creator": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that created the object.",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of object's creation.",
"example": "2021-04-26T10:08:03.856648Z"
},
"modified_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that last modified the object.",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"modified_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp of last modification.",
"example": "2021-04-26T10:08:03.856648Z"
},
"metadata": {
"type": "object",
"description": "Client data. May be used to store e.g. external system object IDs. See [Metadata](#tag/Overview/Metadata) for more details.",
"example": {
"some_key": "some_value"
},
"default": {}
},
"organization_url": {
"type": "string",
"format": "uri",
"description": "Organization URL.",
"example": "https://example.rossum.app/api/v1/organizations/406"
},
"assignees": {
"type": "array",
"x-beta": true,
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of assigned users.",
"example": [
"https://example.rossum.app/api/v1/users/1",
"https://example.rossum.app/api/v1/users/2"
]
},
"annotation": {
"type": "object",
"title": "Annotation object",
"x-tags": [
"Annotation"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the annotation.",
"example": 314528
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the annotation.",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"status": {
"type": "string",
"enum": [
"confirmed",
"created",
"deleted",
"exported",
"exporting",
"failed_export",
"failed_import",
"importing",
"in_workflow",
"postponed",
"purged",
"rejected",
"reviewing",
"split",
"to_review"
],
"description": "Status of the document, see [Annotation Lifecycle](/guides/annotation-lifecycle) for more details.",
"example": "to_review"
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "Related [document](/api/document)."
}
]
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
},
{
"description": "A [queue](/api/queue) that annotation belongs to."
}
]
},
"schema": {
"type": "string",
"format": "uri",
"description": "A [schema](/api/schema) that defines content shape.",
"example": "https://example.rossum.app/api/v1/schemas/31336"
},
"relations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"deprecated": true,
"description": "List of relations that annotation belongs to.",
"example": []
},
"pages": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of rendered [pages](/api/page.)",
"example": [
"https://example.rossum.app/api/v1/pages/558598"
]
},
"creator": {
"$ref": "#/components/schemas/creator"
},
"created_at": {
"$ref": "#/components/schemas/created_at"
},
"modifier": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "User that last modified the annotation.",
"example": null
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
},
"assigned_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp of last assignment to a user or when the annotation was started being annotated.",
"example": null
},
"confirmed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp when the annotation was moved to status `confirmed`.",
"example": null
},
"deleted_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp when the annotation was moved to status `deleted`.",
"example": null
},
"exported_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp of finished export.",
"example": null
},
"export_failed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp of failed export.",
"example": null
},
"purged_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp when was annotation purged.",
"example": null
},
"rejected_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp when the annotation was moved to status `rejected`.",
"example": null
},
"confirmed_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that confirmed the annotation.",
"example": null
},
"deleted_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that deleted the annotation.",
"example": null
},
"exported_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that exported the annotation.",
"example": null
},
"purged_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that purged the annotation.",
"example": null
},
"rejected_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that rejected the annotation.",
"example": null
},
"rir_poll_id": {
"type": [
"string",
"null"
],
"description": "Internal identifier used by Rossum.",
"example": "54f6b9ecfa751789f71ddf12"
},
"messages": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"id": {
"type": [
"integer",
"null"
]
},
"type": {
"type": "string",
"enum": [
"error",
"warning",
"info"
]
}
}
},
"description": "List of messages from the connector (save).",
"default": [],
"example": null
},
"content": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Link to annotation content (datapoint values), see [Annotation Content](/api/annotation-content.)",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"suggested_edit": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "Link to [Suggested edit](/api/suggested-edit) object.",
"example": null
},
"time_spent": {
"type": "number",
"format": "float",
"description": "Total time spent while validating the annotation.",
"default": 0,
"example": 0
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"automated": {
"type": "boolean",
"description": "Whether annotation was [automated](/guides/automation)",
"default": false,
"example": false
},
"related_emails": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of [emails](/api/email) related with annotation.",
"example": []
},
"email": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "Related [email](/api/email) that the annotation was imported by (for annotations imported by email).",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"automation_blocker": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "Related [automation blocker](/api/automation-blocker) object.",
"example": null
},
"email_thread": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "Related [email thread](/api/email-thread) object.",
"example": "https://example.rossum.app/api/v1/email_threads/456"
},
"has_email_thread_with_replies": {
"type": "boolean",
"readOnly": true,
"description": "Related email thread contains more than one `incoming` email.",
"example": true
},
"has_email_thread_with_new_replies": {
"type": "boolean",
"readOnly": true,
"description": "Related email thread contains an unread `incoming` email.",
"example": false
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"automatically_rejected": {
"type": "boolean",
"readOnly": true,
"description": "Indicates whether the annotation was rejected automatically.",
"example": false
},
"prediction": {
"type": [
"object",
"null"
],
"readOnly": true,
"description": "Internal prediction data including engine version info.",
"example": null
},
"assignees": {
"$ref": "#/components/schemas/assignees"
},
"labels": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of selected [labels](/api/label.)",
"example": []
},
"restricted_access": {
"type": "boolean",
"readOnly": true,
"description": "Access to annotation is restricted.",
"default": false,
"example": false
},
"training_enabled": {
"type": "boolean",
"description": "Flag signalling whether the annotation should be used in the training of the instant learning component.",
"default": true,
"example": true
}
}
},
"assignees_writable": {
"type": "array",
"x-beta": true,
"items": {
"type": "string",
"format": "uri"
},
"description": "List of users to be added as assignees.",
"example": [
"https://example.rossum.app/api/v1/users/1",
"https://example.rossum.app/api/v1/users/2"
]
},
"edit_page": {
"type": "object",
"required": [
"page"
],
"properties": {
"page": {
"type": "string",
"format": "uri",
"description": "Page URL",
"example": "https://example.rossum.app/api/v1/pages/12345"
},
"rotation_deg": {
"type": "integer",
"enum": [
0,
90,
180,
270
],
"description": "Rotation to apply in degrees",
"example": 90
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the page is marked as deleted.",
"default": false
}
}
},
"edit_metadata": {
"type": "object",
"description": "Metadata will be saved in created/edited annotation/document metadata.",
"properties": {
"annotation": {
"type": "object",
"additionalProperties": true,
"example": {
"some_key": "some value"
}
},
"document": {
"type": "object",
"additionalProperties": true
}
}
},
"edit_pages_result": {
"type": "object",
"properties": {
"results": {
"type": "array",
"description": "Created or modified annotations",
"items": {
"type": "object",
"properties": {
"annotation": {
"type": "string",
"format": "uri",
"description": "Annotation URL",
"example": "https://example.rossum.app/api/v1/annotations/67890"
},
"document": {
"allOf": [
{
"$ref": "#/components/schemas/document_url"
},
{
"description": "Document URL"
}
]
}
}
}
}
}
},
"pagination_with_total": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of items.",
"example": 1
},
"total_pages": {
"type": "integer",
"description": "Total number of pages.",
"example": 1
},
"next": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "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.",
"example": null
},
"previous": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "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.",
"example": null
}
}
},
"edit_child_annotation": {
"type": "object",
"properties": {
"parent_pages": {
"type": "array",
"description": "Pages from parent used in this child",
"items": {
"$ref": "#/components/schemas/edit_page"
}
},
"queue": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Queue URL for the child annotation",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"status": {
"type": [
"string",
"null"
],
"description": "Current status of the child annotation",
"example": "to_review"
},
"url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the child annotation",
"example": "https://example.rossum.app/api/v1/annotations/67890"
},
"original_file_name": {
"type": "string",
"description": "File name of the original document",
"example": "large_document.pdf"
},
"values": {
"type": "object",
"description": "Edit values to be propagated to newly created annotations. Keys must be prefixed with \"edit:\",\ne.g. `\"edit:document_type\"`. [Schema Datapoint description](#tag/Document-Schema/Schema-content/)\ndescribes how it is used to initialize datapoint value.\n"
}
}
},
"validation_source": {
"type": "string",
"readOnly": true,
"enum": [
"score",
"checks",
"not_found",
"data_matching",
"history",
"connector",
"table_suggester",
"rules",
"einvoicing",
"human",
"non_required",
"NA"
]
},
"validation_sources": {
"type": "array",
"description": "See [Validation Source](#validation-source) for details.\n",
"example": [
"score"
],
"items": {
"$ref": "#/components/schemas/validation_source"
}
},
"annotation_content_base": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "A unique ID of a given object.",
"readOnly": true,
"example": 27801933
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of a given object.",
"readOnly": true,
"example": "https://example.rossum.app/api/v1/annotations/319668/content/27801933"
},
"schema_id": {
"type": "string",
"description": "Reference mapping the object to the schema tree.",
"example": "some_id"
},
"category": {
"type": "string",
"description": "Type of the object.",
"enum": [
"datapoint",
"multivalue",
"tuple"
]
},
"validation_sources": {
"$ref": "#/components/schemas/validation_sources"
},
"time_spent": {
"type": "number",
"format": "float",
"description": "Time spent while actively working on a given node, in seconds."
},
"time_spent_overall": {
"type": "number",
"format": "float",
"description": "Total time spent while validating a given node, in seconds. Only for internal purposes."
},
"hidden": {
"type": "boolean",
"description": "If set to true, the datapoint is not visible in the user interface, but remains stored in the database."
}
}
},
"annotation_content_datapoint_content": {
"type": "object",
"description": "A dictionary of the writable attributes of a given datapoint. Can be null for datapoints of type `button`.",
"example": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"properties": {
"value": {
"type": "string",
"description": "The extracted data of a given node. Maximum length: 1500 UTF characters."
},
"normalized_value": {
"type": [
"string",
"null"
],
"description": "Normalized value for date (in ISO 8601 format) and number fields (in JSON number format)."
},
"page": {
"type": [
"integer",
"null"
],
"description": "Number of page where the data is situated (see position)."
},
"position": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"format": "float"
},
"minItems": 4,
"maxItems": 4,
"description": "List of the coordinates of the label box of the given node. (left, top, right, bottom)"
},
"rir_text": {
"type": [
"string",
"null"
],
"description": "The extracted text, used as a reference for data extraction models.",
"readOnly": true
},
"rir_raw_text": {
"type": [
"string",
"null"
],
"description": "Raw extracted text (only for internal purposes, may be removed in the future).",
"readOnly": true
},
"rir_page": {
"type": [
"integer",
"null"
],
"description": "The extracted page, used as a reference for data extraction models.",
"readOnly": true
},
"rir_position": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"minItems": 4,
"maxItems": 4,
"description": "The extracted position, used as a reference for data extraction models. (left, top, right, bottom)",
"readOnly": true
},
"rir_confidence": {
"type": [
"number",
"null"
],
"format": "float",
"description": "Confidence (estimated probability) that this field was extracted correctly.",
"readOnly": true
},
"connector_text": {
"type": [
"string",
"null"
],
"description": "Text set by the connector.",
"readOnly": true
},
"connector_position": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"description": "Position set by the connector. (left, top, right, bottom)",
"readOnly": true
},
"ocr_text": {
"type": [
"string",
"null"
],
"description": "Value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)",
"readOnly": true
},
"ocr_raw_text": {
"type": [
"string",
"null"
],
"description": "Raw value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)",
"readOnly": true
},
"ocr_position": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"minItems": 4,
"maxItems": 4,
"description": "OCR position, if applicable. (left, top, right, bottom) (only for internal purposes, may be removed in the future)",
"readOnly": true
}
}
},
"annotation_content_datapoint": {
"description": "A datapoint with a single value.",
"title": "datapoint",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/annotation_content_base"
},
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"datapoint"
]
},
"schema_id": {
"example": "item_amount"
},
"id": {
"example": 27801933
},
"url": {
"example": "https://example.rossum.app/api/v1/annotations/319668/content/27801933"
},
"content": {
"$ref": "#/components/schemas/annotation_content_datapoint_content"
},
"no_recalculation": {
"type": "boolean",
"description": "If set to true, the datapoint's formula is not recalculated automatically. Only available for datapoint category editable formula datapoints.",
"example": false
}
}
}
]
},
"annotation_content_tuple": {
"description": "A container for a set of related datapoints, representing a table row. Must be nested within a multivalue.",
"title": "tuple",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/annotation_content_base"
},
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"tuple"
]
},
"schema_id": {
"example": "line_items_row"
},
"id": {
"example": 27801932
},
"url": {
"example": "https://example.rossum.app/api/v1/annotations/319668/content/27801932"
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/annotation_content_datapoint"
}
}
}
}
]
},
"annotation_content_grid": {
"type": "object",
"description": "Defines the grid structure for a multivalue object.",
"example": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"properties": {
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "A unique ID of a given object."
},
"columns": {
"type": "array",
"description": "Grid columns.",
"items": {
"type": "object",
"description": "Grid column.",
"properties": {
"left_position": {
"type": "number",
"format": "float",
"description": "Position of the column left edge."
},
"schema_id": {
"type": [
"string",
"null"
],
"description": "Reference to datapoint schema id. Used in grid-to-table conversion."
},
"header_texts": {
"type": "array",
"description": "Extracted texts from column headers.",
"items": {
"type": "string"
}
}
}
}
},
"rows": {
"type": "array",
"description": "Grid rows.",
"items": {
"type": "object",
"description": "Grid row.",
"properties": {
"top_position": {
"type": "number",
"format": "float",
"description": "Position of the row top edge."
},
"tuple_id": {
"type": [
"number",
"null"
],
"description": "ID of the corresponding tuple datapoint if it exists else null."
},
"type": {
"type": [
"string",
"null"
],
"description": "Row type. Allowed values are specified in the schema. If `null`, the row is ignored\nduring grid-to-table conversion.\n"
}
}
}
},
"width": {
"type": "number",
"format": "float",
"description": "Total width of the grid."
},
"height": {
"type": "number",
"format": "float",
"description": "Total height of the grid."
}
}
}
}
}
},
"annotation_content_multivalue": {
"description": "A container for a list of datapoints or tuples, used to represent recurring items or table rows.",
"title": "multivalue",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/annotation_content_base"
},
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"multivalue"
]
},
"schema_id": {
"example": "line_items"
},
"id": {
"example": 27801931
},
"url": {
"example": "https://example.rossum.app/api/v1/annotations/319668/content/27801931"
},
"children": {
"type": "array",
"items": {
"type": "object",
"description": "Represents a datapoint or tuple object within the multivalue context.",
"oneOf": [
{
"$ref": "#/components/schemas/annotation_content_tuple"
},
{
"$ref": "#/components/schemas/annotation_content_datapoint"
}
]
}
},
"grid": {
"$ref": "#/components/schemas/annotation_content_grid"
},
"time_spent_grid": {
"type": "number",
"format": "float",
"description": "Total time spent while actively working on a grid, in seconds. Only for internal purposes.",
"readOnly": true
},
"time_spent_grid_overall": {
"type": "number",
"format": "float",
"description": "Total time spent while validating a given grid, in seconds. Only for internal purposes.",
"readOnly": true
}
}
}
]
},
"annotation_content_section": {
"type": "object",
"description": "Represents a section within the annotation content.",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "A unique ID of a given section.",
"readOnly": true,
"example": 197466
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the section.",
"readOnly": true,
"example": "https://example.rossum.app/api/v1/annotations/319668/content/197466"
},
"schema_id": {
"type": "string",
"description": "Reference mapping the object to the schema tree.",
"example": "invoice_info_section"
},
"category": {
"type": "string",
"description": "The category of the object, which is 'section'.",
"enum": [
"section"
]
},
"children": {
"type": "array",
"description": "Datapoints, multivalues and tuples that belong to the section.",
"items": {
"type": "object",
"description": "Represents a datapoint, multivalue, or tuple object within the annotation content.",
"oneOf": [
{
"$ref": "#/components/schemas/annotation_content_multivalue"
},
{
"$ref": "#/components/schemas/annotation_content_tuple"
},
{
"$ref": "#/components/schemas/annotation_content_datapoint"
}
]
}
}
}
},
"annotation_content": {
"type": "object",
"title": "Annotation Content object",
"x-tags": [
"Annotation Content"
],
"properties": {
"content": {
"type": "array",
"description": "Represents the full content of an annotation, composed of sections and datapoints.\n",
"items": {
"$ref": "#/components/schemas/annotation_content_section"
}
}
}
},
"value": {
"type": "string",
"description": "The extracted data of a given node. Maximum length: 1500 UTF characters."
},
"normalized_value": {
"type": [
"string",
"null"
],
"description": "When both value and normalized_value are specified, they must match, otherwise datapoint won't be modified (this may be changed in the future)."
},
"position": {
"type": "array",
"items": {
"type": "number",
"format": "float"
},
"minItems": 4,
"maxItems": 4,
"description": "List of the coordinates of the label box of the given node. (left, top, right, bottom)"
},
"page": {
"type": "integer",
"description": "Number of page where the data is situated (see position)."
},
"validation_sources-2": {
"type": "array",
"description": "Optional list of validation sources to set for all fields of the row by default",
"items": {
"type": "string"
}
},
"hidden": {
"type": "boolean",
"description": "If set to true, the datapoint is not visible in the user interface, but remains stored in the database."
},
"options": {
"type": "array",
"description": "Enum option object with value and label.",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "Value of the option."
},
"label": {
"type": "string",
"description": "User-friendly label for the option, shown in the UI."
}
}
}
},
"operation_replace": {
"type": "object",
"description": "Replace operation to update a datapoint value or other supported attributes",
"properties": {
"op": {
"type": "string",
"enum": [
"replace"
],
"description": "Type of operation"
},
"id": {
"type": "integer",
"description": "Datapoint id"
},
"value": {
"type": "object",
"description": "Updated data. Only `value`, `position`, `page`, `validation_sources`, `hidden` and `options` attributes may be updated.\nPlease note that `value` is parsed and formatted. When both `value` and `normalized_value` are specified,\nthey must match, otherwise datapoint won't be modified.\n",
"properties": {
"content": {
"type": "object",
"properties": {
"value": {
"$ref": "#/components/schemas/value"
},
"normalized_value": {
"$ref": "#/components/schemas/normalized_value"
},
"position": {
"$ref": "#/components/schemas/position"
},
"page": {
"$ref": "#/components/schemas/page"
}
}
},
"validation_sources": {
"$ref": "#/components/schemas/validation_sources-2"
},
"hidden": {
"$ref": "#/components/schemas/hidden"
},
"options": {
"$ref": "#/components/schemas/options"
}
}
}
},
"required": [
"op",
"id",
"value"
]
},
"operation_add": {
"type": "object",
"description": "Add operation to add a new row into a table multivalue or add one child datapoint to simple multivalue",
"properties": {
"op": {
"type": "string",
"enum": [
"add"
],
"description": "Type of operation"
},
"id": {
"type": "integer",
"description": "Multivalue id (parent of new datapoint)"
},
"value": {
"oneOf": [
{
"type": "array",
"description": "List of objects for adding a row to table multivalue",
"items": {
"type": "object",
"properties": {
"schema_id": {
"type": "string",
"description": "Reference to schema (required)"
},
"content": {
"type": "object",
"properties": {
"value": {
"$ref": "#/components/schemas/value"
},
"normalized_value": {
"$ref": "#/components/schemas/normalized_value"
},
"position": {
"$ref": "#/components/schemas/position"
},
"page": {
"$ref": "#/components/schemas/page"
}
}
},
"validation_sources": {
"$ref": "#/components/schemas/validation_sources-2"
},
"hidden": {
"$ref": "#/components/schemas/hidden"
},
"options": {
"$ref": "#/components/schemas/options"
}
},
"required": [
"schema_id"
]
}
},
{
"type": "object",
"description": "Object for adding one child datapoint to simple multivalue",
"properties": {
"content": {
"type": "object",
"properties": {
"value": {
"$ref": "#/components/schemas/value"
},
"normalized_value": {
"$ref": "#/components/schemas/normalized_value"
},
"position": {
"$ref": "#/components/schemas/position"
},
"page": {
"$ref": "#/components/schemas/page"
}
}
},
"validation_sources": {
"$ref": "#/components/schemas/validation_sources-2"
},
"hidden": {
"$ref": "#/components/schemas/hidden"
},
"options": {
"$ref": "#/components/schemas/options"
}
}
}
]
}
},
"required": [
"op",
"id",
"value"
]
},
"operation_remove": {
"type": "object",
"description": "Remove operation to remove a row from a multivalue. Only multivalue children datapoints may be removed.",
"properties": {
"op": {
"type": "string",
"enum": [
"remove"
],
"description": "Type of operation"
},
"id": {
"type": "integer",
"description": "Datapoint id to remove"
}
},
"required": [
"op",
"id"
]
},
"bulk_operations_request": {
"type": "object",
"properties": {
"operations": {
"type": "array",
"description": "List of operations to perform on annotation content",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/operation_replace"
},
{
"$ref": "#/components/schemas/operation_add"
},
{
"$ref": "#/components/schemas/operation_remove"
}
]
}
}
},
"required": [
"operations"
]
},
"grid_part": {
"type": "object",
"description": "A single grid part representing table structure on a page",
"properties": {
"page": {
"type": "integer",
"description": "Page number"
},
"columns": {
"type": "array",
"description": "Description of grid columns",
"items": {
"type": "object",
"properties": {
"left_position": {
"type": "number",
"description": "Position of the column left edge"
},
"schema_id": {
"type": "string",
"description": "Reference to datapoint schema id"
},
"header_texts": {
"type": "array",
"description": "Extracted texts from column headers",
"items": {
"type": "string"
}
}
},
"required": [
"left_position",
"schema_id"
]
}
},
"rows": {
"type": "array",
"description": "Description of grid rows",
"items": {
"type": "object",
"properties": {
"top_position": {
"type": "number",
"description": "Position of the row top edge"
},
"tuple_id": {
"type": [
"integer",
"null"
],
"description": "ID of the corresponding tuple datapoint if it exists else null"
},
"type": {
"type": [
"string",
"null"
],
"description": "Row type. If null, the row is ignored during grid-to-table conversion"
},
"tuple_index": {
"type": "integer",
"description": "Index for tuple_id re-mapping after creation of a new row (internal use)"
}
},
"required": [
"top_position"
]
}
},
"width": {
"type": "number",
"description": "Total width of the grid"
},
"height": {
"type": "number",
"description": "Total height of the grid"
}
},
"required": [
"page",
"columns",
"rows"
]
},
"grid_operations_request": {
"type": "object",
"description": "Request to apply multiple operations on multiple grids for one multivalue",
"properties": {
"operations": {
"type": "array",
"description": "List of operations to apply to the grid",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"update",
"delete",
"create"
],
"description": "Type of operation"
},
"grid_index": {
"type": "integer",
"description": "Index of the grid"
},
"grid": {
"$ref": "#/components/schemas/grid_part"
}
},
"required": [
"op",
"grid_index"
]
}
}
},
"required": [
"operations"
]
},
"grid_parts_operations_request": {
"type": "object",
"description": "Request to apply multiple operations on a grid and perform OCR on modified cell datapoints",
"properties": {
"grid_index": {
"type": "integer",
"description": "Index of the grid part"
},
"grid": {
"$ref": "#/components/schemas/grid_part"
},
"operations": {
"type": "object",
"description": "Operations to apply to the grid",
"properties": {
"rows": {
"type": "array",
"description": "List of row operations",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"update",
"delete",
"create"
],
"description": "Type of operation"
},
"row_index": {
"type": "integer",
"description": "Required for row update and create operations"
},
"tuple_id": {
"type": "integer",
"description": "ID of the tuple datapoint, required for row delete and update operations"
},
"schema_id": {
"type": "string",
"description": "ID of the schema, required for column operations"
}
},
"required": [
"op"
]
}
},
"columns": {
"type": "array",
"description": "List of column operations",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"update",
"delete"
],
"description": "Type of operation"
},
"schema_id": {
"type": "string",
"description": "ID of the schema (required)"
}
},
"required": [
"op",
"schema_id"
]
}
}
}
}
},
"required": [
"grid_index",
"grid",
"operations"
]
},
"select_request": {
"type": "object",
"description": "Request to replace annotation content by OCR extracted from a rectangle",
"properties": {
"rectangle": {
"type": "array",
"description": "Bounding box of an occurrence (left, top, right, bottom)",
"items": {
"type": "number"
},
"minItems": 4,
"maxItems": 4
},
"page": {
"type": "string",
"format": "uri",
"description": "URL of the page of the occurrence"
}
},
"required": [
"rectangle",
"page"
]
},
"audit_log_content": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Partial URL path of the request",
"example": "api/v1/users/131"
},
"method": {
"type": "string",
"description": "Method of the request",
"example": "PATCH"
},
"request_id": {
"type": "string",
"description": "ID of the request. Use this when contacting Rossum support with any related questions",
"example": "0aadfd75-8dcz-4e62-94d9-a23811d0d0b0"
},
"status_code": {
"type": "integer",
"description": "Status code of the response",
"example": 200
},
"details": {
"type": "object",
"description": "Details about the request (if available). For most cases, this field will be `{}`",
"properties": {
"payload": {
"type": "object",
"description": "Payload details of the request",
"properties": {
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "Name of the user roles that were sent (if sent) in a request on a user object",
"example": [
"admin"
]
}
}
}
}
}
}
},
"audit_log": {
"type": "object",
"title": "Audit Log object",
"x-tags": [
"Audit Log"
],
"properties": {
"organization_id": {
"type": "integer",
"readOnly": true,
"description": "ID of the organization",
"example": 406
},
"timestamp": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of the log record.\n",
"example": "2024-07-01T07:00:00.000000Z"
},
"username": {
"type": "string",
"readOnly": true,
"description": "Username of the user that performed the action",
"example": "john.doe@example.com"
},
"object_id": {
"type": "integer",
"readOnly": true,
"description": "ID of the object on which the action was performed",
"example": 131
},
"object_type": {
"type": "string",
"readOnly": true,
"description": "Type of the object on which the action was performed",
"enum": [
"document",
"annotation",
"user"
],
"example": "user"
},
"action": {
"type": "string",
"readOnly": true,
"description": "Type of the action performed.\n\nEach `object_type` has different actions available.\n\n| object_type | Available actions |\n|-------------|-------------------|\n| document | create |\n| annotation | update-status |\n| user | create, delete, purge, update, destroy, app_load, reset-password, change-password |\n\n\n`app_load` value represents records of when `api/v1/auth/user` endpoint was called.\n\n",
"example": "update"
},
"content": {
"$ref": "#/components/schemas/audit_log_content"
}
}
},
"automation_blocker": {
"type": "object",
"title": "Automation Blocker object",
"x-tags": [
"Automation Blocker"
],
"example": {
"id": 1,
"url": "https://example.rossum.app/api/v1/automation_blockers/1",
"annotation": "https://example.rossum.app/api/v1/annotations/4",
"content": [
{
"level": "datapoint",
"type": "low_score",
"schema_id": "invoice_id",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 1234,
"details": {
"score": 0.901,
"threshold": 0.975
}
},
{
"datapoint_id": 1235,
"details": {
"score": 0.968,
"threshold": 0.975
}
}
]
},
{
"level": "datapoint",
"type": "failed_checks",
"schema_id": "schema_id",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 43,
"details": {
"validation": "bad"
}
}
]
},
{
"level": "datapoint",
"type": "no_validation_sources",
"schema_id": "schema_id",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 412
}
]
},
{
"level": "annotation",
"type": "error_message",
"details": {
"message_content": [
"annotation error"
]
}
},
{
"level": "datapoint",
"type": "error_message",
"schema_id": "schema_id",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 45,
"details": {
"message_content": [
"longer than 3 characters"
]
}
}
]
},
{
"level": "annotation",
"type": "delete_recommendation_filename",
"details": {
"message_content": [
"annotation error"
]
}
},
{
"level": "datapoint",
"type": "delete_recommendation_field",
"schema_id": "document_type",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 45
}
]
},
{
"level": "annotation",
"type": "extension",
"details": {
"content": [
"PO not found in the master data!"
]
}
},
{
"level": "datapoint",
"type": "extension",
"schema_id": "sender_name",
"samples_truncated": false,
"samples": [
{
"datapoint_id": 1357,
"details": {
"content": [
"Unregistered vendor"
]
}
}
]
}
]
},
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "AutomationBlocker object ID",
"example": 1
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "AutomationBlocker object URL",
"example": "https://example.rossum.app/api/v1/automation_blockers/1"
},
"annotation": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of related Annotation object",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"content": {
"type": "array",
"description": "List of reasons why automation is blocked",
"items": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"datapoint",
"annotation"
],
"description": "Designates whether automation blocker relates to specific `datapoint` or to the whole `annotation`",
"example": "datapoint"
},
"type": {
"type": "string",
"enum": [
"automation_disabled",
"is_duplicate",
"suggested_edit_present",
"low_score",
"failed_checks",
"no_validation_sources",
"error_message",
"delete_recommendation_filename",
"delete_recommendation_page_count",
"delete_recommendation_field",
"extension",
"human_confirmation_required"
],
"description": "Type of automation blocker",
"example": "low_score"
},
"schema_id": {
"type": [
"string",
"null"
],
"description": "Only for `datapoint` level objects",
"example": "invoice_id"
},
"samples": {
"type": "array",
"items": {
"type": "object",
"properties": {
"datapoint_id": {
"type": "integer",
"description": "ID of the datapoint",
"example": 1234
},
"details": {
"type": "object",
"description": "Additional details specific to the blocker type",
"additionalProperties": true
}
},
"description": "Contains sample of specific datapoints with detailed info (only for `datapoint` level objects). Only first 10 samples are listed"
}
},
"samples_truncated": {
"type": [
"boolean",
"null"
],
"description": "Whether number samples were truncated to 10, or contains all of them",
"example": false
},
"details": {
"type": [
"object",
"null"
],
"description": "Only for `level`: `annotation` with `type`: `error_message`.",
"properties": {
"message_content": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of error messages",
"example": [
"Error 1"
]
}
}
}
}
}
}
}
},
"connector": {
"type": "object",
"title": "Connector object",
"x-tags": [
"Connector"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the connector",
"example": 1500
},
"name": {
"type": "string",
"description": "Name of the connector (not visible in UI)",
"example": "MyQ Connector"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the connector",
"example": "https://example.rossum.app/api/v1/connectors/1500"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of queues that use connector object",
"example": [
"https://example.rossum.app/api/v1/queues/8199"
]
},
"service_url": {
"type": "string",
"format": "uri",
"description": "URL of the connector endpoint",
"example": "https://myq.east-west-trading.com"
},
"params": {
"type": [
"string",
"null"
],
"description": "Query params appended to the service_url",
"example": "strict=true"
},
"client_ssl_certificate": {
"type": [
"string",
"null"
],
"description": "Client SSL certificate used to authenticate requests. Must be PEM encoded.",
"example": "-----BEGIN CERTIFICATE-----\n..."
},
"client_ssl_key": {
"type": [
"string",
"null"
],
"writeOnly": true,
"description": "Client SSL key (write only). Must be PEM encoded. Key may not be encrypted."
},
"authorization_type": {
"type": "string",
"description": "String sent in HTTP header `Authorization` could be set to `secret_key` or `Basic`. For details see [Connector API](/guides/extensions#connector-extension).",
"default": "secret_key",
"enum": [
"secret_key",
"Basic"
],
"example": "secret_key"
},
"authorization_token": {
"type": "string",
"description": "Token sent to connector in `Authorization` header to ensure connector was contacted by Rossum (displayed only to `admin` user).",
"example": "wuNg0OenyaeK4eenOovi7aiF"
},
"asynchronous": {
"type": "boolean",
"description": "Affects exporting: when `true`, [confirm](/api/annotation#confirm-validation) endpoint returns immediately and connector's `save` endpoint is called asynchronously later on.",
"default": true,
"example": true
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"dedicated_engine": {
"type": "object",
"title": "Dedicated Engine object",
"x-tags": [
"Dedicated Engine"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true,
"description": "ID of the engine",
"example": 3000
},
"name": {
"type": "string",
"description": "Name of the engine",
"example": "Dedicated engine 1"
},
"description": {
"type": "string",
"description": "Description of the engine",
"example": "AI engine trained to recognize data for the specific data capture requirement"
},
"url": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the engine",
"example": "https://example.rossum.app/api/v1/dedicated_engines/3000"
},
"status": {
"type": "string",
"readOnly": true,
"description": "Current status of the engine. If status is not `draft`, the whole engine and its schema become read-only.",
"enum": [
"draft",
"schema_review",
"annotating_initial",
"annotating_review",
"annotating_training",
"training_started",
"training_finished",
"retraining",
"sample_review"
],
"default": "draft",
"example": "draft"
},
"schema": {
"type": [
"string",
"null"
],
"format": "url",
"description": "Related dedicated engine schema URL",
"example": "https://example.rossum.app/api/v1/dedicated_engine_schemas/6000"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"readOnly": true,
"description": "List of queues using this dedicated engine",
"example": []
}
}
},
"dedicated_engine_request": {
"type": "object",
"properties": {
"document_type": {
"type": "string",
"description": "Type of the document the engine should predict",
"example": "Custom invoice"
},
"document_language": {
"type": "string",
"description": "Language of the documents",
"example": "en-US"
},
"volume": {
"type": "integer",
"description": "Estimated volume per year",
"example": 9
},
"sample_uploads": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"description": "Multiple sample files of the documents"
}
},
"required": [
"document_type",
"document_language",
"volume"
]
},
"source": {
"type": "object",
"properties": {
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
},
{
"description": "Queue to map the field from. Only one Queue per engine output is allowed."
}
]
},
"schema_id": {
"type": "string",
"description": "ID of the field to map. The id must exist in the mapped Queue's schema.",
"example": "document_id"
}
}
},
"engine_datapoint": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"datapoint"
],
"description": "Category of the object.",
"example": "datapoint"
},
"engine_output_id": {
"type": "string",
"description": "Name of the new extracted field in the trained Dedicated Engine.",
"example": "document_id"
},
"label": {
"type": "string",
"description": "User-friendly label for an object, shown in the user interface.",
"example": "Document ID"
},
"trained": {
"type": "boolean",
"readOnly": true,
"description": "Whether the field was successfully trained.",
"example": true
},
"type": {
"type": "string",
"enum": [
"number",
"string",
"date",
"enum"
],
"description": "Type of the trained field.",
"example": "string"
},
"description": {
"type": "string",
"description": "Description of field attribute.",
"example": "Document number"
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/source"
},
"description": "Mapping describing the source Queues and their fields to train this field from."
}
}
},
"engine_tuple": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"tuple"
],
"description": "Category of the object.",
"example": "tuple"
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/engine_datapoint"
},
"description": "Array specifying objects that belong to a given tuple. It may contain only objects with category `datapoint`."
}
}
},
"multivalue_with_tuple": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"multivalue"
],
"description": "Category of the object.",
"example": "multivalue"
},
"engine_output_id": {
"type": "string",
"description": "Unique name of the new extracted field in the trained Dedicated Engine.",
"example": "line_items"
},
"label": {
"type": "string",
"description": "User-friendly label for an object, shown in the user interface.",
"example": "Line Items"
},
"trained": {
"type": "boolean",
"readOnly": true,
"description": "Whether the field was successfully trained.",
"example": true
},
"type": {
"type": "string",
"enum": [
"grid",
"freeform"
],
"description": "Type of the trained field.",
"example": "grid"
},
"description": {
"type": "string",
"description": "Description of field attribute.",
"example": "Line item column types."
},
"children": {
"$ref": "#/components/schemas/engine_tuple",
"description": "Object specifying type of children. It may contain only objects with category `tuple`."
}
}
},
"multivalue_with_datapoint": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"multivalue"
],
"description": "Category of the object.",
"example": "multivalue"
},
"children": {
"$ref": "#/components/schemas/engine_datapoint",
"description": "Object specifying type of children. It may contain only objects with category `datapoint`."
}
}
},
"field": {
"oneOf": [
{
"$ref": "#/components/schemas/multivalue_with_tuple"
},
{
"$ref": "#/components/schemas/multivalue_with_datapoint"
},
{
"$ref": "#/components/schemas/engine_datapoint"
}
],
"description": "Field object that can be either multivalue (with tuple or datapoint children) or datapoint category."
},
"engine_content": {
"type": "object",
"properties": {
"training_queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of Queues that will be used for the training. Note that queues can't have `delete_after` field set, otherwise a validation error is raised.",
"example": [
"https://example.rossum.app/api/v1/queues/123",
"https://example.rossum.app/api/v1/queues/200",
"https://example.rossum.app/api/v1/queues/321"
]
},
"fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/field"
},
"description": "Container for fields declarations. It may contain only objects of category `multivalue` or `datapoint`."
}
}
},
"dedicated_engine_schema": {
"type": "object",
"title": "Dedicated Engine Schema object",
"x-tags": [
"Dedicated Engine Schema"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the engine schema.",
"example": 6000
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the engine schema.",
"example": "https://example.rossum.app/api/v1/dedicated_engine_schemas/6000"
},
"content": {
"$ref": "#/components/schemas/engine_content"
}
}
},
"predict_request": {
"type": "object",
"properties": {
"training_queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of Queues that will be used for the training.",
"example": [
"https://example.rossum.app/api/v1/queues/123",
"https://example.rossum.app/api/v1/queues/200",
"https://example.rossum.app/api/v1/queues/321"
]
}
},
"required": [
"training_queues"
]
},
"predict_response": {
"type": "object",
"properties": {
"content": {
"$ref": "#/components/schemas/engine_content"
}
}
},
"validate_request": {
"type": "object",
"properties": {
"content": {
"$ref": "#/components/schemas/engine_content"
}
},
"required": [
"content"
]
},
"delete_recommendation": {
"type": "object",
"title": "Delete Recommendation object",
"x-tags": [
"Delete Recommendation"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the delete recommendation",
"example": 1244
},
"enabled": {
"type": "boolean",
"description": "Whether the associated triggers' rules should be active",
"example": true
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the delete recommendation",
"example": "https://example.rossum.app/api/v1/delete_recommendations/1244"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url",
"description": "URL of the associated queue"
}
]
},
"triggers": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "URLs of the associated triggers",
"example": [
"https://example.rossum.app/api/v1/triggers/500"
]
}
}
},
"document_attachment_status": {
"type": [
"string",
"null"
],
"description": "Reason why the Document got filtered out on Email ingestion.",
"readOnly": true,
"example": "processed",
"enum": [
null,
"filtered_by_inbox_resolution",
"filtered_by_inbox_size",
"filtered_by_inbox_mime_type",
"filtered_by_inbox_file_name",
"filtered_by_hook_custom",
"filtered_by_queue_mime_type",
"hook_additional_file",
"filtered_by_insecure_mime_type",
"extracted_archive",
"failed_to_extract",
"processed",
"password_protected_archive",
"broken_image"
]
},
"document": {
"type": "object",
"title": "Document object",
"x-tags": [
"Document"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true,
"description": "ID of the document",
"example": 314628
},
"url": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the document",
"example": "https://example.rossum.app/api/v1/documents/314628"
},
"s3_name": {
"type": "string",
"readOnly": true,
"description": "Storage key of the document file. Internal use only.",
"example": "272c2f01ae84a4e19a421cb432e490bb"
},
"parent": {
"type": [
"string",
"null"
],
"format": "url",
"readOnly": true,
"description": "URL of the parent document (e.g. the zip file it was extracted from)",
"example": "https://example.rossum.app/api/v1/documents/203517"
},
"email": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the email object that document was imported by (only for document imported by email).",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"readOnly": true,
"description": "List of annotations related to the document. Usually there is only one annotation.",
"example": [
"https://example.rossum.app/api/v1/annotations/314528"
]
},
"mime_type": {
"type": "string",
"readOnly": true,
"description": "MIME type of the document (e.g. `application/pdf`)",
"example": "application/pdf"
},
"creator": {
"type": [
"string",
"null"
],
"format": "url",
"readOnly": true,
"description": "User that created the annotation.",
"example": "https://example.rossum.app/api/v1/users/1"
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of document upload or incoming email attachment extraction.",
"example": "2020-05-21T12:34:56.789Z"
},
"arrived_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "See `created_at`",
"deprecated": true,
"example": "2020-05-21T12:34:56.789Z"
},
"original_file_name": {
"type": "string",
"readOnly": true,
"description": "File name of the attachment or upload.",
"example": "invoice.pdf"
},
"content": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "Link to the document's raw content (e.g. PDF file). May be `null` if there is no file associated.",
"example": "https://example.rossum.app/api/v1/documents/314628/content"
},
"attachment_status": {
"$ref": "#/components/schemas/document_attachment_status"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
}
}
},
"documents_create": {
"type": "object",
"properties": {
"content": {
"type": "string",
"format": "binary",
"description": "The file to be uploaded."
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"parent": {
"type": "string",
"format": "url",
"description": "URL of the parent document (e.g. the original file based on which the uploaded content was created)"
}
},
"required": [
"content"
]
},
"document_relation": {
"type": "object",
"title": "Document Relation object",
"x-tags": [
"Document Relation"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the document relation",
"example": 1
},
"type": {
"type": "string",
"description": "Type of relationship. Possible values:\n- `export` - Related documents are exports of the annotation data (e.g. in XML or JSON formats).\n- `einvoice` - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)\n",
"enum": [
"export",
"einvoice"
],
"default": "export",
"example": "export"
},
"key": {
"type": [
"string",
"null"
],
"description": "Key used to distinguish several relationships of the same type.\nNote: The combination of `type`, `key` and `annotation` attribute values must be *unique*.\n",
"example": null
},
"annotation": {
"type": "string",
"format": "uri",
"description": "Annotation",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"documents": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of related documents",
"example": [
"https://example.rossum.app/api/v1/documents/124",
"https://example.rossum.app/api/v1/documents/125"
]
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the relation",
"example": "https://example.rossum.app/api/v1/document_relations/1"
}
}
},
"documents_download": {
"type": "object",
"title": "Documents Download object",
"x-tags": [
"Documents Download"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the download object",
"example": 105
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the download object",
"example": "https://example.rossum.app/api/v1/documents/456700"
},
"file_name": {
"type": "string",
"readOnly": true,
"description": "Name of the archive to be downloaded.",
"example": "test_invoice_1.pdf"
},
"expires_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of a guaranteed availability of the download object and its content. Set to the archive creation time plus 2 hours. Expired downloads are being deleted periodically.",
"example": "2023-09-13T23:04:00.933658Z"
},
"content": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "Link to the download's raw content. May be `null` if there is no archive associated yet.",
"example": "https://example.rossum.app/api/v1/documents/downloads/105/content"
}
}
},
"email_address": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address.",
"example": "john.doe@example.com"
},
"name": {
"type": [
"string",
"null"
],
"description": "Name of the email recipient.",
"example": "John Doe"
}
},
"required": [
"email"
]
},
"annotation_counts": {
"type": "object",
"description": "This attribute is intended for **INTERNAL** use only and may be changed in the future. \nInformation about how many annotations were extracted from email attachments and in which state they currently are.\n",
"properties": {
"annotations": {
"type": "integer",
"description": "Total number of annotations (Annotation status: Any)",
"example": 3
},
"annotations_processed": {
"type": "integer",
"description": "Number of processed annotations (Annotation status: exported, deleted, purged, split)",
"example": 1
},
"annotations_purged": {
"type": "integer",
"description": "Number of purged annotations (Annotation status: purged)",
"example": 0
},
"annotations_unprocessed": {
"type": "integer",
"description": "Number of not yet processed annotations (Annotation status: importing, failed_import, to_review, reviewing, confirmed, exporting, postponed, failed_export)",
"example": 1
},
"annotations_rejected": {
"type": "integer",
"description": "Number of rejected annotations (Annotation status: rejected)",
"example": 1
},
"related_annotations": {
"type": "integer",
"description": "Total number of related annotations (Annotation status: Any)",
"example": 0
}
}
},
"email": {
"type": "object",
"title": "Email object",
"x-tags": [
"Email"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the email",
"example": 1234
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the email",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
}
]
},
"inbox": {
"type": "string",
"format": "uri",
"description": "URL of the associated inbox",
"example": "https://example.rossum.app/api/v1/inboxes/1229"
},
"parent": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the parent email",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"email_thread": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "URL of the associated email thread",
"example": "https://example.rossum.app/api/v1/email_threads/456"
},
"children": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of URLs of the children emails",
"example": [
"https://example.rossum.app/api/v1/emails/1244"
]
},
"documents": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of documents attached to email",
"example": [
"https://example.rossum.app/api/v1/documents/5678"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of incoming email",
"example": "2021-03-26T14:31:46.993427Z"
},
"last_thread_email_created_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"deprecated": true,
"description": "(Deprecated) Timestamp of the most recent email in this email thread",
"example": "2021-03-27T14:29:48.665478Z"
},
"subject": {
"type": [
"string",
"null"
],
"description": "Email subject",
"example": "Some email subject"
},
"from": {
"allOf": [
{
"$ref": "#/components/schemas/email_address"
},
{
"readOnly": true,
"description": "Information about sender containing keys `email` and `name`"
}
],
"example": {
"email": "company@east-west.com",
"name": "Company East"
}
},
"to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"readOnly": true,
"description": "List that contains information about recipients",
"example": [
{
"email": "east-west-trading-co-a34f3a@example.rossum.app",
"name": "East West Trading"
}
]
},
"cc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"readOnly": true,
"description": "List that contains information about recipients of carbon copy",
"example": []
},
"bcc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"readOnly": true,
"description": "List that contains information about recipients of blind carbon copy",
"example": []
},
"body_text_plain": {
"type": [
"string",
"null"
],
"description": "Plain text email section (shortened to 4kB)",
"example": "Some body"
},
"body_text_html": {
"type": [
"string",
"null"
],
"description": "HTML email section (shortened to 4kB)",
"example": "Some body
"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"type": {
"type": "string",
"enum": [
"incoming",
"outgoing"
],
"readOnly": true,
"description": "Email type. Can be `incoming` or `outgoing`",
"example": "outgoing"
},
"annotation_counts": {
"$ref": "#/components/schemas/annotation_counts"
},
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of URLs of annotations that arrived via email",
"example": [
"https://example.rossum.app/api/v1/annotations/1",
"https://example.rossum.app/api/v1/annotations/2",
"https://example.rossum.app/api/v1/annotations/4"
]
},
"related_annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of URLs of annotations that are related to the email (e.g. rejected by that, added as attachment etc.)",
"example": []
},
"related_documents": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of URLs of documents related to the email (e.g. by forwarding email containing document as attachment etc.)",
"example": [
"https://example.rossum.app/api/v1/documents/3"
]
},
"creator": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that have sent the email. `null` if email has been received via SMTP",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"filtered_out_document_count": {
"type": "integer",
"readOnly": true,
"description": "This attribute is intended for **INTERNAL** use only and may be changed in the future without notice. \nNumber of documents automatically filtered out by Rossum smart inbox (this feature can be configured in inbox settings).\n",
"example": 2
},
"labels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"rejection",
"automatic_rejection",
"rejected",
"automatic_status_changed_info",
"forwarded",
"reply"
]
},
"description": "List of email labels. Email objects can have assigned any number of labels.\n \n| Label name | Description |\n|-------------------------------|------------------------------------------------------------------------------------------------|\n| rejection | Outgoing informative email sent by Rossum after email was manually rejected. |\n| automatic_rejection | Informative automatic email sent by Rossum when no document was extracted from incoming email. |\n| automatic_status_changed_info | Informative automatic email sent by Rossum about document status change. |\n| rejected | Incoming email rejected together with all attached documents. |\n| forwarded | Outgoing email sent by forwarding other email. |\n| reply | Outgoing email sent by replying to another email. |\n",
"example": [
"rejected"
]
},
"content": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the emails [content](/api/email#emails_content).",
"example": "https://example.rossum.app/api/v1/emails/1234"
}
}
},
"send_email_request": {
"type": "object",
"properties": {
"to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains information about recipients."
},
"cc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains information about recipients of carbon copy."
},
"bcc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains information about recipients of blind carbon copy."
},
"template_values": {
"type": "object",
"description": "Values to fill in the email template, it should always contain `subject` and `message` keys.\n",
"properties": {
"subject": {
"type": "string",
"description": "Email subject template",
"example": "Document processed"
},
"message": {
"type": "string",
"description": "Email message template (may contain HTML)",
"example": "The document was processed.
{{user_name}}
Additional notes: {{note}}
"
}
},
"additionalProperties": {
"type": "string"
},
"example": {
"subject": "Document processed",
"message": "The document was processed.
{{user_name}}
Additional notes: {{note}}
",
"note": "No issues found"
}
},
"queue": {
"$ref": "#/components/schemas/queue_url"
},
"related_annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of links to email-related annotations.",
"example": [
"https://example.rossum.app/api/v1/annotations/123"
]
},
"related_documents": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of URLs to email-related documents (on the top of `related_annotations` documents which are linked automatically).",
"example": [
"https://example.rossum.app/api/v1/documents/123"
]
},
"attachments": {
"type": "object",
"description": "Keys are attachment types (currently only `documents` key is supported), value is list of URL.",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of document URLs to attach",
"example": [
"https://example.rossum.app/api/v1/documents/123"
]
}
}
},
"parent_email": {
"type": "string",
"format": "uri",
"description": "Link to parent email.",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"reset_related_annotations_email_thread": {
"type": "boolean",
"description": "Update related annotations, so that their email thread matches the one of the email object created.",
"example": false
},
"labels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"rejection",
"automatic_rejection",
"rejected",
"automatic_status_changed_info",
"forwarded",
"reply"
]
},
"description": "List of email labels.",
"example": [
"forwarded"
]
},
"email_template": {
"type": "string",
"format": "uri",
"description": "Link to the email template that was used for the email creation. If specified, the email will be included in the email templates stats.",
"example": "https://example.rossum.app/api/v1/email_templates/789"
}
},
"required": [
"queue"
]
},
"email_template": {
"type": "object",
"title": "Email Template object",
"x-tags": [
"Email Template"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the email template",
"example": 1234
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the email template",
"example": "https://example.rossum.app/api/v1/email_templates/789"
},
"name": {
"type": "string",
"description": "Name of the email template",
"example": "My Email Template"
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
}
]
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"triggers": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"default": [],
"description": "URLs of the linked triggers",
"example": [
"https://example.rossum.app/api/v1/triggers/500",
"https://example.rossum.app/api/v1/triggers/600"
]
},
"type": {
"type": "string",
"enum": [
"rejection",
"rejection_default",
"email_with_no_processable_attachments",
"custom"
],
"default": "custom",
"description": "Type of the email template. Only templates with types `rejection` and `custom` can be manually created and deleted.\n\n- `rejection` - Template for a rejection email\n- `rejection_default` - Default template for a rejection email \n- `email_with_no_processable_attachments` - Template for a reply to an email with no attachments\n- `custom` - Custom email template\n",
"example": "custom"
},
"subject": {
"type": "string",
"default": "",
"description": "Email subject",
"example": "My Email Template Subject"
},
"message": {
"type": "string",
"default": "",
"description": "HTML subset of text email section",
"example": "My Email Template Message
"
},
"enabled": {
"type": "boolean",
"default": true,
"deprecated": true,
"description": "(Deprecated) Use `automate` instead",
"example": true
},
"automate": {
"type": "boolean",
"default": true,
"description": "True if user wants to send email automatically on the action",
"example": true
},
"to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"default": [],
"description": "List that contains information about recipients. The total number of recipients (to, cc and bcc together) cannot exceed 40.",
"example": [
{
"email": "recipient@example.com",
"name": "Recipient Name"
}
]
},
"cc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"default": [],
"description": "List that contains information about recipients of carbon copy. The total number of recipients (to, cc and bcc together) cannot exceed 40.",
"example": []
},
"bcc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"default": [],
"description": "List that contains information about recipients of blind carbon copy. The total number of recipients (to, cc and bcc together) cannot exceed 40.",
"example": []
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"email_address_template": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address.",
"example": "{{sender_email}}"
},
"name": {
"type": [
"string",
"null"
],
"description": "Name of the email recipient.",
"example": "John Doe"
}
},
"required": [
"email"
]
},
"render_request": {
"type": "object",
"properties": {
"to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address_template"
},
"default": [],
"description": "List that contains information about recipients to be rendered. The total number of recipients (to, cc and bcc together) cannot exceed 40."
},
"cc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address_template"
},
"default": [],
"description": "List that contains information about recipients of carbon copy to be rendered. The total number of recipients (to, cc and bcc together) cannot exceed 40.",
"example": []
},
"bcc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address_template"
},
"default": [],
"description": "List that contains information about recipients of blind carbon copy to be rendered. The total number of recipients (to, cc and bcc together) cannot exceed 40.",
"example": []
},
"parent_email": {
"type": "string",
"format": "uri",
"description": "Link to parent email",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"document_list": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"default": [],
"description": "List of document URLs to simulate sending of documents over email into Rossum",
"example": [
"https://example.rossum.app/api/v1/documents/2314"
]
},
"annotation_list": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"default": [],
"description": "List of annotation URLs to use for rendering values for annotation.content placeholders",
"example": []
},
"template_values": {
"type": "object",
"default": {},
"description": "Values to fill in the email template",
"example": {}
}
}
},
"render_response": {
"type": "object",
"properties": {
"to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains rendered information about recipients",
"example": [
{
"email": "satisfied.customer@rossum.ai"
}
]
},
"cc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains rendered information about recipients of carbon copy",
"example": []
},
"bcc": {
"type": "array",
"items": {
"$ref": "#/components/schemas/email_address"
},
"description": "List that contains rendered information about recipients of blind carbon copy",
"example": []
},
"subject": {
"type": "string",
"description": "Rendered email template's subject",
"example": "My Email Template Subject: Rendered Parent Email Subject"
},
"message": {
"type": "string",
"description": "Rendered email template's message",
"example": "My Email Template Message from user@example.com
"
}
}
},
"email_thread": {
"type": "object",
"title": "Email Thread object",
"x-tags": [
"Email Thread"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the email thread.",
"example": 1244
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the email thread.",
"example": "https://example.rossum.app/api/v1/email_threads/456"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
}
]
},
"root_email": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the associated root email (first incoming email in the thread).",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"has_replies": {
"type": "boolean",
"readOnly": true,
"description": "True if the thread has more than one incoming emails.",
"example": false
},
"has_new_replies": {
"type": "boolean",
"description": "True if the thread has unread incoming emails.",
"example": false
},
"root_email_read": {
"type": "boolean",
"readOnly": true,
"description": "True if the root email has been opened in Rossum UI at least once.",
"example": false
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of the creation of email thread (inherited from arrived_at timestamp of the root email).",
"example": "2021-06-10T12:38:44.866180Z"
},
"last_email_created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp of the most recent email in this email thread.",
"example": "2021-11-01T18:02:24.740600Z"
},
"subject": {
"type": "string",
"readOnly": true,
"description": "Subject of the root email.",
"example": "Root email subject"
},
"from": {
"type": "object",
"readOnly": true,
"description": "Information about sender of the root email containing keys `email` and `name`.",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the sender.",
"example": "satisfied.customer@rossum.ai"
},
"name": {
"type": "string",
"description": "Name of the sender.",
"example": "Satisfied Customer"
}
},
"example": {
"email": "satisfied.customer@rossum.ai",
"name": "Satisfied Customer"
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"readOnly": true,
"description": "This attribute is intended for **INTERNAL** use only and may be changed without notice. \nList of email thread labels set by root email. If root email is rejected and no other \nincoming emails are in thread, labels field is set to `[rejected]`. Labels is an empty \nlist in all the other cases.\n",
"example": []
},
"annotation_counts": {
"type": "object",
"readOnly": true,
"description": "This attribute is intended for **INTERNAL** use only and may be changed without notice. \nInformation about how many annotations were extracted from all emails in the thread and \nin which state they currently are.\n",
"properties": {
"annotations": {
"type": "integer",
"description": "Total number of annotations.",
"example": 4
},
"annotations_processed": {
"type": "integer",
"description": "Number of processed annotations.",
"example": 2
},
"annotations_purged": {
"type": "integer",
"description": "Number of purged annotations.",
"example": 0
},
"annotations_rejected": {
"type": "integer",
"description": "Number of rejected annotations.",
"example": 1
},
"annotations_unprocessed": {
"type": "integer",
"description": "Number of not yet processed annotations.",
"example": 1
}
},
"example": {
"annotations": 4,
"annotations_processed": 2,
"annotations_purged": 0,
"annotations_rejected": 1,
"annotations_unprocessed": 1
}
}
}
},
"engine_field": {
"type": "object",
"title": "Engine Field object",
"x-tags": [
"Engine Field"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Engine Field object ID.",
"example": 3
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Engine Field object URL.",
"example": "https://example.rossum.app/api/v1/engine_fields/3"
},
"engine": {
"type": "string",
"format": "uri",
"description": "Engine object URL.",
"example": "https://example.rossum.app/api/v1/engines/8"
},
"name": {
"type": "string",
"description": "Name of the field. Only numbers, characters and underscores are allowed. The value must be unique across all fields for given engine.",
"example": "document_id"
},
"label": {
"type": "string",
"description": "Human readable name of the field.",
"example": "Document ID"
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"date",
"enum"
],
"description": "Type of the field.\n",
"example": "string"
},
"subtype": {
"type": [
"string",
"null"
],
"description": "Subtype for more specific field validation. Possible values depend on the field type:\n\n**String subtypes:**\n- `null`: Plain text without any constraints\n- `alphanumeric`: Only characters a-z, A-Z, and 0-9 (whitespace stripped). Example: `A 123b` → `A123b`.\n- `numeric`: Only numbers (whitespace stripped, useful for leading zeros). Example: `01 23` → `0123`.\n- `country_code`: Two or three-letter country code (ISO 3166). Example: `CZ` or `CZE`.\n- `currency_code`: Three-letter currency code (ISO 4217). Example: `USD`.\n- `iban`: International Bank Account Number (up to 34 alphanumeric characters). Example: `IE12BOFI90000112345678`.\n- `vat_number`: VAT identification number (starts with country code, 2-13 characters). Example: `CZ1234567890`.\n\n**Number subtypes:**\n- `null`: Plain number\n- `integer`: Whole number. Example: `10.0` → `10`.\n- `rate`: Typically in range of 0-100%. Example: `10%` → `10`, `15,00` → `15`.\n- `amount`: Financial notation (parenthesis for negative values). Example: `(100)` → `-100`, `$10.5` → `10.5`, `▲10` → `-10`.\n\n**Date subtypes:**\n- `null`: Plain date\n- `period_begin`: Beginning of date period (fallback to first day of month)\n- `period_end`: End of date period (fallback to last day of month)\n",
"example": "string"
},
"pre_trained_field_id": {
"type": [
"string",
"null"
],
"description": "Pre-trained field identifier for common document elements. See the [pre_trained_fields](/api/engine-field#list-pre-trained-fields) endpoint for available values.",
"example": "document_id"
},
"tabular": {
"type": "boolean",
"description": "Whether the field belongs to a multivalue row. Default is false. Must be in sync with all assigned schemas - tabular = true means that the field is a child of tabular multivalue.",
"default": false,
"example": false
},
"multiline": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Multiline configuration. Allowed values are:\n- `true`: Field's parent is of type tuple\n- `false`: Header field\n",
"example": "false"
}
}
},
"pre_trained_field": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Pre-trained field identifier.",
"example": "account_num"
},
"label": {
"type": "string",
"description": "Human readable name of the pre-trained field.",
"example": "Bank Account"
},
"section": {
"type": "string",
"description": "Category section of the pre-trained field.",
"example": "Identifiers"
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"date",
"enum"
],
"description": "Field type.",
"example": "string"
},
"subtype": {
"type": [
"string",
"null"
],
"description": "Field subtype for more specific validation.",
"example": "alphanumeric"
},
"tabular": {
"type": "boolean",
"description": "Whether the field is designed for tabular data.",
"example": false
},
"multiline": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Multiline configuration.",
"example": "false"
},
"description": {
"type": "string",
"description": "Detailed description of the pre-trained field.",
"example": "Bank account number. Whitespaces are stripped."
}
}
},
"engine": {
"type": "object",
"title": "Engine object",
"x-tags": [
"Engines"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Engine object ID.",
"example": 3
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Engine object URL.",
"example": "https://example.rossum.app/api/v1/engines/8"
},
"name": {
"type": "string",
"description": "Name of the engine.",
"example": "Engine name"
},
"type": {
"type": "string",
"enum": [
"extractor",
"splitter"
],
"description": "Type of the engine. Allowed values are:\n- `extractor`: Engine used for data extraction\n- `splitter`: Engine used for splitting of documents\n",
"example": "extractor"
},
"learning_enabled": {
"type": "boolean",
"description": "Whether is the engine learning from the attached queues.",
"default": true,
"example": true
},
"description": {
"type": "string",
"description": "Description of the engine.",
"default": "",
"example": "AI engine trained to recognize data for the specific data capture requirement"
},
"agenda_id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier of the engine.",
"example": "ross_a9d9vkl1"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
]
},
"training_queues": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"format": "uri"
},
"description": "Queues that are used for training the engine. Queues that become assigned to the engine are added to the list automatically.",
"example": [
"https://example.rossum.app/api/v1/queues/8199",
"https://example.rossum.app/api/v1/queues/8236"
]
}
}
},
"template_compatibility_request": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the template organization.",
"example": "EU Demo Template"
}
},
"required": [
"name"
]
},
"template_compatibility_response": {
"type": "object",
"properties": {
"compatible": {
"type": "boolean",
"description": "Is the template schema compatible with this engine.",
"example": true
}
}
},
"duplicate_request": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the duplicated engine.",
"example": "Duplicated Engine"
}
},
"required": [
"name"
]
},
"queue_stats": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the queue.",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"number_of_used_engine_fields": {
"type": "integer",
"description": "Number of engine fields used in the queue schema overlapping with engine fields of given engine.",
"example": 12
},
"prediction_queue": {
"type": "boolean",
"description": "Queue is using given engine for its predictions.",
"example": true
},
"training_queue": {
"type": "boolean",
"description": "Queue is used for training of the given engine.",
"example": false
}
}
},
"generic_engine": {
"type": "object",
"title": "Generic Engine object",
"x-tags": [
"Generic Engine"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the generic engine.",
"example": 3000
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the generic engine.",
"example": "https://example.rossum.app/api/v1/generic_engines/3000"
},
"name": {
"type": "string",
"description": "Name of the generic engine.",
"example": "Generic engine"
},
"description": {
"type": "string",
"description": "Description of the generic engine.",
"example": "AI engine trained to recognize data for the specific data capture requirement"
},
"documentation_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the generic engine's documentation.",
"example": "https://knowledge-base.rossum.ai/docs/ai-engines#generic-engines"
},
"schema": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the related generic engine schema.",
"example": "https://example.rossum.app/api/v1/generic_engine_schemas/6000"
}
}
},
"generic_engine_schema": {
"type": "object",
"title": "Generic Engine Schema object",
"x-tags": [
"Generic Engine Schema"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the generic engine schema.",
"example": 6000
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the generic engine schema.",
"example": "https://example.rossum.app/api/v1/generic_engine_schemas/6000"
},
"content": {
"$ref": "#/components/schemas/engine_content"
}
}
},
"hook_base": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the hook.",
"example": 1500
},
"type": {
"type": "string",
"enum": [
"webhook",
"function"
],
"default": "webhook",
"description": "Hook type.",
"example": "webhook"
},
"name": {
"type": "string",
"description": "Name of the hook.",
"example": "Change of Status"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the hook.",
"example": "https://example.rossum.app/api/v1/hooks/1500"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of queues that use hook object.",
"example": [
"https://example.rossum.app/api/v1/queues/8199",
"https://example.rossum.app/api/v1/queues/8191"
]
},
"run_after": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of all hooks that has to be executed before running this hook.",
"example": []
},
"active": {
"type": "boolean",
"description": "If set to `true` the hook is notified.",
"example": true
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of events, when the hook should be notified. For the list of events see [Webhook events](/guides/extensions#webhook-extension).",
"example": [
"annotation_status.changed"
]
},
"sideload": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "List of related objects that should be included in hook request. For the list of possible sideloads see [Webhook events](/guides/extensions#webhook-extension).",
"example": [
"queues"
]
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"token_owner": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of a user object. If present, an API access token is generated for this user and [sent to the hook](/guides/extensions#webhook-extension). Users with organization group admin cannot be set as token_owner. If `null`, token is not generated.",
"example": "https://example.rossum.app/api/v1/users/2"
},
"token_lifetime_s": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 7200,
"description": "Lifetime number of seconds for `rossum_authorization_token` (min=0, max=7200). This setting will ensure the token will be valid after hook response is returned. If `null`, default lifetime of `600` is used.",
"example": 1000
},
"test": {
"type": "object",
"default": {},
"description": "Input saved for hook testing purposes, see [Test a hook](/api/hook#test-hook).",
"example": {
"saved_input": {}
}
},
"description": {
"type": [
"string",
"null"
],
"description": "Hook description text.",
"example": "This hook does..."
},
"extension_source": {
"type": "string",
"enum": [
"custom",
"rossum_store"
],
"default": "custom",
"description": "Import source of the extension.",
"example": "custom"
},
"settings": {
"type": "object",
"default": {},
"description": "Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in `settings_schema` field.",
"example": {}
},
"settings_schema": {
"type": [
"object",
"null"
],
"description": "JSON schema for `settings` field validation.",
"example": {
"type": "object",
"properties": {}
}
},
"secrets": {
"type": "object",
"writeOnly": true,
"default": {},
"description": "Specific secrets that are stored securely encrypted. The values are merged into the hook execution payload. Field is validated with json schema stored in `secrets_schema` field. (write only)",
"example": {}
},
"secrets_schema": {
"type": "object",
"description": "JSON schema for `secrets` field validation.",
"default": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"example": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"guide": {
"type": [
"string",
"null"
],
"description": "Description how to use the extension.",
"example": "Here we explain how the extension should be used."
},
"read_more_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL address leading to more info page.",
"example": "https://github.com/rossumai/simple-vendor-matching-webhook-python"
},
"extension_image_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL address of extension picture.",
"example": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg"
},
"hook_template": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the hook template used to create the hook.",
"example": "https://example.rossum.app/api/v1/hook_templates/998877"
},
"created_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "URL of the hook creator. Might be `null` for hooks created before April 2025.",
"example": "https://example.rossum.app/api/v1/users/2"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Date of hook creation. Might be `null` for hooks created before April 2025.",
"example": "2020-01-01T09:05:50.213451Z"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"webhook_config": {
"type": "object",
"description": "Configuration for webhook hooks.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the webhook endpoint to call.",
"example": "https://myq.east-west-trading.com/api/hook1?strict=true"
},
"secret": {
"type": "string",
"description": "(optional) If set, it is used to create a hash signature with each payload. For more information see [Validating payloads from Rossum](#validating-payloads-from-rossum).",
"example": "secret-token"
},
"insecure_ssl": {
"type": "boolean",
"default": false,
"description": "Disable SSL certificate verification (only use for testing purposes).",
"example": false
},
"client_ssl_certificate": {
"type": [
"string",
"null"
],
"description": "Client SSL certificate used to authenticate requests. Must be PEM encoded.",
"example": "-----BEGIN CERTIFICATE-----\n..."
},
"client_ssl_key": {
"type": "string",
"writeOnly": true,
"description": "Client SSL key (write only). Must be PEM encoded. Key may not be encrypted.",
"example": "-----BEGIN PRIVATE KEY-----\n..."
},
"private": {
"type": "boolean",
"default": false,
"description": "(optional) If set, the `url` and `secret` values become hidden and immutable once the hook is created. The value of this flag cannot be changed to `false` once set.",
"example": false
},
"schedule": {
"type": "object",
"default": {},
"description": "Specific configuration for hooks of invocation.scheduled event and action interval. See [schedule](#schedule-object).",
"properties": {
"cron": {
"type": "string",
"description": "Used to set interval with [cron expression](https://crontab.guru/) in UTC timezone. Cron object interval can't be shorter than every 10 minutes.",
"example": "*/10 * * * *"
}
}
},
"timeout_s": {
"type": "integer",
"minimum": 0,
"maximum": 60,
"default": 30,
"description": "Webhook call timeout in seconds. For non-interactive webhooks only (min=0, max=60).",
"example": 30
},
"retry_count": {
"type": "integer",
"minimum": 0,
"maximum": 4,
"default": 4,
"description": "Number of times the webhook call is retried in case of failure. For non-interactive webhooks only (min=0, max=4).",
"example": 4
},
"max_polling_time_s": {
"type": "integer",
"minimum": 1,
"maximum": 3600,
"default": 300,
"description": "The maximum polling time in seconds for [asynchronous webhooks](#asynchronous-webhooks) (min=1, max=3600). It is possible to configure this value only for `upload.created` and `invocation.scheduled` events. For other non-interactive events the default value is used.",
"example": 300
},
"retry_after_polling_failure": {
"type": "boolean",
"default": true,
"description": "If set to `true`, the original webhook call is retried in case the polling fails. See the [asynchronous webhooks](#asynchronous-webhooks) section for more details. Possible to configure only for `upload.created` and `invocation.scheduled` events. For other non-interactive events the default value is used.",
"example": true
},
"app": {
"type": [
"object",
"null"
],
"deprecated": true,
"description": "(deprecated) (optional) Configuration of the app.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the app that will be embedded in Rossum UI.",
"example": "https://myq.east-west-trading.com/api/hook1?strict=true"
},
"settings": {
"type": "object",
"description": "Settings of the app that can be used for further customization of configuration app (such as UI schema etc.).",
"example": {}
},
"display_mode": {
"type": "string",
"enum": [
"drawer",
"fullscreen"
],
"default": "drawer",
"description": "Display mode of the app. `drawer` opens a drawer with embedded URL, `fullscreen` opens an embedded URL in full-screen overlay.",
"example": "drawer"
}
},
"required": [
"url"
]
},
"payload_logging_enabled": {
"type": "boolean",
"default": false,
"description": "(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.",
"example": false
},
"retry_on_any_non_2xx": {
"type": "boolean",
"default": false,
"description": "(optional) Disabling this option results in retrying only on these response statuses: [408, 429, 500, 502, 503, 504].",
"example": false
}
}
},
"webhook_hook": {
"allOf": [
{
"$ref": "#/components/schemas/hook_base"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "webhook"
},
"config": {
"$ref": "#/components/schemas/webhook_config"
}
}
}
]
},
"function_config_base": {
"type": "object",
"description": "Configuration for function hooks.",
"properties": {
"status": {
"type": "string",
"readOnly": true,
"enum": [
"ready",
"pending",
"failed"
],
"description": "Status indicates whether the function is ready to be invoked or modified. Possible values are `ready`, `pending` or `failed`. While the state is `pending`, invocations and other API actions that operate on the function return status 400. It is recommended to resave function for `failed` state. (Function hooks only)",
"example": "ready"
},
"third_party_library_pack": {
"type": [
"string",
"null"
],
"enum": [
null,
"default"
],
"default": "default",
"description": "Set of libraries to be included in execution environment of the function.\n\nFor Python 3.12:\n * `null` (only standard library),\n * `default` (rossum, requests, jmespath, xmltodict, pydantic, pandas, httpx, boto3, botocore)\n\nFor Node.js 22:\n * `null` (built-in modules only),\n * `default` (node-fetch, https-proxy-agent, lodash)\n",
"example": "default"
},
"private": {
"type": "boolean",
"default": false,
"description": "(optional) If set, the `runtime`, `code` and `third_party_library_pack` values become hidden and immutable once the hook is created. The value of this flag cannot be changed to `false` once set.",
"example": false
},
"schedule": {
"type": "object",
"default": {},
"description": "Specific configuration for hooks of invocation.scheduled event and action interval. See [schedule](#schedule-object).",
"properties": {
"cron": {
"type": "string",
"description": "Used to set interval with [cron expression](https://crontab.guru/) in UTC timezone. Cron object interval can't be shorter than every 10 minutes.",
"example": "*/10 * * * *"
}
}
},
"timeout_s": {
"type": "integer",
"minimum": 0,
"maximum": 60,
"default": 30,
"description": "Function call timeout in seconds. For non-interactive functions only (min=0, max=60).",
"example": 30
},
"memory_size_mb": {
"type": "integer",
"minimum": 128,
"maximum": 256,
"default": 256,
"description": "Function memory limit (min=128, max=256). The limit can be increased upon request.",
"example": 256
},
"retry_count": {
"type": "integer",
"minimum": 0,
"maximum": 4,
"default": 4,
"description": "Number of times the function call is retried in case of failure. For non-interactive functions only (min=0, max=4).",
"example": 4
},
"app": {
"type": [
"object",
"null"
],
"deprecated": true,
"description": "(deprecated) (optional) Configuration of the app.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the app that will be embedded in Rossum UI.",
"example": "https://myq.east-west-trading.com/api/hook1?strict=true"
},
"settings": {
"type": "object",
"description": "Settings of the app that can be used for further customization of configuration app (such as UI schema etc.).",
"example": {}
},
"display_mode": {
"type": "string",
"enum": [
"drawer",
"fullscreen"
],
"default": "drawer",
"description": "Display mode of the app. `drawer` opens a drawer with embedded URL, `fullscreen` opens an embedded URL in full-screen overlay.",
"example": "drawer"
}
}
},
"payload_logging_enabled": {
"type": "boolean",
"default": false,
"description": "(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.",
"example": false
}
}
},
"function_config": {
"allOf": [
{
"type": "object",
"properties": {
"runtime": {
"type": "string",
"enum": [
"nodejs22.x",
"python3.12"
],
"description": "Runtime used to execute code. Allowed values: `nodejs22.x` or `python3.12`.",
"example": "nodejs22.x"
},
"code": {
"type": "string",
"description": "String-serialized source code to be executed.",
"example": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};"
}
}
},
{
"$ref": "#/components/schemas/function_config_base"
}
]
},
"function_hook": {
"allOf": [
{
"$ref": "#/components/schemas/hook_base"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "function"
},
"config": {
"$ref": "#/components/schemas/function_config"
}
}
}
]
},
"hook": {
"type": "object",
"title": "Hook object",
"x-tags": [
"Hook"
],
"oneOf": [
{
"$ref": "#/components/schemas/webhook_hook"
},
{
"$ref": "#/components/schemas/function_hook"
}
]
},
"webhook_hook_w_required": {
"allOf": [
{
"$ref": "#/components/schemas/hook_base",
"required": [
"name",
"events"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "webhook"
},
"config": {
"$ref": "#/components/schemas/webhook_config"
}
}
}
]
},
"function_config_w_required": {
"allOf": [
{
"type": "object",
"properties": {
"runtime": {
"type": "string",
"enum": [
"nodejs22.x",
"python3.12"
],
"description": "Runtime used to execute code. Allowed values: `nodejs22.x` or `python3.12`.",
"example": "nodejs22.x"
},
"code": {
"type": "string",
"description": "String-serialized source code to be executed.",
"example": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};"
}
},
"required": [
"runtime",
"code"
]
},
{
"$ref": "#/components/schemas/function_config_base"
}
]
},
"function_hook_w_required": {
"allOf": [
{
"$ref": "#/components/schemas/hook_base",
"required": [
"name",
"events"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "function"
},
"config": {
"$ref": "#/components/schemas/function_config_w_required"
}
}
}
]
},
"hook_w_required": {
"type": "object",
"title": "Hook object",
"oneOf": [
{
"$ref": "#/components/schemas/webhook_hook_w_required"
},
{
"$ref": "#/components/schemas/function_hook_w_required"
}
]
},
"email_url": {
"type": "string",
"format": "uri",
"description": "Email URL.",
"example": "https://example.rossum.app/api/v1/emails/1234"
},
"hook_logs_response": {
"type": "object",
"required": [
"results",
"pagination"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the log entry.",
"example": "2023-09-23T12:00:00.000000Z"
},
"request_id": {
"type": "string",
"description": "Request ID of the hook call.",
"example": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
},
"event": {
"type": "string",
"description": "Event that triggered the hook.",
"example": "annotation_content"
},
"action": {
"type": "string",
"description": "Action that was performed.",
"example": "updated"
},
"annotation_id": {
"type": [
"integer",
"null"
],
"description": "ID of the related annotation.\n\nOnly present for `annotation_content` and `annotation_status` events.\n",
"example": 1
},
"queue_id": {
"type": [
"integer",
"null"
],
"description": "ID of the related queue.",
"example": 1
},
"email_id": {
"type": [
"integer",
"null"
],
"description": "ID of the related email.\n\nOnly present for `email` events.\n",
"example": 1
},
"hook_id": {
"type": "integer",
"description": "ID of the hook.",
"example": 1
},
"hook_type": {
"type": "string",
"description": "Type of the hook.",
"example": "webhook"
},
"message": {
"type": "string",
"description": "Log message.",
"example": "message"
},
"request": {
"type": "string",
"description": "Request payload.",
"example": "{}"
},
"response": {
"type": "string",
"description": "Response payload.",
"example": "{}"
},
"start": {
"type": "string",
"format": "date-time",
"description": "Start timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"end": {
"type": "string",
"format": "date-time",
"description": "End timestamp.",
"example": "2023-09-23T12:00:00.000000Z"
},
"settings": {
"type": "string",
"description": "Hook settings.",
"example": "{}"
},
"status": {
"type": "string",
"enum": [
"waiting",
"running",
"completed",
"cancelled",
"failed"
],
"description": "Status of the hook call.",
"example": "completed"
},
"uuid": {
"type": "string",
"description": "UUID of the hook call.",
"example": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
}
}
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"hook_template": {
"type": "object",
"title": "Hook Template object",
"x-tags": [
"Hook Template"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the hook template.",
"example": 1
},
"type": {
"type": "string",
"description": "Hook type.",
"enum": [
"webhook",
"function"
],
"default": "webhook",
"example": "function"
},
"name": {
"type": "string",
"description": "Name of the hook template.",
"example": "Document sorting"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the hook template.",
"example": "https://example.rossum.app/api/v1/hook_templates/1"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of events, when the hook should be notified. For the list of events see Webhook events.",
"example": [
"annotation_status.changed"
]
},
"sideload": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events.",
"default": [],
"example": [
"queues"
]
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"config": {
"type": "object",
"description": "Configuration of the hook.",
"example": {
"runtime": "nodejs22.x",
"code": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};",
"schedule": {
"cron": "*/10 * * * *"
}
}
},
"test": {
"type": "object",
"description": "Input saved for hook testing purposes, see Test a hook.",
"default": {}
},
"description": {
"type": "string",
"description": "Hook description text.",
"example": "Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale."
},
"extension_source": {
"type": "string",
"description": "Import source of the extension. For more, see Extension sources.",
"default": "rossum_store",
"example": "rossum_store"
},
"settings": {
"type": "object",
"description": "Specific settings that will be included in the payload when executing the hook.",
"default": {}
},
"settings_schema": {
"type": [
"object",
"null"
],
"description": "JSON schema for settings field, specifying the JSON structure of this field.",
"default": null
},
"secrets_schema": {
"type": [
"object",
"null"
],
"description": "JSON schema for secrets field, specifying the JSON structure of this field.",
"default": null
},
"guide": {
"type": "string",
"description": "Description how to use the extension.",
"example": "Here we explain how the extension should be used."
},
"read_more_url": {
"type": "string",
"format": "uri",
"description": "URL address leading to more info page.",
"example": "https://github.com/rossumai/simple-vendor-matching-webhook-python"
},
"extension_image_url": {
"type": "string",
"format": "uri",
"description": "URL address of extension picture.",
"example": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg"
},
"settings_description": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of settings attribute."
},
"description": {
"type": "string",
"description": "Description of settings attribute."
},
"tooltip": {
"type": "string",
"description": "Tooltip for the attribute."
}
}
},
"description": "Contains description for settings.",
"default": []
},
"store_description": {
"type": "string",
"description": "Description of hook displayed in Rossum store.",
"example": "Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale.
"
},
"external_url": {
"type": "string",
"description": "External URL to be called (relates to webhook type).",
"example": ""
},
"use_token_owner": {
"type": "boolean",
"description": "Whether the hook should use token owner.",
"default": false,
"example": true
},
"install_action": {
"type": "string",
"description": "Whether the hook is added directly via application (copy) or on customer's request (request_access).",
"enum": [
"copy",
"request_access"
],
"default": "copy",
"example": "copy"
},
"token_lifetime_s": {
"type": [
"integer",
"null"
],
"description": "Lifetime number of seconds for rossum_authorization_token (min=0, max=7200). This setting will ensure the token will be valid after hook response is returned. If null, default lifetime of 600 is used.",
"minimum": 0,
"maximum": 7200,
"default": null
},
"order": {
"type": "integer",
"description": "Hook templates can be ordered or grouped by this parameter.",
"default": 0,
"example": 0
}
}
},
"document_rejection_conditions": {
"type": "object",
"description": "Rules for filtering out documents coming to Rossum smart inbox. If it's enabled document will be rejected\nonce it satisfied at least one of defined conditions.\n\nSetting attribute value to null (or empty list in case of `mime_types`, `file_name_regexes`) will turn that specific filtering feature off.\n",
"properties": {
"enabled": {
"description": "Whether the document rejection feature is enabled.",
"type": "boolean",
"default": true,
"example": true
},
"resolution_lower_than_px": {
"description": "Resolution [width, height] in pixels. A file will be filtered out if both of the dimensions are smaller than the limits.",
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2,
"default": [
1200,
600
],
"example": [
1200,
600
]
},
"file_size_less_than_b": {
"description": "Size of document in bytes. A file with smaller size will be filtered out.",
"type": [
"integer",
"null"
],
"default": null,
"example": null
},
"mime_types": {
"description": "List of mime types to filter out (must match `^.+/.+$`).",
"type": "array",
"items": {
"type": "string",
"pattern": "^.+/.+$"
},
"default": [
"image/gif"
],
"example": [
"image/gif"
]
},
"file_name_regexes": {
"description": "Regular expressions in `re2` format (for more info about syntax see [docs](https://github.com/google/re2/wiki/Syntax)). A file with matching name will be filtered out.",
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"example": null
}
}
},
"filters": {
"type": "object",
"description": "Filtering of incoming emails and documents. `allowed_senders` and `denied_senders` settings allow filtering of incoming emails based on sender email address. Filters can be specified by exact email addresses as well as using expressions containing wildcards:\n- `*` matches everything (e.g. `*@rossum.ai` matches every email from `rossum.ai` domain)\n- `?` matches any single character (e.g. `john?doe@rossum.ai` matches `john.doe@rossum.ai` as well as `john-doe@rossum.ai`)\n`document_rejection_conditions` defines rules for filtering incoming documents via email.\n",
"properties": {
"allowed_senders": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only emails with matching sender's address will be processed. If empty all senders all allowed.",
"default": [],
"example": [
"*@rossum.ai",
"john.doe@company.com",
"john.doe@company.??"
]
},
"denied_senders": {
"type": "array",
"items": {
"type": "string"
},
"description": "Incoming emails from email address matching one of these will be ignored.",
"default": [],
"example": [
"spam@*"
]
},
"document_rejection_conditions": {
"$ref": "#/components/schemas/document_rejection_conditions"
}
}
},
"inbox": {
"type": "object",
"title": "Inbox object",
"x-tags": [
"Inbox"
],
"properties": {
"id": {
"description": "ID of the inbox.",
"type": "integer",
"format": "int64",
"readOnly": true,
"example": 1234
},
"name": {
"description": "Name of the inbox (not visible in UI).",
"type": "string",
"example": "Receipts"
},
"url": {
"description": "URL of the inbox.",
"type": "string",
"format": "url",
"readOnly": true,
"example": "https://example.rossum.app/api/v1/inboxes/1234"
},
"queues": {
"description": "Queue that receives documents from inbox. Queue has to be passed in list due to backward compatibility. It is possible to have only one queue per inbox.",
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"example": [
"https://example.rossum.app/api/v1/queues/8199"
]
},
"email": {
"description": "Rossum email address (e.g. `east-west-trading-co-a34f3a@example.rossum.app`).",
"type": "string",
"format": "email",
"example": "east-west-trading-co-a34f3a@example.rossum.app"
},
"email_prefix": {
"description": "Rossum email address prefix (e.g. `east-west-trading-co`). Maximum length allowed is 57 chars.",
"type": "string",
"maxLength": 57,
"example": "east-west-trading-co"
},
"bounce_email_to": {
"description": "(Deprecated) Email address to send notifications to (e.g. about failed import). Configuration moved to Email notifications settings.",
"type": [
"string",
"null"
],
"format": "email",
"deprecated": true,
"example": "bounces@east-west.com"
},
"bounce_unprocessable_attachments": {
"description": "(Deprecated) Whether return back unprocessable attachments (e.g. MS Word docx) or just silently ignore them. When true, minimum image size requirement does not apply. Configuration moved to Email notifications settings.",
"type": "boolean",
"deprecated": true,
"default": false,
"example": false
},
"bounce_postponed_annotations": {
"description": "(Deprecated) Whether to send notification when annotation is postponed. Configuration moved to Email notifications settings.",
"type": "boolean",
"deprecated": true,
"default": false,
"example": false
},
"bounce_deleted_annotations": {
"description": "(Deprecated) Whether to send notification when annotation is deleted. Configuration moved to Email notifications settings.",
"type": "boolean",
"deprecated": true,
"default": false,
"example": false
},
"bounce_email_with_no_attachments": {
"description": "(Deprecated) Whether to send notification when no processable documents were found. Configuration moved to Email notifications settings.",
"type": "boolean",
"deprecated": true,
"default": true,
"example": true
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"filters": {
"$ref": "#/components/schemas/filters"
},
"dmarc_check_action": {
"description": "Decides what to do with incoming emails, that don't pass the DMARC check.",
"type": "string",
"enum": [
"accept",
"drop"
],
"default": "accept",
"example": "accept"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"label": {
"type": "object",
"title": "Label object",
"x-tags": [
"Label"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Label object ID.",
"example": 1
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Label object URL.",
"example": "https://example.rossum.app/api/v1/labels/1"
},
"name": {
"type": "string",
"description": "Text of the label.",
"example": "expedite"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"color": {
"type": [
"string",
"null"
],
"description": "Color of the label in RGB hex format.",
"example": "#FF5733"
}
}
},
"apply_request": {
"type": "object",
"properties": {
"operations": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of label URLs to add to annotations",
"example": [
"https://example.rossum.app/api/v1/labels/42"
]
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of label URLs to remove from annotations",
"example": [
"https://example.rossum.app/api/v1/labels/43"
]
}
},
"description": "Operations to perform on labels"
},
"objects": {
"type": "object",
"properties": {
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of annotation URLs to apply operations to",
"example": [
"https://example.rossum.app/api/v1/annotations/10",
"https://example.rossum.app/api/v1/annotations/11"
]
}
},
"description": "Objects to apply operations to"
}
},
"required": [
"operations",
"objects"
]
},
"user_url": {
"type": "string",
"format": "uri",
"description": "User URL.",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"membership": {
"type": "object",
"title": "Membership object",
"x-tags": [
"Membership"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the membership",
"example": 3
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the membership",
"example": "https://example.rossum.app/api/v1/organization_groups/1/memberships/3"
},
"user": {
"allOf": [
{
"$ref": "#/components/schemas/user_url"
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/1/users/4"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/1/organizations/5"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "URLs of queues user has access to",
"example": [
"https://example.rossum.app/api/v1/organization_groups/1/queues/3",
"https://example.rossum.app/api/v1/organization_groups/1/queues/4"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Timestamp of membership expiration. Membership won't expire if no expiration is set.",
"example": null
}
}
},
"organization_group_url": {
"type": "string",
"format": "uri",
"description": "Organization group URL.",
"example": "https://example.rossum.app/api/v1/organization_groups/17"
},
"annotation_list_table": {
"type": "object",
"properties": {
"visible": {
"type": "boolean",
"description": "Column is visible on the dashboard."
},
"width": {
"type": "number",
"format": "float",
"description": "Width of the column."
},
"column_type": {
"type": "string",
"enum": [
"meta",
"schema"
],
"description": "Type of the field (`meta` - annotation meta field, `schema` - annotation content field)."
},
"schema_id": {
"type": "string",
"description": "`schema_id` of the extracted field (only for `column_type=schema`)."
},
"data_type": {
"type": "string",
"enum": [
"date",
"number",
"string",
"boolean"
],
"description": "Data type of the extracted field (only for `column_type=schema`). Allowed values are `date`, `number`, `string`, `boolean`."
},
"meta_type": {
"type": "string",
"description": "Meta column type (only for `column_type=meta`). Allowed values can be found in `meta_field` table (+ additionally `details`)."
}
}
},
"organization": {
"type": "object",
"title": "Organization object",
"x-tags": [
"Organization"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the organization.",
"example": 406
},
"name": {
"type": "string",
"description": "Name of the organization (not visible in UI).",
"example": "East West Trading Co"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the organization.",
"example": "https://example.rossum.app/api/v1/organizations/406"
},
"workspaces": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of workspaces objects in the organization.",
"example": [
"https://example.rossum.app/api/v1/workspaces/7540"
]
},
"users": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of users in the organization.",
"example": [
"https://example.rossum.app/api/v1/users/10775"
]
},
"organization_group": {
"allOf": [
{
"$ref": "#/components/schemas/organization_group_url"
},
{
"description": "URL to organization group the organization belongs to.",
"readOnly": true
}
]
},
"ui_settings": {
"type": "object",
"description": "Organization-wide frontend UI settings (e.g. locales). Rossum internal.",
"default": {},
"example": {}
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"is_trial": {
"type": "boolean",
"readOnly": true,
"description": "Property indicates whether this license is a trial license.",
"example": true
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Timestamp for when the organization was created.",
"example": "2019-09-02T14:28:11.000000Z"
},
"trial_expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Timestamp for when the trial period ended (ISO 8601).",
"example": "2020-09-02T14:28:11.000000Z"
},
"oidc_provider": {
"type": [
"string",
"null"
],
"readOnly": true,
"deprecated": true,
"description": "(Deprecated) OpenID Connect provider name.",
"example": null
},
"internal_info": {
"type": [
"object",
"null"
],
"readOnly": true,
"description": "**INTERNAL** Rossum internal information on organization.",
"properties": {
"cs_account_classification": {
"type": [
"string",
"null"
],
"description": "Account classification in SalesForce."
},
"customer_type": {
"type": [
"string",
"null"
],
"description": "Customer type in SalesForce."
},
"market_category": {
"type": [
"string",
"null"
],
"description": "Customer market category in SalesForce."
},
"overdue_payment_date": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Date of overdue payment. If empty, no payment is overdue. There may be a delay between update of the value of this field and the actual payment settlement with the Finance team and/or other customer-facing teams.\n"
},
"sso_active": {
"type": [
"boolean",
"null"
],
"description": "Customer has SSO login enabled."
}
},
"example": {
"cs_account_classification": null,
"customer_type": null,
"market_category": null,
"overdue_payment_date": null,
"sso_active": false
}
},
"creator": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "URL of the first user of the organization (set during organization creation).",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
},
"settings": {
"type": "object",
"description": "Settings of the organization.",
"properties": {
"annotation_list_table": {
"type": "object",
"description": "Configuration of annotation dashboard columns.",
"default": {},
"properties": {
"columns": {
"type": "array",
"description": "Configuration of columns on annotation list.",
"default": [],
"items": {
"$ref": "#/components/schemas/annotation_list_table"
}
}
}
}
},
"default": {},
"example": {}
},
"sandbox": {
"type": "boolean",
"description": "Specifies if the organization is a sandbox.",
"default": false,
"example": false
}
}
},
"organizations_create": {
"type": "object",
"required": [
"template_name",
"organization_name",
"user_fullname",
"user_email",
"create_key"
],
"properties": {
"template_name": {
"type": "string",
"enum": [
"Empty Organization Template",
"CZ Demo Template",
"Tax Invoice EU Demo Template",
"Tax Invoice US Demo Template",
"Tax Invoice UK Demo Template",
"Delivery Note Demo Template",
"Tax Invoice CN Demo Template",
"Certificates of Analysis Demo Template"
],
"description": "Template to use for new organization.",
"example": "Tax Invoice UK Demo Template"
},
"organization_name": {
"type": "string",
"description": "Name of the organization. Will be also used as a base for inbox e-mail address.",
"example": "East West Trading Co"
},
"user_fullname": {
"type": "string",
"description": "Full user name.",
"example": "John Doe"
},
"user_email": {
"type": "string",
"format": "email",
"description": "Valid email of the user (also used as Rossum login).",
"example": "john@east-west-trading.com"
},
"user_password": {
"type": "string",
"description": "Initial user password. If not provided, password will be generated.",
"example": "owo1aiG9ua9Aihai"
},
"user_ui_settings": {
"type": "object",
"description": "Initial UI settings.",
"default": {
"locale": "en"
},
"example": {
"locale": "en"
}
},
"create_key": {
"type": "string",
"description": "A key that allows to create an organization.",
"example": "13156106d6f185df24648ac7ff20f64f1c5c06c144927be217189e26f8262c4a"
}
}
},
"billing_filters_base": {
"type": "object",
"description": "Filters used for the computation of billed items counts.",
"properties": {
"queues": {
"type": "array",
"items": {
"type": [
"string",
"null"
],
"format": "uri"
},
"description": "Filter billed items for the specified queues (or `null` for historically deleted queues) to be counted in the report.",
"example": [
"https://example.rossum.app/api/v1/queues/8199"
]
},
"begin_date": {
"type": "string",
"format": "date",
"description": "Filter billed items that was issued **since** the specified date (including the specified date) to be counted to the report.",
"example": "2021-08-01"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Filter billed items that was issued **up to** the specified date (including the specified date) to be counted to the report.",
"example": "2021-08-31"
}
}
},
"group_by_base": {
"type": "array",
"items": {
"type": "string",
"enum": [
"queue",
"month",
"week"
]
},
"description": "List of attributes by which the `results` are to be grouped. Only a single value is supported.",
"example": [
"queue"
]
},
"billing_period": {
"type": "object",
"properties": {
"begin_date": {
"type": "string",
"format": "date",
"description": "Begin date of the billing period.",
"example": "2021-01-01"
},
"end_date": {
"type": "string",
"format": "date",
"description": "End date of the billing period.",
"example": "2022-12-31"
}
}
},
"billing_history_values_base": {
"type": "object",
"properties": {
"billable_documents": {
"type": "integer",
"description": "Number of billable documents.",
"example": 32
},
"billable_pages": {
"type": "integer",
"description": "Number of billable pages.",
"example": 27
},
"non_billable_documents": {
"type": "integer",
"description": "Number of non-billable documents.",
"example": 0
},
"non_billable_pages": {
"type": "integer",
"description": "Number of non-billable pages.",
"example": 0
},
"purchased_documents": {
"type": "integer",
"description": "Number of purchased documents.",
"example": 0
},
"purchased_pages": {
"type": "integer",
"description": "Number of purchased pages.",
"example": 555
},
"extracted_pages_with_learning": {
"type": "integer",
"description": "Number of extracted pages with learning.",
"example": 0
},
"extracted_pages_without_learning": {
"type": "integer",
"description": "Number of extracted pages without learning.",
"example": 0
},
"split_pages_with_learning": {
"type": "integer",
"description": "Number of split pages with learning.",
"example": 0
},
"split_pages_without_learning": {
"type": "integer",
"description": "Number of split pages without learning.",
"example": 0
},
"extracted_documents_with_learning": {
"type": "integer",
"description": "Number of extracted documents with learning.",
"example": 0
},
"extracted_documents_without_learning": {
"type": "integer",
"description": "Number of extracted documents without learning.",
"example": 0
},
"split_documents_with_learning": {
"type": "integer",
"description": "Number of split documents with learning.",
"example": 0
},
"split_documents_without_learning": {
"type": "integer",
"description": "Number of split documents without learning.",
"example": 0
},
"ocr_only_pages": {
"type": "integer",
"description": "Number of OCR-only pages.",
"example": 0
},
"ocr_only_documents": {
"type": "integer",
"description": "Number of OCR-only documents.",
"example": 0
},
"purchased_extracted_pages_with_learning": {
"type": "integer",
"description": "Number of purchased extracted pages with learning.",
"example": 0
},
"purchased_extracted_pages_without_learning": {
"type": "integer",
"description": "Number of purchased extracted pages without learning.",
"example": 0
},
"purchased_split_pages_with_learning": {
"type": "integer",
"description": "Number of purchased split pages with learning.",
"example": 0
},
"purchased_split_pages_without_learning": {
"type": "integer",
"description": "Number of purchased split pages without learning.",
"example": 0
},
"purchased_extracted_documents_with_learning": {
"type": "integer",
"description": "Number of purchased extracted documents with learning.",
"example": 0
},
"purchased_extracted_documents_without_learning": {
"type": "integer",
"description": "Number of purchased extracted documents without learning.",
"example": 0
},
"purchased_split_documents_with_learning": {
"type": "integer",
"description": "Number of purchased split documents with learning.",
"example": 0
},
"purchased_split_documents_without_learning": {
"type": "integer",
"description": "Number of purchased split documents without learning.",
"example": 0
},
"purchased_ocr_only_pages": {
"type": "integer",
"description": "Number of purchased OCR-only pages.",
"example": 0
},
"purchased_ocr_only_documents": {
"type": "integer",
"description": "Number of purchased OCR-only documents.",
"example": 0
}
}
},
"billing_history_values": {
"allOf": [
{
"$ref": "#/components/schemas/billing_history_values_base"
},
{
"type": "object",
"description": "Billing values for a specific period or grouping.",
"properties": {
"is_current": {
"type": "boolean",
"description": "Whether this is the current billing period.",
"example": true
}
}
}
]
},
"billing_history_totals": {
"allOf": [
{
"$ref": "#/components/schemas/billing_history_values_base"
},
{
"type": "object",
"description": "Total billing values across all periods or groupings."
}
]
},
"order_by": {
"type": "array",
"items": {
"type": "string",
"enum": [
"billable_pages",
"billable_documents",
"non_billable_pages",
"non_billable_documents"
]
},
"description": "List of attributes by which the `results` are to be ordered.",
"example": [
"billable_pages"
]
},
"organization_group": {
"type": "object",
"title": "Organization Group object",
"x-tags": [
"Organization Group"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the organization group.",
"example": 42
},
"name": {
"type": "string",
"description": "Name of the organization group.",
"example": "Rossum group"
},
"is_trial": {
"type": "boolean",
"readOnly": true,
"description": "Property indicates whether this license is a trial license.",
"example": false
},
"is_production": {
"type": "boolean",
"readOnly": true,
"description": "Property indicates whether this licence is a production licence.",
"example": true
},
"deployment_location": {
"type": "string",
"readOnly": true,
"description": "Deployment location identifier.",
"example": "prod-eu"
},
"features": {
"type": [
"object",
"null"
],
"readOnly": true,
"deprecated": true,
"description": "Use the [/features endpoint](/api/organization-group/#retrieve-optional-features) instead. Enabled features (for internal use only).\n",
"example": null
},
"usage": {
"type": "object",
"readOnly": true,
"description": "Enabled priced features (for internal use only).",
"example": {}
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"billing_filters_org_group": {
"allOf": [
{
"$ref": "#/components/schemas/billing_filters_base"
},
{
"type": "object",
"properties": {
"organizations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Filter billed items for the specified organizations to be counted in the report. (Only available for organization groups)",
"example": [
"https://example.rossum.app/api/v1/organization_groups/42/organizations/406"
]
}
}
}
]
},
"group_by_stats_group": {
"type": "array",
"items": {
"type": "string",
"enum": [
"organization",
"queue",
"month",
"week"
]
},
"maxItems": 1,
"description": "List of attributes by which the `results` are to be grouped. Only a single value is supported. Note that 'organization' is only available for organization groups.",
"example": [
"queue"
]
},
"membership_organization": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the organization.",
"example": 321
},
"url": {
"type": "string",
"format": "uri",
"description": "Membership URL of the organization.",
"example": "https://example.rossum.app/api/v1/organization_groups/42/organizations/321"
},
"name": {
"type": "string",
"description": "Name of the organization (not visible in UI).",
"example": "East West Trading Co"
}
}
},
"workspace_url": {
"type": "string",
"format": "uri",
"description": "Workspace URL.",
"example": "https://example.rossum.app/api/v1/workspaces/7540"
},
"membership_queue": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the queue.",
"example": 654
},
"url": {
"type": "string",
"format": "uri",
"description": "Membership URL of the queue.",
"example": "https://example.rossum.app/api/v1/organization_groups/42/queues/654"
},
"name": {
"type": "string",
"description": "Name of the queue.",
"example": "Received invoices"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"description": "Membership URL of the organization."
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/42/organizations/321"
},
"workspace": {
"allOf": [
{
"$ref": "#/components/schemas/workspace_url"
},
{
"description": "Membership URL of the workspace."
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/42/workspaces/12"
}
}
},
"membership_user": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the user.",
"example": 123456
},
"url": {
"type": "string",
"format": "uri",
"description": "Membership URL of the user.",
"example": "https://example.rossum.app/api/v1/organization_groups/42/users/123456"
},
"email": {
"type": "string",
"format": "email",
"description": "Email of the user.",
"example": "john-doe@east-west-trading.com"
},
"username": {
"type": "string",
"description": "Username of a user.",
"example": "JohnDoe"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"description": "Related organization."
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/42/organizations/321"
}
}
},
"membership_workspace": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the workspace.",
"example": 345
},
"url": {
"type": "string",
"format": "uri",
"description": "Membership URL of the workspace.",
"example": "https://example.rossum.app/api/v1/organization_groups/42/workspaces/345"
},
"name": {
"type": "string",
"description": "Name of the workspace.",
"example": "East West Trading Co"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"description": "Membership URL of the organization."
}
],
"example": "https://example.rossum.app/api/v1/organization_groups/42/organizations/123"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Membership URLs of the queues.",
"example": [
"https://example.rossum.app/api/v1/organization_groups/42/queues/1",
"https://example.rossum.app/api/v1/organization_groups/42/queues/2"
]
}
}
},
"page_object": {
"type": "object",
"title": "Page object",
"x-tags": [
"Page"
],
"properties": {
"id": {
"type": "integer",
"description": "ID of the page",
"readOnly": true,
"example": 558598
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the page.",
"readOnly": true,
"example": "https://example.rossum.app/api/v1/pages/558598"
},
"annotation": {
"type": "string",
"format": "uri",
"description": "Annotation that page belongs to.",
"example": "https://example.rossum.app/api/v1/annotations/314528"
},
"number": {
"type": "integer",
"description": "Page index, first page has index 1.",
"example": 1
},
"rotation_deg": {
"type": "integer",
"description": "Page rotation.",
"example": 0
},
"mime_type": {
"type": "string",
"description": "MIME type of the page (`image/png`).",
"readOnly": true,
"example": "image/png"
},
"s3_name": {
"type": "string",
"description": "Storage key of the page file. Internal use only.",
"readOnly": true,
"example": "7eb0dcc0faa8868b55fb425d21cc60dd"
},
"content": {
"type": "string",
"format": "uri",
"description": "Link to the page raw content (e.g. pdf file).",
"example": "https://example.rossum.app/api/v1/pages/558598/content"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"width": {
"type": [
"integer",
"null"
],
"description": "Page width in pixels (for internal purposes only)",
"readOnly": true,
"example": null
},
"height": {
"type": [
"integer",
"null"
],
"description": "Page height in pixels (for internal purposes only)",
"readOnly": true,
"example": null
}
}
},
"queue": {
"type": "object",
"title": "Queue object",
"x-tags": [
"Queue"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the queue.",
"example": 8198
},
"name": {
"type": "string",
"maxLength": 255,
"description": "Name of the queue (max. 255 characters).",
"example": "Received invoices"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the queue.",
"example": "https://example.rossum.app/api/v1/queues/8198"
},
"workspace": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Workspace in which the queue should be placed (it can be set to `null`, but bare in mind that it will make the queue invisible in the Rossum UI and it may cause some unexpected consequences).",
"example": "https://example.rossum.app/api/v1/workspaces/7540"
},
"connector": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Connector associated with the queue.",
"default": null,
"example": null
},
"webhooks": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"deprecated": true,
"description": "(Deprecated) Webhooks associated with the queue (serves as an alias for `hooks` attribute).\n",
"default": [],
"example": []
},
"hooks": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Hooks associated with the queue.",
"default": [],
"example": []
},
"schema": {
"type": "string",
"format": "uri",
"description": "Schema which will be applied to annotations in this queue.",
"example": "https://example.rossum.app/api/v1/schemas/31336"
},
"inbox": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Inbox for import to this queue.",
"default": null,
"example": "https://example.rossum.app/api/v1/inboxes/1229"
},
"users": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Users associated with this queue.",
"default": [],
"example": [
"https://example.rossum.app/api/v1/users/10775"
]
},
"session_timeout": {
"type": "string",
"description": "Time before annotation will be returned from `reviewing` status to `to_review` (timeout is evaluated every 10 minutes).",
"default": "01:00:00",
"example": "01:00:00"
},
"rir_url": {
"type": [
"string",
"null"
],
"format": "uri",
"deprecated": true,
"description": "(Deprecated) Use `generic_engine` or `dedicated_engine` to set AI Core Engine.\n\n\nSince April 5, 2022, `rir_url` and `agenda` in `rir_params` is no longer used to set AI Engine to the Queue. To change engine use attributes `generic_engine` and `dedicated_engine`. Queues created with parameter `rir_url` will have corresponding `generic_engine` or `dedicated_engine` set automatically.\n\n",
"default": null
},
"rir_params": {
"type": [
"string",
"null"
],
"description": "URL parameters to be passed to the AI Core Engine. More specific AI Core Engine parameters influencing the extraction may be set using this field.\n\nPublicly available parameters:\n- `effective_page_count` (int): Limits the extraction to the first `effective_page_count` pages of the document. Useful to prevent data extraction from additional pages of unrelated, but included documents. Default: 32 (pages to be extracted from a document).\n- `tables` (boolean): Allows disabling line item data extraction. Useful to speed up data extraction when line item details are not required, especially on long documents with large tables. Default: true (line items are being extracted).\n",
"default": null,
"example": null
},
"dedicated_engine": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Dedicated engine used for processing documents uploaded to this queue. If `dedicated_engine` is set `generic_engine` must be `null`. If both engines are `null`, a default generic one gets set.\n",
"default": null,
"example": null
},
"generic_engine": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Generic engine used for processing documents uploaded to this queue. If `generic_engine` is set `dedicated_engine` must be `null`. If both engines are `null`, a default generic one gets set.\n",
"default": null,
"example": "https://example.rossum.app/api/v1/generic_engines/3000"
},
"counts": {
"type": "object",
"readOnly": true,
"description": "Count of annotations per status.",
"properties": {
"importing": {
"type": "integer",
"example": 0
},
"split": {
"type": "integer",
"example": 0
},
"failed_import": {
"type": "integer",
"example": 0
},
"to_review": {
"type": "integer",
"example": 2
},
"reviewing": {
"type": "integer",
"example": 0
},
"confirmed": {
"type": "integer",
"example": 0
},
"exporting": {
"type": "integer",
"example": 0
},
"postponed": {
"type": "integer",
"example": 0
},
"failed_export": {
"type": "integer",
"example": 0
},
"exported": {
"type": "integer",
"example": 0
},
"deleted": {
"type": "integer",
"example": 0
},
"purged": {
"type": "integer",
"example": 0
},
"rejected": {
"type": "integer",
"example": 0
}
}
},
"default_score_threshold": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "Threshold used to automatically validate field content based on AI confidence scores.\n\n\nThe old behavior enabled `default_score_threshold` set to null on queue. When threshold on queue was set to null then default value 0.975 was used. Starting from February 24, 2020 setting of default_score_threshold to null is deprecated. Due to backward compatibility if null value is passed then default value 0.8 is set to `default_score_threshold`.\n\n",
"default": 0.8,
"example": 0.8
},
"automation_enabled": {
"type": "boolean",
"description": "Toggle for switching automation on/off.",
"default": false,
"example": false
},
"automation_level": {
"type": "string",
"enum": [
"never",
"confident",
"always"
],
"description": "Set level of automation. `always` - Auto-export all documents with no validation errors. When there is an error triggered for a non-required field, such values are deleted and export is re-tried. `confident` - Auto-export documents with at least one validation source and no validation errors. `never` - Annotation is not automatically exported and must be validated in UI manually.",
"default": "never",
"example": "never"
},
"locale": {
"type": "string",
"description": "Typical originating region of documents processed in this queue specified in the locale format. If `auto` option is chosen, the locale will be detected automatically if the organization group has access to Aurora engine. Otherwise, default option (`en_GB`) will be used.\n\nThe `locale` field is a hint for the AI Engine on how to resolve some ambiguous cases during data extraction, concerning e.g. date formats or decimal separators that may depend on the locale. For example, in US the typical date format is mm/dd/yyyy whilst in Europe it is dd.mm.yyyy. A date such as \"12. 6. 2018\" will be extracted as Jun 12 when locale is `en_GB`, while the same date will be extracted as Dec 6 when locale is `en_US`.\n",
"default": "en_GB",
"example": "en_US"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"use_confirmed_state": {
"type": "boolean",
"description": "Affects exporting - when `true`, confirm endpoint transitions annotation to `confirmed` status instead to `exporting`.",
"default": false,
"example": false
},
"document_lifetime": {
"type": [
"string",
"null"
],
"description": "Data retention period -- annotations will be automatically purged this time after their creation. The format of the value is '[DD] [HH:[MM:]]ss[.uuuuuu]', e.g. 90 days retention can be set as '90 00:00:00'. Please keep in mind that purging documents in Rossum can limit its learning capabilities. This is a priced feature and has no effect unless enabled.",
"default": null,
"example": "01:00:00"
},
"status": {
"type": "string",
"enum": [
"active",
"deletion_requested",
"deletion_in_progress",
"deletion_failed"
],
"readOnly": true,
"description": "Current status of the queue. `active` - This is the default status. Queue is usable. `deletion_requested` - Queue is marked for deletion (by calling `DELETE /v1/queues/`). Will be asynchronously deleted after `delete_after`. `deletion_in_progress` - Queue is currently being deleted. When a queue has this status some raise conditions may occur as the related objects are being gradually deleted. `deletion_failed` - Something wrong happened in the process of queue deletion. The queue may be in an inconsistent state.\n\nPlease note, that document import (via upload as well as email) is disabled while the queue status is one of `deletion_requested`, `deletion_in_progress`, `deletion_failed`.\n",
"default": "active",
"example": "active"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
},
"settings": {
"type": "object",
"description": "Queue UI settings.",
"default": {},
"properties": {
"columns": {
"type": "array",
"deprecated": true,
"description": "(Deprecated, use `annotation_list_table` instead) List that contains schema ids to be shown on a dashboard.",
"default": [],
"items": {
"type": "object"
}
},
"hide_export_button": {
"type": "boolean",
"description": "Toggle to uncover \"Export\" button on dashboard (useful when `queue.use_confirmed_state = true`), which allows manual export of annotations in `confirmed` status.",
"default": true,
"example": true
},
"autopilot": {
"type": [
"object",
"null"
],
"description": "Autopilot configuration describing which fields can be confirmed automatically.",
"default": null,
"example": null
},
"accepted_mime_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of MIME types which can be uploaded to the queue. This can contain wildcards such as `image/*` or exact type like `application/pdf`.",
"default": [],
"example": []
},
"asynchronous_export": {
"type": "boolean",
"deprecated": true,
"description": "(Deprecated) Always set to `true`. The confirm endpoint returns immediately and hooks' and connector's `save` endpoint is called asynchronously later on. This value is used only when queue does not have a connector.",
"default": true,
"example": true
},
"automation": {
"type": "object",
"description": "Queue automation settings.",
"default": {},
"properties": {
"automate_duplicates": {
"type": "boolean",
"description": "When set to `true`, automation will be enabled for documents that have a duplicates. Disabled if parameter is `false`.",
"default": true,
"example": true
},
"automate_suggested_edit": {
"type": "boolean",
"description": "When set to `true`, automation will be enabled for annotations containing suggested edits. Disabled if parameter is `false`.",
"default": false,
"example": false
}
}
},
"rejection_config": {
"type": "object",
"description": "Queue rejection settings.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Dashboard `Rejected` is visible in application when enabled is set to `true`.",
"default": true,
"example": true
}
}
},
"suggested_recipients_sources": {
"type": "array",
"description": "Queue suggested email recipients settings.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"email_header",
"extracted_value",
"vendor_database",
"queue_mailing_history",
"organization_users"
],
"description": "Indicates source of the suggested recipients email address. `email_header` - Email is taken from the sender in header of the email. `extracted_value` - Email is extracted from annotation data - schema_id is used to find requested value. `vendor_database` - Email is extracted from annotation data - schema_id is used to find requested value. Value is filled by vendor matching connector. `queue_mailing_history` - Emails are taken from all the recipient inside all the emails send inside the email's queue. `organization_users` - Emails are taken from the users of related organization.",
"default": "email_header",
"example": "email_header"
},
"schema_id": {
"type": "string",
"description": "Used for finding appropriate datapoint value in annotation data (necessary only for vendor_database and extracted_value sources).",
"example": ""
}
}
}
},
"suggested_edit": {
"type": "string",
"enum": [
"suggest",
"disable"
],
"description": "Allow to split document (semi-)automatically. Allowed values are `suggest` and `disable`.",
"default": "disable",
"example": "disable"
},
"dashboard_customization": {
"type": "object",
"description": "Dashboard customization settings.",
"properties": {
"all_documents": {
"type": "boolean",
"description": "When set to `true`, all UI tabs are merged into one, so the documents with different statuses are mixes in one tab instead of having its own one.",
"default": false,
"example": false
},
"confirmed": {
"type": "boolean",
"description": "When set to `true`, UI tab for `confirmed` documents will be shown. Relates to the queue settings attribute `use_confirmed_state` is set to true.",
"default": true,
"example": true
},
"deleted": {
"type": "boolean",
"description": "When set to `true`, UI tab for documents in `deleted` state will be shown.",
"default": true,
"example": true
},
"exported": {
"type": "boolean",
"description": "When set to `true`, UI tab for documents in `exported` state will be shown.",
"default": true,
"example": true
},
"postponed": {
"type": "boolean",
"description": "When set to `true`, UI tab for documents in `postponed` state will be shown.",
"default": true,
"example": true
},
"rejected": {
"type": "boolean",
"description": "When set to `true`, UI tab for documents in `rejected` state will be shown.",
"default": true,
"example": true
},
"to_review": {
"type": "boolean",
"description": "When set to `true`, UI tab for documents in `to_review` state will be shown.",
"default": true,
"example": true
}
}
},
"email_notifications": {
"type": "object",
"description": "Queue email notifications settings.",
"properties": {
"recipient": {
"type": [
"object",
"null"
],
"description": "Information about email address to send notifications to (e.g. about failed import). It contains keys `email` and `name`.",
"default": null,
"properties": {
"email": {
"type": "string",
"format": "email",
"example": "john.doe@company.com"
},
"name": {
"type": "string",
"example": "John Doe"
}
}
},
"unprocessable_attachments": {
"type": "boolean",
"description": "Whether return back unprocessable attachments (e.g. MS Word docx) or just silently ignore them. When true, minimum image size requirement does not apply.",
"default": false,
"example": false
},
"email_with_no_attachments": {
"type": "boolean",
"description": "Whether to send notification when no processable documents were found.",
"default": true,
"example": true
},
"postponed_annotations": {
"type": "boolean",
"description": "Whether to send notification when annotation is postponed.",
"default": false,
"example": false
},
"deleted_annotations": {
"type": "boolean",
"description": "Whether to send notification when annotation is deleted.",
"default": false,
"example": false
}
}
},
"workflows": {
"type": "object",
"description": "Queue workflows settings. Talk to your Rossum representative to enable [workflows](tag#Workflows) for your queue.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Dashboard `Workflows` is visible in application when enabled is set to `true`. Also enables the workflow automation.",
"default": false,
"example": false
},
"bypass_workflows_allowed": {
"type": "boolean",
"description": "Whether to allow to confirm annotation with option `skip_workflows=true`.",
"default": false,
"example": false
}
}
},
"annotation_list_table": {
"type": "object",
"description": "Configuration of annotation dashboard columns.",
"default": {},
"properties": {
"columns": {
"type": "array",
"description": "Configuration of columns on annotation dashboard.",
"default": [],
"items": {
"$ref": "#/components/schemas/annotation_list_table"
}
}
}
},
"upload_values": {
"type": "array",
"description": "Configuration of values to be specified during upload.",
"default": [],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the value."
},
"type": {
"type": "string",
"enum": [
"values",
"metadata"
],
"description": "Type of the value - `values` or `metadata` — specify how to pass the value.",
"default": "values"
},
"data_type": {
"type": "string",
"enum": [
"enum",
"string"
],
"description": "Data type of the value - `enum` or `string`.",
"default": "string"
},
"label": {
"type": "string",
"description": "Label to be used in UI."
},
"enum_options": {
"type": [
"array",
"null"
],
"description": "List of objects with `value` and `label` fields. Only allowed for `enum` type.",
"default": null,
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
},
"required": {
"type": "boolean",
"description": "Whether the value is required to be set during upload.",
"default": false
}
}
}
},
"ui_upload_enabled": {
"type": "boolean",
"description": "Flag for enabling upload for particular queue in Rossum UI.",
"default": true,
"example": true
},
"ui_on_edit_confirm": {
"type": "string",
"enum": [
"annotation_list",
"edit_next",
"validate_first"
],
"description": "Changes edit screen confirm button behavior. Allowed values are `annotation_list`, `edit_next`, `validate_first`.",
"default": "validate_first",
"example": "validate_first"
},
"ui_validation_screen_enabled": {
"type": "boolean",
"description": "Flag for enabling validation screen for a particular queue in Rossum UI. If disabled, opening of a document will trigger a redirect to an edit screen.",
"default": true,
"example": true
},
"ui_edit_values": {
"type": "array",
"description": "Configuration of values to be specified during edit_pages.",
"default": [],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the value."
},
"label": {
"type": "string",
"description": "Label to be used in UI."
},
"data_type": {
"type": "string",
"enum": [
"enum",
"string"
],
"description": "Type of the value - `enum` or `string`."
},
"enum_options": {
"type": [
"array",
"null"
],
"description": "List of objects with `value` and `label` fields. Only allowed for `enum` data_type.",
"default": null,
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
},
"required": {
"type": "boolean",
"description": "Whether the value is required to be set during edit.",
"default": false
}
}
}
}
}
},
"workflows": {
"type": "array",
"description": "Workflows set for the queue.",
"default": [],
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Url of the workflow object.",
"example": "https://example.rossum.app/api/v1/workflows/7540"
},
"priority": {
"type": "integer",
"description": "Priority of the linked workflow. Designate the order of their evaluation (lower number means it's evaluated sooner).",
"example": 2
}
}
}
}
}
},
"relation": {
"type": "object",
"title": "Relation object",
"x-tags": [
"Relation"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the relation",
"example": 1
},
"type": {
"type": "string",
"description": "Type of relationship. Possible values are `edit`, `attachment` or `duplicate`.\n\n- `edit` relation is created after editing annotation in user interface (rotation or split of the document)\n- `attachment` is a relationship representing the state that one or more documents are attachments to another document\n- `duplicate` relation is created after importing the same document that already exists in Rossum for current organization\n",
"enum": [
"edit",
"attachment",
"duplicate"
],
"default": "edit",
"example": "edit"
},
"key": {
"type": [
"string",
"null"
],
"description": "Key used to distinguish several instances of the same type.\n\n- For `attachment` relations, this is null\n- For `duplicate` relations, this is set to a hash of document content\n- For `edit` relations, this is typically null\n",
"example": null
},
"parent": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "URL of the parent annotation in case of 1-M relationship",
"example": "https://example.rossum.app/api/v1/annotations/123"
},
"annotations": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of related annotations",
"example": [
"https://example.rossum.app/api/v1/annotations/124",
"https://example.rossum.app/api/v1/annotations/125"
]
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the relation",
"example": "https://example.rossum.app/api/v1/relations/1"
}
}
},
"rule_base": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Rule object ID.",
"example": 123
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Rule object URL.",
"example": "https://example.rossum.app/api/v1/rules/123"
},
"name": {
"type": "string",
"description": "Name of the rule.",
"example": "rule"
},
"description": {
"type": "string",
"description": "Description of the rule.",
"default": "",
"example": "Flags invoices missing a required purchase order number."
},
"enabled": {
"type": "boolean",
"description": "If false the rule is disabled.",
"default": true,
"example": true
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of queues the rule belongs to.",
"example": [
"https://example.rossum.app/api/v1/queues/101",
"https://example.rossum.app/api/v1/queues/102"
]
},
"trigger_condition": {
"type": "string",
"description": "A condition for triggering the rule's actions. This is a formula evaluated by Rossum TxScript. See [Trigger Condition](/guides/using-triggers#trigger-condition) for details.",
"default": "True",
"example": "True"
},
"created_by": {
"type": "string",
"format": "uri",
"description": "User who created the rule.",
"example": "https://example.rossum.app/api/v1/users/9524"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the rule creation.",
"example": "2022-01-01T15:02:25.653324Z"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"action_base": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Rule action ID. Needs to be unique within the Rule's actions.",
"example": "f3c43f16-b5f1-4ac8-b789-17d4c26463d7"
},
"enabled": {
"type": "boolean",
"description": "If false the action is disabled.",
"default": true,
"example": true
},
"type": {
"type": "string",
"description": "Type of the action to be executed.",
"enum": [
"show_message",
"add_automation_blocker",
"change_status",
"change_queue",
"add_label",
"remove_label",
"show_field",
"hide_field",
"add_validation_source",
"send_email",
"custom",
"exclude_from_training"
],
"example": "show_message"
},
"event": {
"type": "string",
"description": "Event on which the action should be triggered.",
"enum": [
"validation",
"annotation_imported",
"annotation_confirmed",
"annotation_exported"
],
"example": "validation"
}
}
},
"action_show_message_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n",
"properties": {
"type": {
"type": "string",
"enum": [
"error",
"warning",
"info"
],
"description": "Type of message",
"example": "error"
},
"content": {
"type": "string",
"description": "Message content to be displayed.",
"example": "No vendor found!"
},
"schema_id": {
"type": "string",
"description": "Optional message target field (omit for document scope message).",
"example": "vendor_id"
}
}
},
"action_show_message": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_show_message_base"
}
}
}
]
},
"action_add_automation_blocker_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n\nNote: at most one action of type `add_automation_blocker` can be set up for one rule object.\n",
"properties": {
"content": {
"type": "string",
"description": "Automation blocker content to be displayed.",
"example": "No validation"
},
"schema_id": {
"type": "string",
"description": "Optional automation blocker target field id (omit for document scope automation blocker).",
"example": "vendor_id"
}
}
},
"action_add_automation_blocker": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_add_automation_blocker_base"
}
}
}
]
},
"action_change_status_base": {
"type": "object",
"description": "Event: can be triggered on `annotation_imported` event only.\n\nNote: at most one action of type `change_status` can be set up for one rule object.\n",
"properties": {
"method": {
"type": "string",
"enum": [
"postpone",
"export",
"delete",
"confirm",
"reject"
],
"description": "Method.",
"example": "confirm"
}
}
},
"action_change_status": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_change_status_base"
}
}
}
]
},
"action_change_queue_base": {
"type": "object",
"description": "This action moves the annotation to another queue with or without re-extraction of the data (see the `reimport` flag).\n\nEvent: Can be configured to trigger on `annotation_imported`, `annotation_confirmed` or `annotation_exported`.\n\nNote: at most one action of type change_queue can be set up for one rule object.\n",
"properties": {
"reimport": {
"type": "boolean",
"description": "Flag that controls whether the annotation will be reimported during the action execution.",
"example": true
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
},
{
"description": "Target queue."
}
]
}
}
},
"action_change_queue": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_change_queue_base"
}
}
}
]
},
"action_add_label_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n\nNote: at most one action of type `add_label` can be set up for one rule object.\n",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string",
"format": "uri",
"description": "URLs of label object to be linked to the processed annotation.",
"example": "https://example.rossum.app/api/v1/labels/12"
}
}
}
},
"action_add_label": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_add_label_base"
}
}
}
]
},
"action_remove_label_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n\nNote: at most one action of type `remove_label` can be set up for one rule object.\n",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string",
"format": "uri",
"description": "URLs of label object to be unlinked from the processed annotation.",
"example": "https://example.rossum.app/api/v1/labels/12"
}
}
}
},
"action_remove_label": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_remove_label_base"
}
}
}
]
},
"action_add_remove_label_base": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"description": "The affected labels are added to the annotation when the condition is satisfied, and removed otherwise.\nCan be triggered on `validation` event only.\n\nNote: at most one action of type `add_remove_label` can be set up for one [rule](#rule) object.\n",
"properties": {
"type": {
"type": "string",
"enum": [
"add_remove_label"
],
"description": "Action type."
},
"payload": {
"type": "object",
"description": "Action payload.",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "URLs of label objects to be linked to the processed annotation."
}
},
"required": [
"labels"
]
}
}
}
]
},
"action_add_remove_label": {
"allOf": [
{
"$ref": "#/components/schemas/action_add_remove_label_base"
}
]
},
"action_show_field_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n\nNote: at most one action of type `show_field` can be set up for one rule object.\n",
"properties": {
"schema_ids": {
"description": "List of schema IDs of fields to show (set `hidden` attribute to `false`).",
"type": "array",
"items": {
"type": "string"
},
"example": [
"vendor_id",
"invoice_id"
]
}
}
},
"action_show_field": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_show_field_base"
}
}
}
]
},
"action_hide_field_base": {
"type": "object",
"description": "Event: can be triggered on `validation` event only.\n\nNote: at most one action of type `hide_field` can be set up for one rule object.\n",
"properties": {
"schema_ids": {
"description": "List of schema IDs of fields to hide (set `hidden` attribute to `true`).",
"type": "array",
"items": {
"type": "string"
},
"example": [
"vendor_id",
"invoice_id"
]
}
}
},
"action_hide_field": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_hide_field_base"
}
}
}
]
},
"action_show_hide_field_base": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"description": "The affected schema fields are visible when the condition is satisfied, and hidden otherwise. Can be triggered on `validation` event only.",
"properties": {
"type": {
"type": "string",
"enum": [
"show_hide_field"
],
"description": "Action type."
},
"payload": {
"type": "object",
"description": "Action payload. The affected schema fields are visible when the condition is satisfied, and hidden otherwise.",
"properties": {
"schema_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of schema IDs of fields to show/hide according to condition (sets `hidden` attribute). See [schema content](#schema-content).",
"example": [
"vendor_id",
"invoice_id"
]
}
},
"required": [
"schema_ids"
]
}
}
}
]
},
"action_show_hide_field": {
"allOf": [
{
"$ref": "#/components/schemas/action_show_hide_field_base"
}
]
},
"action_add_validation_source": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_add_validation_source"
}
}
}
]
},
"action_send_email_base": {
"type": "object",
"properties": {
"email_template": {
"type": [
"string",
"null"
],
"format": "url",
"description": "Email template URL.",
"example": "https://example.rossum.app/api/v1/email_templates/123"
},
"attach_document": {
"type": "boolean",
"description": "When true document linked to the annotation will be sent together with the email as an attachment. Only applicable if `email_template` is not `null`.",
"default": false,
"example": true
},
"to": {
"type": "array",
"description": "List of recipients. Only allowed if `email_template` is not defined. Ignored if `email_template` is `null`.",
"items": {
"type": "string",
"example": "john.doe@example.com"
}
},
"subject": {
"type": "string",
"description": "Subject of the email. Ignored if `email_template` is `null`.",
"example": "No PO found"
},
"body": {
"type": "string",
"description": "Body of the email. Ignored if `email_template` is `null`.",
"example": "Hello, no purchase order was not found. Truly Yours --agent"
},
"cc": {
"type": "array",
"description": "List of cc. Ignored if `email_template` is `null`.",
"items": {
"type": "string",
"example": "john.doe@example.com"
}
},
"bcc": {
"type": "array",
"description": "List of bcc. Ignored if `email_template` is `null`.",
"items": {
"type": "string",
"example": "john.doe@example.com"
}
}
}
},
"action_send_email": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"$ref": "#/components/schemas/action_send_email_base"
}
}
}
]
},
"action_custom": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"properties": {
"payload": {
"type": "object",
"properties": {}
}
}
}
]
},
"action_exclude_from_training": {
"allOf": [
{
"$ref": "#/components/schemas/action_base"
},
{
"type": "object",
"description": "This action sets `training_enabled` to `false` on the annotation, excluding it from being used for AI training.\n\nEvent: Can be configured to trigger on `annotation_confirmed` or `annotation_exported`.\n\nNote: at most one action of type exclude_from_training can be set up for one rule object.\n",
"properties": {
"type": {
"type": "string",
"enum": [
"exclude_from_training"
]
},
"event": {
"type": "string",
"enum": [
"annotation_confirmed",
"annotation_exported"
]
}
}
}
]
},
"rule": {
"type": "object",
"title": "Rule object",
"x-tags": [
"Rule"
],
"allOf": [
{
"$ref": "#/components/schemas/rule_base"
},
{
"type": "object",
"properties": {
"actions": {
"type": "array",
"description": "List of the rule action objects.",
"items": {
"type": "object",
"title": "Rule action",
"oneOf": [
{
"$ref": "#/components/schemas/action_show_message"
},
{
"$ref": "#/components/schemas/action_add_automation_blocker"
},
{
"$ref": "#/components/schemas/action_change_status"
},
{
"$ref": "#/components/schemas/action_change_queue"
},
{
"$ref": "#/components/schemas/action_add_label"
},
{
"$ref": "#/components/schemas/action_remove_label"
},
{
"$ref": "#/components/schemas/action_add_remove_label"
},
{
"$ref": "#/components/schemas/action_show_field"
},
{
"$ref": "#/components/schemas/action_hide_field"
},
{
"$ref": "#/components/schemas/action_show_hide_field"
},
{
"$ref": "#/components/schemas/action_add_validation_source"
},
{
"$ref": "#/components/schemas/action_send_email"
},
{
"$ref": "#/components/schemas/action_custom"
},
{
"$ref": "#/components/schemas/action_exclude_from_training"
}
]
}
}
}
}
]
},
"rules_execution_log": {
"type": "object",
"properties": {
"rule_id": {
"type": "integer",
"description": "ID of the rule that was executed.",
"example": 123
},
"rule_name": {
"type": "string",
"description": "Name of the rule at the time of execution.",
"example": "Auto-confirm invoices over $1000"
},
"queue_id": {
"type": "integer",
"description": "ID of the queue where the rule was triggered.",
"example": 456
},
"annotation_id": {
"type": "integer",
"description": "ID of the annotation that triggered the rule.",
"example": 789
},
"request_id": {
"type": "string",
"description": "Unique identifier for this rule execution request.",
"example": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the rule was executed.",
"example": "2024-01-15T10:30:00.000000Z"
},
"trigger_event": {
"type": "string",
"description": "Event that triggered the rule evaluation.",
"example": "annotation_imported"
},
"trigger_condition": {
"type": "string",
"description": "The trigger condition expression that was evaluated.",
"example": "field.amount_total > 1000"
},
"trigger_condition_results": {
"type": [
"array",
"null"
],
"items": {
"type": "boolean"
},
"description": "Array of boolean results from trigger condition evaluation.\n\n- **Regular rules**: Array with a single element (e.g., `[true]}`)\n- **Line item rules**: One result per line item row (e.g., `[false, true, true]` for 3 rows where rows 1 and 2 matched)\n\nAll arrays (`trigger_condition_results`, `trigger_condition_values`, `actions`) are aligned by index for line item rules.\n",
"example": [
true
]
},
"trigger_condition_values": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Array of objects containing the field values used in trigger condition evaluation. Keys are schema IDs referenced in the trigger condition.\n\n- **Regular rules**: Array with a single object (e.g., `[{\"amount_total\": \"1500.00\"}]`)\n- **Line item rules**: One object per line item row, each containing that row's field values (e.g., `[{\"item_price\": \"80\"}, {\"item_price\": \"150\"}, {\"item_price\": \"90\"}]`)\n\nAligned by index with `trigger_condition_results` and `actions`.\n",
"example": [
{
"amount_total": "1500.00"
}
]
},
"execution_result": {
"type": "string",
"enum": [
"success",
"failure",
"partial_success"
],
"description": "Overall result of the rule execution.\n\n- `success`: All actions executed successfully.\n- `failure`: All actions failed to execute.\n- `partial_success`: Some actions succeeded while others failed (for line item rules).\n",
"example": "success"
},
"execution_error": {
"type": [
"string",
"null"
],
"description": "Error message if the rule execution failed.",
"example": null
},
"actions": {
"type": [
"array",
"null"
],
"items": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"additionalProperties": true
}
},
"description": "Array of executed actions per trigger condition result. `null` if all conditions were false.\n\n- **Regular rules**: Array with a single element containing all actions (e.g., `[[action1, action2]]`)\n- **Line item rules**: One element per line item row, aligned with `trigger_condition_results`. Elements are `null` for rows where the condition was false (e.g., `[null, [action], null]` for 3 rows where only row 1 matched)\n\nFor line item rules, builtin actions (`show_message`, `add_automation_blocker`) are replicated for each matching row, while handler actions (`send_email`, `add_label`, etc.) are distributed one-to-one to matching rows.\n",
"example": [
[
{
"action_id": "a1",
"action_type": "send_email",
"execution_result": "success",
"execution_error": null,
"payload": {
"to": [
"accountant@example.com"
],
"cc": [
"manager@example.com"
],
"subject": "Invoice processed",
"body": "Invoice has been processed successfully.",
"attach_document": true
}
},
{
"action_id": "a2",
"action_type": "add_label",
"execution_result": "success",
"execution_error": null,
"payload": {
"labels": [
"https://example.rossum.app/api/v1/labels/123"
]
}
},
{
"action_id": "a3",
"action_type": "change_status",
"execution_result": "success",
"execution_error": null,
"payload": {
"method": "postpone"
}
}
]
]
}
},
"required": [
"rule_id",
"rule_name",
"queue_id",
"annotation_id",
"request_id",
"created_at",
"trigger_event",
"trigger_condition",
"execution_result"
]
},
"rules_execution_logs_response": {
"type": "object",
"required": [
"results",
"pagination"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/rules_execution_log"
},
"description": "List of rule execution log entries."
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"schema_base": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the schema.",
"example": 31336
},
"name": {
"type": "string",
"description": "Name of the schema (not visible in UI).",
"example": "Basic Schema"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the schema.",
"example": "https://example.rossum.app/api/v1/schemas/31336"
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of queues that use schema object.",
"example": [
"https://example.rossum.app/api/v1/queues/8236"
]
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"object_base": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 50,
"description": "Unique identifier of an object. Maximum length is 50 characters."
},
"label": {
"type": "string",
"description": "User-friendly label for an object, shown in the user interface."
},
"hidden": {
"type": "boolean",
"default": false,
"description": "If set to true, the object is not visible in the user interface, but remains stored in the database and may be exported. Default is false. Note that section is hidden if all its children are hidden."
},
"disable_prediction": {
"type": "boolean",
"default": false,
"description": "Can be set to true to disable field extraction, while still preserving the data shape. Ignored by aurora engines."
}
}
},
"section_base": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"section"
]
},
"icon": {
"type": [
"string",
"null"
],
"description": "The icon that appears on the left panel in the UI for a given section (not yet supported on UI)."
}
}
},
"multivalue_base": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"multivalue"
]
},
"min_occurrences": {
"type": [
"integer",
"null"
],
"minimum": 0,
"default": 0,
"description": "Minimum number of occurrences of nested objects. If condition of min_occurrences is violated corresponding fields should be manually reviewed. Minimum required value for the field is 0. If not specified, it is set to 0 by default."
},
"max_occurrences": {
"type": [
"integer",
"null"
],
"minimum": 1,
"default": 1000,
"description": "Maximum number of occurrences of nested objects. All additional rows above max_occurrences are removed by extraction process. Minimum required value for the field is 1. If not specified, it is set to 1000 by default."
},
"show_grid_by_default": {
"type": "boolean",
"default": false,
"description": "If set to true, the magic-grid is opened instead of footer upon entering the multivalue. Default false. Applied only in UI. Useful when annotating documents for custom training."
},
"rir_field_names": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "List of names used to initialize content from the AI engine predictions. If specified, the value of the first field from the array is used, otherwise default name line_items is used. Attribute can be set only for multivalue containing objects with category tuple."
}
}
},
"grid": {
"type": "object",
"description": "Multivalue grid object allows to specify a row type for each row of the grid. Configure magic-grid feature properties.",
"properties": {
"row_types": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"data"
],
"description": "List of allowed row type values."
},
"default_row_type": {
"type": "string",
"default": "data",
"description": "Row type to be used by default."
},
"row_types_to_extract": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"data"
],
"description": "Types of rows to be extracted to related table."
}
}
},
"tuple_base": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"tuple"
]
},
"rir_field_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of names used to initialize content from the AI engine predictions. If specified, the value of the first extracted field from the array is used, otherwise, no AI engine initialization is done for the object."
}
}
},
"datapoint_base": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"datapoint"
]
},
"can_export": {
"type": "boolean",
"default": true,
"description": "If set to false, datapoint is not exported through export endpoint. Default is true."
},
"can_collapse": {
"type": "boolean",
"default": false,
"description": "If set to true, tabular (multivalue-tuple) datapoint may be collapsed in the UI. Default is false."
},
"rir_field_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of references used to initialize an object value."
},
"default_value": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "Default value used either for fields that do not use hints from AI engine predictions (i.e. rir_field_names are not specified), or when the AI engine does not return any data for the field."
},
"ui_configuration": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"enum": [
"captured",
"data",
"manual",
"formula",
"reasoning",
null
],
"default": null,
"description": "Logical type of the datapoint. Possible values are captured, data, manual, formula, reasoning or null. Default value is null."
},
"edit": {
"type": "string",
"enum": [
"enabled",
"disabled",
"enabled_without_warning"
],
"default": "enabled",
"description": "When set to disabled, value of the datapoint is not editable via UI. When set to enabled_without_warning, no warnings are displayed in the UI regarding this fields editing behaviour. Default value is enabled, this option enables field editing, but user receives dismissible warnings when doing so."
}
},
"description": "UI configuration provides a group of settings, which alter behaviour of the field in the application. This does not affect behaviour of the field via the API."
},
"width": {
"type": "integer",
"description": "Width of the column (in characters). Default widths are number 8, string 20, date 10, enum 20. Only supported for table datapoints."
},
"stretch": {
"type": "boolean",
"description": "If total width of columns doesn't fill up the screen, datapoints with stretch set to true will be expanded proportionally to other stretching columns. Only supported for table datapoints."
},
"width_chars": {
"type": "integer",
"deprecated": true,
"description": "(Deprecated) Use width and stretch properties instead."
},
"score_threshold": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Threshold used to automatically validate field content based on AI confidence scores. If not set, queue.default_score_threshold is used."
},
"formula": {
"type": "string",
"maxLength": 2000,
"description": "Formula definition, required only for fields of type formula. rir_field_names should also be empty for these fields."
},
"prompt": {
"type": "string",
"maxLength": 2000,
"description": "Prompt definition, required only for fields of type reasoning."
},
"context": {
"type": "array",
"items": {
"type": "string"
},
"description": "Context for the prompt, required only for fields of type reasoning."
}
}
},
"datapoint_string_base": {
"type": "object",
"title": "string",
"allOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"string"
],
"description": "Data type of the object."
}
}
},
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/datapoint_base"
}
]
},
"datapoint_constraints_base": {
"type": "object",
"properties": {
"length": {
"type": "object",
"properties": {
"min": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Minimum length for the datapoint value."
},
"max": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Maximum length for the datapoint value."
},
"exact": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Exact length for the datapoint value."
}
},
"description": "Defines minimum, maximum or exact length for the datapoint value. By default, minimum and maximum are 0 and infinity, respectively."
},
"required": {
"type": "boolean",
"default": true,
"description": "Specifies if the datapoint is required by the schema. Default value is true."
}
}
},
"datapoint_constraints_regex": {
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "Regular expression pattern that the content must match. To ensure that entire value matches, surround your regular expression with ^ and $."
}
},
"description": "When specified, content must match a regular expression."
},
"datapoint_constraints": {
"type": "object",
"properties": {
"constraints": {
"allOf": [
{
"$ref": "#/components/schemas/datapoint_constraints_base"
},
{
"type": "object",
"properties": {
"regex": {
"allOf": [
{
"$ref": "#/components/schemas/datapoint_constraints_regex"
}
]
}
}
}
]
}
}
},
"datapoint_string": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_string_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints"
}
]
},
"datapoint_number_base": {
"type": "object",
"title": "number",
"allOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"number"
],
"description": "Data type of the object."
}
}
},
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/datapoint_base"
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"description": "Number format.",
"default": "# ##0.#",
"example": "# ##0.#"
},
"aggregations": {
"type": "object",
"properties": {
"sum": {
"type": "object",
"properties": {
"label": {
"type": "string",
"default": "Sum",
"description": "Label that will be shown in the UI for the sum aggregation."
}
},
"description": "Sum of values in a column. Default label is \"Sum\"."
}
},
"description": "Aggregations allow computation of some informative values, e.g. a sum of a table column with numeric values. These are returned among messages when /v1/annotations/{id}/content/validate endpoint is called. Aggregations can be computed only for tables (multivalues of tuples)."
}
}
}
]
},
"datapoint_number": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_number_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints"
}
]
},
"datapoint_date_base": {
"type": "object",
"title": "date",
"allOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"date"
],
"description": "Data type of the object."
}
}
},
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/datapoint_base"
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"description": "Enforces a format for date datapoint on the UI.",
"default": "YYY-MM-DD",
"example": "YYYY-MM-DD"
}
}
}
]
},
"datapoint_date": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_date_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints"
}
]
},
"datapoint_enum_base": {
"type": "object",
"title": "enum",
"allOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"enum"
],
"description": "Data type of the object."
}
}
},
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/datapoint_base"
},
{
"type": "object",
"properties": {
"enum_value_type": {
"type": "string",
"enum": [
"string",
"number",
"date"
],
"description": "Data type of the option's value attribute. Must be one of string, number, date."
}
}
}
]
},
"datapoint_enum_options_item": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "Value of the option."
},
"label": {
"type": "string",
"description": "User-friendly label for the option, shown in the UI."
}
},
"description": "Enum option object with value and label."
},
"datapoint_enum_options": {
"type": "object",
"properties": {
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/datapoint_enum_options_item"
},
"description": "Options for enum datapoint."
}
}
},
"datapoint_enum": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_enum_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints"
},
{
"$ref": "#/components/schemas/datapoint_enum_options"
}
]
},
"datapoint_button_base": {
"type": "object",
"title": "button",
"allOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"button"
],
"description": "Data type of the object."
}
}
},
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/datapoint_base"
},
{
"type": "object",
"properties": {
"popup_url": {
"type": "string",
"format": "uri",
"description": "URL of a popup window to be opened when button is pressed."
},
"can_obtain_token": {
"type": "boolean",
"description": "If set to true the popup window is allowed to ask the main Rossum window for authorization token."
}
}
}
]
},
"datapoint_button": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_button_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints"
}
]
},
"content_datapoint": {
"type": "object",
"title": "datapoint",
"oneOf": [
{
"$ref": "#/components/schemas/datapoint_string"
},
{
"$ref": "#/components/schemas/datapoint_number"
},
{
"$ref": "#/components/schemas/datapoint_date"
},
{
"$ref": "#/components/schemas/datapoint_enum"
},
{
"$ref": "#/components/schemas/datapoint_button"
}
]
},
"content_tuple": {
"type": "object",
"title": "tuple",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/tuple_base"
},
{
"type": "object",
"properties": {
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/content_datapoint"
},
"description": "Array specifying objects that belong to a given tuple. It can contain only objects with category datapoint."
}
}
}
]
},
"multivalue": {
"type": "object",
"title": "multivalue",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/multivalue_base"
},
{
"type": "object",
"properties": {
"grid": {
"$ref": "#/components/schemas/grid"
},
"children": {
"oneOf": [
{
"$ref": "#/components/schemas/content_tuple"
},
{
"$ref": "#/components/schemas/content_datapoint"
}
],
"description": "Object specifying type of children. It may contain only objects with categories tuple or datapoint."
}
}
}
]
},
"section": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/section_base"
},
{
"type": "object",
"properties": {
"children": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/multivalue"
},
{
"$ref": "#/components/schemas/content_datapoint"
}
]
},
"description": "Specifies objects grouped under a given section. It may contain multivalue or datapoint objects."
}
}
}
]
},
"schema": {
"type": "object",
"title": "Schema object",
"x-tags": [
"Schema"
],
"allOf": [
{
"$ref": "#/components/schemas/schema_base"
},
{
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/section"
},
"description": "Schema content: list of sections.\n",
"example": [
{
"category": "section",
"id": "invoice_info_section",
"label": "Basic information",
"icon": null,
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice number",
"type": "string",
"rir_field_names": [
"document_id"
],
"constraints": {
"required": false
},
"default_value": null
},
{
"category": "datapoint",
"id": "date_issue",
"label": "Issue date",
"type": "date",
"format": "YYYY-MM-DD",
"rir_field_names": [
"date_issue"
],
"constraints": {
"required": false
},
"default_value": null
},
{
"category": "datapoint",
"id": "document_type",
"label": "Document type",
"type": "enum",
"options": [
{
"label": "Invoice Received",
"value": "21"
},
{
"label": "Invoice Sent",
"value": "22"
},
{
"label": "Receipt",
"value": "23"
}
],
"enum_value_type": "number",
"default_value": "21",
"rir_field_names": []
}
]
},
{
"category": "section",
"id": "line_items_section",
"label": "Line items",
"icon": null,
"children": [
{
"category": "multivalue",
"id": "line_items",
"label": "Line items",
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": [
"line_items"
],
"children": {
"category": "tuple",
"id": "line_item",
"label": "Line item",
"children": [
{
"category": "datapoint",
"id": "item_desc",
"label": "Description",
"type": "string",
"rir_field_names": [
"table_column_description"
],
"constraints": {
"required": true
},
"stretch": true
},
{
"category": "datapoint",
"id": "item_quantity",
"label": "Quantity",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"table_column_quantity"
],
"constraints": {
"required": false
},
"width": 15
},
{
"category": "datapoint",
"id": "item_amount_total",
"label": "Price w tax",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"table_column_amount_total"
],
"constraints": {
"required": false
},
"aggregations": {
"sum": {
"label": "Total"
}
}
}
]
}
}
]
},
{
"category": "section",
"id": "tax_details_section",
"label": "Tax details",
"icon": null,
"children": [
{
"category": "multivalue",
"id": "tax_details",
"label": "Tax details",
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": [
"tax_details"
],
"children": {
"category": "tuple",
"id": "tax_detail",
"label": "Tax detail",
"children": [
{
"category": "datapoint",
"id": "tax_detail_rate",
"label": "Tax rate",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_rate"
],
"constraints": {
"required": false
},
"width": 15
},
{
"category": "datapoint",
"id": "tax_detail_base",
"label": "Tax base",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_base"
],
"constraints": {
"required": false
}
},
{
"category": "datapoint",
"id": "tax_detail_tax",
"label": "Tax amount",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_tax"
],
"constraints": {
"required": false
}
}
]
}
}
]
}
]
}
}
}
]
},
"datapoint_constraints_w_required": {
"type": "object",
"properties": {
"constraints": {
"allOf": [
{
"$ref": "#/components/schemas/datapoint_constraints_base"
},
{
"type": "object",
"properties": {
"regex": {
"allOf": [
{
"$ref": "#/components/schemas/datapoint_constraints_regex"
}
],
"required": [
"pattern"
]
}
}
}
]
}
}
},
"datapoint_string_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_string_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints_w_required"
}
]
},
"datapoint_number_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_number_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints_w_required"
}
],
"required": [
"category",
"id",
"label",
"type"
]
},
"datapoint_date_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_date_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints_w_required"
}
],
"required": [
"category",
"id",
"label",
"type"
]
},
"datapoint_enum_options_w_required": {
"type": "object",
"properties": {
"options": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/datapoint_enum_options_item"
}
],
"required": [
"value",
"label"
]
},
"description": "Options for enum datapoint."
}
}
},
"datapoint_enum_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_enum_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints_w_required"
},
{
"$ref": "#/components/schemas/datapoint_enum_options_w_required"
}
],
"required": [
"category",
"id",
"label",
"type",
"options"
]
},
"datapoint_button_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/datapoint_button_base"
},
{
"$ref": "#/components/schemas/datapoint_constraints_w_required"
}
],
"required": [
"category",
"id",
"label",
"type"
]
},
"datapoint_w_required": {
"type": "object",
"title": "datapoint",
"oneOf": [
{
"$ref": "#/components/schemas/datapoint_string_w_required"
},
{
"$ref": "#/components/schemas/datapoint_number_w_required"
},
{
"$ref": "#/components/schemas/datapoint_date_w_required"
},
{
"$ref": "#/components/schemas/datapoint_enum_w_required"
},
{
"$ref": "#/components/schemas/datapoint_button_w_required"
}
]
},
"tuple_w_required": {
"type": "object",
"title": "tuple",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/tuple_base"
},
{
"type": "object",
"properties": {
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/datapoint_w_required"
},
"description": "Array specifying objects that belong to a given tuple. It may contain only objects with category datapoint."
}
}
}
],
"required": [
"children"
]
},
"multivalue_w_required": {
"type": "object",
"title": "multivalue",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/multivalue_base"
},
{
"type": "object",
"properties": {
"grid": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/grid"
}
],
"required": [
"row_types",
"default_row_type",
"row_types_to_extract"
]
},
"children": {
"oneOf": [
{
"$ref": "#/components/schemas/tuple_w_required"
},
{
"$ref": "#/components/schemas/datapoint_w_required"
}
],
"description": "Object specifying type of children. It may contain only objects with categories tuple or datapoint."
}
}
}
],
"required": [
"children"
]
},
"section_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/object_base"
},
{
"$ref": "#/components/schemas/section_base"
},
{
"type": "object",
"properties": {
"children": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/multivalue_w_required"
},
{
"$ref": "#/components/schemas/datapoint_w_required"
}
]
},
"description": "Specifies objects grouped under a given section. It may contain multivalue or datapoint objects."
}
}
}
],
"required": [
"children",
"id",
"label"
]
},
"schema_w_required": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/schema_base"
},
{
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/section_w_required"
},
"description": "Schema content: list of sections.\n",
"example": [
{
"category": "section",
"id": "invoice_info_section",
"label": "Basic information",
"icon": null,
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice number",
"type": "string",
"rir_field_names": [
"document_id"
],
"constraints": {
"required": false
},
"default_value": null
},
{
"category": "datapoint",
"id": "date_issue",
"label": "Issue date",
"type": "date",
"format": "YYYY-MM-DD",
"rir_field_names": [
"date_issue"
],
"constraints": {
"required": false
},
"default_value": null
},
{
"category": "datapoint",
"id": "document_type",
"label": "Document type",
"type": "enum",
"options": [
{
"label": "Invoice Received",
"value": "21"
},
{
"label": "Invoice Sent",
"value": "22"
},
{
"label": "Receipt",
"value": "23"
}
],
"enum_value_type": "number",
"default_value": "21",
"rir_field_names": []
}
]
},
{
"category": "section",
"id": "line_items_section",
"label": "Line items",
"icon": null,
"children": [
{
"category": "multivalue",
"id": "line_items",
"label": "Line items",
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": [
"line_items"
],
"children": {
"category": "tuple",
"id": "line_item",
"label": "Line item",
"children": [
{
"category": "datapoint",
"id": "item_desc",
"label": "Description",
"type": "string",
"rir_field_names": [
"table_column_description"
],
"constraints": {
"required": true
},
"stretch": true
},
{
"category": "datapoint",
"id": "item_quantity",
"label": "Quantity",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"table_column_quantity"
],
"constraints": {
"required": false
},
"width": 15
},
{
"category": "datapoint",
"id": "item_amount_total",
"label": "Price w tax",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"table_column_amount_total"
],
"constraints": {
"required": false
},
"aggregations": {
"sum": {
"label": "Total"
}
}
}
]
}
}
]
},
{
"category": "section",
"id": "tax_details_section",
"label": "Tax details",
"icon": null,
"children": [
{
"category": "multivalue",
"id": "tax_details",
"label": "Tax details",
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": [
"tax_details"
],
"children": {
"category": "tuple",
"id": "tax_detail",
"label": "Tax detail",
"children": [
{
"category": "datapoint",
"id": "tax_detail_rate",
"label": "Tax rate",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_rate"
],
"constraints": {
"required": false
},
"width": 15
},
{
"category": "datapoint",
"id": "tax_detail_base",
"label": "Tax base",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_base"
],
"constraints": {
"required": false
}
},
{
"category": "datapoint",
"id": "tax_detail_tax",
"label": "Tax amount",
"type": "number",
"format": "# ##0.#",
"rir_field_names": [
"tax_detail_tax"
],
"constraints": {
"required": false
}
}
]
}
}
]
}
]
}
}
}
],
"required": [
"name",
"content"
]
},
"page_descriptor": {
"type": "object",
"properties": {
"page": {
"type": "string",
"format": "url",
"description": "Page to split.",
"example": "https://example.rossum.app/api/v1/pages/314554"
},
"rotation": {
"type": "integer",
"description": "Rotation of the page.",
"default": 0,
"example": 0
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the page is marked as deleted.",
"default": false,
"example": false
}
}
},
"document_split_descriptor": {
"type": "object",
"properties": {
"pages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/page_descriptor"
},
"description": "List of pages that should be split."
},
"target_queue": {
"type": "string",
"format": "url",
"description": "Target queue for the suggested split.",
"example": "https://example.rossum.app/api/v1/queues/314528"
},
"values": {
"type": "object",
"default": {},
"description": "Edit values to be propagated to newly created annotations. Keys must be prefixed with \"edit:\", e.g. \"edit:document_type\". Schema Datapoint description describes how it is used to initialize datapoint value.",
"example": {
"edit:document_type": "invoice"
}
}
}
},
"suggested_edit": {
"type": "object",
"title": "Suggested Edit object",
"x-tags": [
"Suggested Edit"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true,
"description": "ID of the suggested edit.",
"example": 314528
},
"url": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the suggested edit.",
"example": "https://example.rossum.app/api/v1/suggested_edits/314528"
},
"annotation": {
"type": "string",
"format": "url",
"description": "Annotation that suggested edit is related to.",
"example": "https://example.rossum.app/api/v1/annotations/314528"
},
"documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/document_split_descriptor"
},
"description": "List of document split descriptors."
}
}
},
"task": {
"type": "object",
"title": "Task object",
"x-tags": [
"Task"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Task object ID.",
"example": 1
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Task object URL.",
"example": "https://example.rossum.app/api/v1/tasks/1"
},
"type": {
"type": "string",
"enum": [
"documents_download",
"upload_created",
"email_imported"
],
"example": "documents_download"
},
"status": {
"type": "string",
"enum": [
"running",
"succeeded",
"failed"
],
"example": "succeeded"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of a guaranteed availability of the task object. Expired tasks are being deleted periodically.",
"example": "2021-09-11T09:59:00.000000Z"
},
"detail": {
"type": [
"string",
"null"
],
"description": "Detailed message on the status of the task. For failed tasks, error id is included in the message and can be used in communication with Rossum support for further investigation.",
"example": null
},
"content": {
"type": "object",
"description": "Detailed information related to tasks. Content structure varies by task type:\n- For `documents_download`: contains `file_name` (string) - File name of the archive to be downloaded.\n- For `upload_created`: contains `upload` (url) - URL of the object representing the upload.\n",
"example": {
"file_name": "my-archive.zip"
}
},
"code": {
"type": [
"string",
"null"
],
"description": "Error code.",
"example": null
},
"result_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Succeeded status resulting redirect URL.",
"example": "https://example.rossum.app/api/v1/documents/456700"
}
}
},
"trigger": {
"type": "object",
"title": "Trigger object",
"x-tags": [
"Trigger"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true,
"description": "ID of the trigger",
"example": 234
},
"url": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the trigger",
"example": "https://example.rossum.app/api/v1/triggers/234"
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
}
]
},
"event": {
"type": "string",
"description": "Event that will trigger the trigger (see [trigger event types](/guides/using-triggers#trigger-event-types))",
"example": "annotation_imported"
},
"condition": {
"type": "object",
"description": "A subset of MongoDB Query Language (see [trigger condition](/guides/using-triggers#trigger-condition))",
"default": {},
"example": {}
},
"email_templates": {
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"description": "URLs of the linked email templates",
"example": [
"https://example.rossum.app/api/v1/email_templates/123",
"https://example.rossum.app/api/v1/email_templates/321"
]
},
"delete_recommendations": {
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"description": "URLs of the linked delete recommendations",
"example": [
"https://example.rossum.app/api/v1/delete_recommendations/123",
"https://example.rossum.app/api/v1/delete_recommendations/321"
]
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"upload": {
"type": "object",
"title": "Upload object",
"x-tags": [
"Upload"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true,
"description": "ID of the upload.",
"example": 314528
},
"url": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "Upload object URL.",
"example": "https://example.rossum.app/api/v1/uploads/314528"
},
"queue": {
"allOf": [
{
"$ref": "#/components/schemas/queue_url"
}
]
},
"creator": {
"type": [
"string",
"null"
],
"format": "url",
"readOnly": true,
"description": "URL of the user who created the upload.",
"example": "https://example.rossum.app/api/v1/users/1"
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Time of the creation of the upload.",
"example": "2021-04-26T10:08:03.856648Z"
},
"email": {
"type": [
"string",
"null"
],
"format": "url",
"readOnly": true,
"description": "URL of the email that created the upload object (if applicable).",
"example": "https://example.rossum.app/api/v1/emails/96743"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"documents": {
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"readOnly": true,
"description": "URLs of the uploaded documents.",
"example": [
"https://example.rossum.app/api/v1/documents/254322",
"https://example.rossum.app/api/v1/documents/254323"
]
},
"additional_documents": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"format": "url"
},
"readOnly": true,
"description": "URLs of additional documents created in upload.created event hooks.",
"example": [
"https://example.rossum.app/api/v1/documents/254324"
]
},
"annotations": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"format": "url"
},
"readOnly": true,
"description": "URLs of all created annotations.",
"example": [
"https://example.rossum.app/api/v1/annotations/104322",
"https://example.rossum.app/api/v1/annotations/104323",
"https://example.rossum.app/api/v1/annotations/104324"
]
}
}
},
"user": {
"type": "object",
"title": "User object",
"x-tags": [
"User"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the user",
"example": 10775
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the user",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"first_name": {
"type": "string",
"description": "First name of the user",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last name of the user",
"example": "Doe"
},
"email": {
"type": "string",
"format": "email",
"readOnly": true,
"description": "Email of the user",
"example": "john-doe@east-west-trading.com"
},
"phone_number": {
"type": [
"string",
"null"
],
"description": "Phone number of the user",
"example": "+1-212-456-7890"
},
"password": {
"type": "string",
"writeOnly": true,
"description": "Password (not shown on API)"
},
"date_joined": {
"type": "string",
"format": "date-time",
"description": "Date of user join",
"example": "2018-09-19T13:44:56.000000Z"
},
"username": {
"type": "string",
"description": "Username of a user",
"example": "john-doe@east-west-trading.com"
},
"groups": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"default": [],
"description": "List of [user role](/api/user-role) (permission groups)",
"example": [
"https://example.rossum.app/api/v1/groups/3"
]
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
]
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"default": [],
"description": "List of queues user is assigned to",
"example": [
"https://example.rossum.app/api/v1/queues/8199"
]
},
"is_active": {
"type": "boolean",
"default": true,
"description": "Whether user is enabled or disabled",
"example": true
},
"last_login": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Date of last login",
"example": "2019-02-07T16:20:18.652253Z"
},
"ui_settings": {
"type": "object",
"default": {},
"description": "User-related frontend UI settings (e.g. locales). Rossum internal.",
"example": {}
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"oidc_id": {
"type": [
"string",
"null"
],
"default": null,
"description": "OIDC provider id used to match Rossum user (displayed only to admin user)",
"example": null
},
"auth_type": {
"type": "string",
"default": "password",
"enum": [
"sso",
"password"
],
"description": "Authorization method, can be `sso` or `password`. This field can be edited only by admin.",
"example": "password"
},
"deleted": {
"type": "boolean",
"readOnly": true,
"default": false,
"description": "Whether a user is deleted",
"example": false
}
}
},
"password_change": {
"type": "object",
"properties": {
"new_password1": {
"type": "string",
"description": "New password",
"minLength": 12,
"maxLength": 64
},
"new_password2": {
"type": "string",
"description": "New password confirmation (must match new_password1)",
"minLength": 12,
"maxLength": 64
},
"old_password": {
"type": "string",
"description": "Current password"
}
},
"required": [
"new_password1",
"new_password2",
"old_password"
]
},
"password_reset": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email of the user to reset password for"
}
},
"required": [
"email"
]
},
"password_score": {
"type": "object",
"properties": {
"password": {
"type": "string",
"description": "Password to be scored",
"example": "MySecureP@ssw0rd"
},
"email": {
"type": "string",
"format": "email",
"description": "Email of the user",
"example": "joe.doe@example.com"
},
"first_name": {
"type": "string",
"description": "First name of the user",
"example": "Joe"
},
"last_name": {
"type": "string",
"description": "Last name of the user",
"example": "Doe"
}
},
"required": [
"password"
]
},
"password_score_response": {
"type": "object",
"properties": {
"score": {
"type": "integer",
"minimum": 0,
"maximum": 4,
"description": "Password strength score from 0 (risky password) to 4 (strong password)",
"example": 2
},
"messages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggestions from the validators",
"example": [
"Add another word or two. Uncommon words are better."
]
}
}
},
"user_role": {
"type": "object",
"title": "User Role object",
"x-tags": [
"User Role"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the user role (may differ between different organizations)",
"example": 3
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the user role",
"example": "https://example.rossum.app/api/v1/groups/3"
},
"name": {
"type": "string",
"readOnly": true,
"description": "Name of the user role",
"example": "admin"
}
}
},
"workflow": {
"type": "object",
"title": "Workflow object",
"x-tags": [
"Workflow"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the workflow",
"example": 7540
},
"name": {
"type": "string",
"description": "Name of the workflow",
"example": "Approval workflow for US entity"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workflow",
"example": "https://example.rossum.app/api/v1/workflows/7540"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
]
},
"condition": {
"type": "object",
"description": "Condition that designates whether the workflow will be entered",
"example": {}
}
}
},
"workflow_activity": {
"type": "object",
"title": "Workflow Activity object",
"x-tags": [
"Workflow Activity"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the workflow activity",
"example": 7540
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workflow activity",
"example": "https://example.rossum.app/api/v1/workflow_activities/7540"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"annotation": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the related annotation",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"workflow": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the related workflow",
"example": "https://example.rossum.app/api/v1/workflows/7540"
},
"workflow_step": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the related workflow step",
"example": "https://example.rossum.app/api/v1/workflow_steps/7540"
},
"workflow_run": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the related workflow run",
"example": "https://example.rossum.app/api/v1/workflow_runs/7512"
},
"assignees": {
"$ref": "#/components/schemas/assignees",
"description": "List of all assigned users"
},
"action": {
"type": "string",
"readOnly": true,
"description": "Supported values are: step_started, step_completed, approved, rejected, workflow_started, workflow_completed, reassigned",
"enum": [
"step_started",
"step_completed",
"approved",
"rejected",
"workflow_started",
"workflow_completed",
"reassigned"
],
"example": "step_started"
},
"note": {
"type": "string",
"readOnly": true,
"description": "String note of the activity",
"example": "The workflow step started"
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Date and time of when the activity was created",
"example": "2021-04-26T10:08:03.856648Z"
},
"created_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User who created the activity",
"example": null
}
}
},
"workflow_run": {
"type": "object",
"title": "Workflow Run object",
"x-tags": [
"Workflow Run"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the workflow run",
"example": 75402
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workflow run",
"example": "https://example.rossum.app/api/v1/workflow_runs/7512"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
},
{
"readOnly": true
}
]
},
"annotation": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the annotation",
"example": "https://example.rossum.app/api/v1/annotations/314159"
},
"current_step": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workflow step",
"example": "https://example.rossum.app/api/v1/workflow_steps/7540"
},
"workflow_status": {
"type": "string",
"readOnly": true,
"description": "Status of the workflow run",
"enum": [
"pending",
"approved",
"rejected"
],
"default": "pending",
"example": "pending"
}
}
},
"reset_request": {
"type": "object",
"properties": {
"note_content": {
"type": "string",
"description": "String note for the reset action",
"default": "",
"example": "Resetting due to invalid due date."
}
}
},
"reset_response": {
"type": "object",
"properties": {
"annotation_status": {
"type": "string",
"description": "New status of the annotation (to_review)",
"example": "to_review"
},
"workflow_status": {
"type": "string",
"description": "New workflow status (in_review)",
"example": "in_review"
}
}
},
"workflow_step": {
"type": "object",
"title": "Workflow Step object",
"x-tags": [
"Workflow Step"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the workflow step",
"example": 7540
},
"name": {
"type": "string",
"description": "Name of the workflow step",
"example": "Team Lead approval step"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workflow step",
"example": "https://example.rossum.app/api/v1/workflow_steps/7540"
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
]
},
"workflow": {
"type": "string",
"format": "uri",
"description": "URL of the workflow",
"example": "https://example.rossum.app/api/v1/workflows/7540"
},
"condition": {
"type": "object",
"description": "Condition that designates whether the workflow step will be entered",
"example": {}
},
"type": {
"type": "string",
"description": "Type of the workflow step (currently the only supported value is `approval`)",
"default": "approval",
"enum": [
"approval"
],
"example": "approval"
},
"mode": {
"type": "string",
"description": "Supported values:\n- `any` - approval of one assignee is enough\n- `all` - all assignees must approve\n- `auto` - automatically approved if the condition matches\n",
"enum": [
"any",
"all",
"auto"
],
"example": "all"
},
"ordering": {
"type": "integer",
"description": "Designates the evaluation order of steps within a workflow (must be unique per a workflow)",
"example": 1
}
}
},
"workspace": {
"type": "object",
"title": "Workspace object",
"x-tags": [
"Workspace"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "ID of the workspace",
"example": 7540
},
"name": {
"type": "string",
"description": "Name of the workspace",
"example": "East West Trading Co"
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "URL of the workspace",
"example": "https://example.rossum.app/api/v1/workspaces/7540"
},
"autopilot": {
"type": "boolean",
"readOnly": true,
"deprecated": true,
"description": "Whether to automatically confirm datapoints from previously seen annotations.\n\n_Note: Please note that autopilot configuration has been moved to Queue. Option autopilot remains\nread-only on Workspace and represents autopilot configuration set to queues within a workspace._\n",
"example": true
},
"organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization_url"
}
]
},
"queues": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"readOnly": true,
"description": "List of queues that belongs to the workspace",
"example": [
"https://example.rossum.app/api/v1/queues/8199",
"https://example.rossum.app/api/v1/queues/8236"
]
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"created_by": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "URL of the workspace creator. Might be `null` for workspaces created before April 2026.",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"readOnly": true,
"description": "Date of workspace creation. Might be `null` for workspaces created before April 2026.",
"example": "2021-04-26T10:08:03.856648Z"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
}
}
},
"note": {
"type": "object",
"title": "Note object",
"x-displayName": "🔒 Note",
"x-tags": [
"Note"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Note object ID.",
"example": 1
},
"url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Note object URL.",
"example": "https://example.rossum.app/api/v1/notes/1"
},
"type": {
"type": "string",
"description": "Note type. Possible values: `rejection`.",
"enum": [
"rejection"
],
"example": "rejection"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"content": {
"type": "string",
"maxLength": 4096,
"description": "Note's string content.",
"example": "Arbitrary note text"
},
"created_at": {
"$ref": "#/components/schemas/created_at"
},
"creator": {
"$ref": "#/components/schemas/creator"
},
"modified_by": {
"$ref": "#/components/schemas/modified_by"
},
"modified_at": {
"$ref": "#/components/schemas/modified_at"
},
"modifier": {
"type": [
"string",
"null"
],
"format": "uri",
"readOnly": true,
"description": "User that last modified the note.",
"example": "https://example.rossum.app/api/v1/users/10775"
},
"annotation": {
"type": "string",
"format": "uri",
"description": "Annotation the note belongs to.",
"example": "https://example.rossum.app/api/v1/annotations/314159"
}
}
}
},
"responses": {
"400_user_error": {
"description": "Invalid input data.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Bad Request."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "bad_request"
}
}
}
}
}
},
"401_unauthorized": {
"description": "The username/password is invalid or token is invalid (e.g. expired).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Invalid token."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "authentication_failed"
}
}
}
}
}
},
"403_forbidden": {
"description": "Insufficient permission, missing authentication, invalid CSRF token and similar issue.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Access to the requested resource is forbidden."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "access_forbidden"
}
}
}
}
}
},
"404_not_found": {
"description": "The specified resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Not found."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "not_found"
}
}
}
}
}
},
"409_conflict": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Conflict."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "conflict_status"
}
}
}
}
}
},
"429_too_many_requests": {
"description": "Request rate is too high, wait before sending more requests. See [Rate Limiting](#tag/Overview/Rate-Limiting) for more details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Request was rate limited."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "rate_limited"
},
"url": {
"type": "string",
"readOnly": true,
"description": "Link to the rate limiting documentation",
"example": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
}
}
}
}
},
"500_server_error": {
"description": "Server failure while processing the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Server error."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "error"
}
}
}
}
}
},
"502_bad_gateway": {
"description": "Invalid response from the upstream server.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Bad Gateway."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "bad_gateway"
}
}
}
}
}
},
"503_service_unavailable": {
"description": "We're temporarily offline for maintenance. Please try again later.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Service Unavailable."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "service_unavailable"
}
}
}
}
}
},
"504_gateway_timeout": {
"description": "Upstream server could not complete the request in time.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Gateway timeout."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "gateway_timeout"
}
}
}
}
}
},
"413_payload_too_large": {
"description": "Payload too large (especially for files uploaded).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Payload Too Large."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "payload_too_large"
}
}
}
}
}
},
"304_not_modified": {
"description": "Object was not modified (e.g. ETag matches `If-None-Match` header).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Object was not modified"
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "not_modified"
}
}
}
}
}
},
"412_precondition_failed": {
"description": "Precondition failed (e.g. ETag does not match).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"readOnly": true,
"description": "Detail of the error",
"example": "Precondition failed."
},
"code": {
"type": "string",
"readOnly": true,
"description": "Code of the error",
"example": "precondition_failed"
}
}
}
}
}
}
}
},
"x-tagGroups": [
{
"name": "📜 Overview",
"tags": [
"Getting Started",
"Overview",
"Import and Export",
"Queue Schema",
"Annotation Lifecycle",
"Usage report",
"Extensions",
"Rossum Transaction Scripts",
"Automation",
"Using Triggers",
"Workflow Guide",
"Embedded Mode",
"SSO",
"FAQ"
]
},
{
"name": "🔌 API Reference",
"tags": [
"Annotation",
"Annotation Content",
"Annotation Processing Duration",
"Audit Log",
"Automation Blocker",
"Connector",
"Dedicated Engine",
"Dedicated Engine Schema",
"Delete Recommendation",
"Document",
"Document Relation",
"Documents Download",
"Email",
"Email Template",
"Email Thread",
"Engine Field",
"Engines",
"Generic Engine",
"Generic Engine Schema",
"Hook",
"Hook Interface",
"Hook Run",
"Hook Template",
"Inbox",
"Label",
"Membership",
"Organization",
"Organization Group",
"Page",
"Question",
"Queue",
"Relation",
"Rule",
"Rules Execution Log",
"Schema",
"Suggested Edit",
"Survey Template",
"Survey",
"Task",
"Trigger",
"Upload",
"User",
"User Role",
"Workflow",
"Workflow Activity",
"Workflow Run",
"Workflow Step",
"Workspace"
]
}
]
}