OpenAPI SpecificationJSON
API Reference

Task

Tasks are used as status monitors of asynchronous operations.

Tasks 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.

Task Types

Currently supported task types:

  • documents_download - Used for monitoring document download operations.
  • upload_created - Used for monitoring upload creation operations.
  • email_imported - Used for monitoring email import operations.

Task Content

The content field contains detailed information related to tasks, which varies by task type:

Documents Download Task Content

  • file_name (string) - File name of the archive to be downloaded specified when creating a download.

Documents Upload Task Content

  • upload (url) - URL of the object representing the upload.

Task

Attribute
Type
Description
id*
read-only
integer

Task object ID.

url*
read-only
URL

Task object URL.

type*
"documents_download" | "upload_created" | "email_imported"
status*
"running" | "succeeded" | "failed"
expires_at*
datetime

Timestamp of a guaranteed availability of the task object. Expired tasks are being deleted periodically.

detail*
string | null

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.

content*
object

Detailed information related to tasks. Content structure varies by task type:

  • For documents_download: contains file_name (string) - File name of the archive to be downloaded.
  • For upload_created: contains upload (url) - URL of the object representing the upload.
code*
string | null

Error code.

result_url*
URL

Succeeded status resulting redirect URL.

Retrieve task

GET api / v1 / tasks / {taskID}

Get a task object.

Response Behavior:

  • If the task has status running or failed, the endpoint returns status 200 with the task object.
  • 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).
  • If the task has status succeeded and no_redirect=true is passed, the endpoint returns the task object with status 200.
GET
/api/v1/tasks/{taskID}
curl -X GET "https://example.rossum.app/api/v1/tasks/0"

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

Empty
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK - Returns the task object. This response is returned when:

  • Task status is running or failed
  • Task status is succeeded and no_redirect=true parameter was passed
Attribute
Type
Description
id*
read-only
integer

Task object ID.

url*
read-only
URL

Task object URL.

type*
"documents_download" | "upload_created" | "email_imported"
status*
"running" | "succeeded" | "failed"
expires_at*
datetime

Timestamp of a guaranteed availability of the task object. Expired tasks are being deleted periodically.

detail*
string | null

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.

content*
object

Detailed information related to tasks. Content structure varies by task type:

  • For documents_download: contains file_name (string) - File name of the archive to be downloaded.
  • For upload_created: contains upload (url) - URL of the object representing the upload.
code*
string | null

Error code.

result_url*
URL

Succeeded status resulting redirect URL.

303

See Other - Redirects to the newly created object when task status is succeeded and no_redirect parameter is not set. The URL of the created object is provided in the Location header and matches the result_url field from the task object.

No response body.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

PATCHPartial update suggested edit

Previous Page

GETRetrieve task

Next Page