Overview

HTTP and REST

The Rossum API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

HTTP Verbs

Call the API using the following standard HTTP methods:

• GET to retrieve an object or multiple objects in a specific category
• POST to create an object
• PUT to modify entire object
• PATCH to modify fields of the object
• DELETE to delete an object

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by API responses, including errors (except when another format is requested, e.g. XML).

Base URL

Base API endpoint URL depends on the account type, deployment and location. Default URL is https://example.rossum.app/api where the example is the domain selected during the account creation. URLs of companies using a dedicated deployment may look like https://acme.rossum.app/api.

If you are not sure about the correct URL you can navigate to https://app.rossum.ai and use your email address to receive your account information via email.

Please note that we previously recommended using the https://api.elis.rossum.ai endpoint to interact with the Rossum API, but now it is deprecated. For new integrations use the new https://example.rossum.app/api endpoint. For accounts created before Nov 2022 use the https://elis.rossum.ai/api.

Authentication

Most of the API endpoints require a user to be authenticated. To login to the Rossum API, post an object with username and password fields. Login returns an access key to be used for token authentication.

Our API also provide possibility to authenticate via One-Time token which is returned after registration. This tokens allows users to authenticate against our API, but after one call, this token will be invalidated. This token can be exchanged for regular access token limited only by the time of validity. For the purpose of token exchange, use the /auth/token endpoint.

Users may delete a token using the logout endpoint or automatically after a configured time (the default expiration time is 162 hours). The default expiration time can be lowered using max_token_lifetime_s field. When the token expires, 401 status is returned. Users are expected to re-login to obtain a new token.

Rossum's API also supports session authentication, where a user session is created inside cookies after login. If enabled, the session lasts 1 day until expired by itself or until logout While the session is valid there is no need to send the authentication token in every request, but the "unsafe" request (POST, PUT, PATCH, DELETE), whose MIME type is different from application/json must include X-CSRFToken header with valid CSRF token, which is returned inside Cookie while logging in. When a session expires, 401 status is returned as with token authentication, and users are expected to re-login to start a new session.

Login

POST /v1/auth/login

Example login request:

curl -H 'Content-Type: application/json' \
  -d '{"username": "east-west-trading-co@example.rossum.app", "password": "aCo2ohghBo8Oghai"}' \
  'https://example.rossum.app/api/v1/auth/login'

Example login response:

{
  "key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03",
  "domain": "acme-corp.app.rossum.ai"
}

Using the token with Bearer authentication:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/organizations/406'

Alternative token authentication format:

curl -H 'Authorization: Token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/organizations/406'

Login request with custom token lifetime:

curl -H 'Content-Type: application/json' \
  -d '{"username": "east-west-trading-co@example.rossum.app", "password": "aCo2ohghBo8Oghai", "max_token_lifetime_s": 3600}' \
  'https://example.rossum.app/api/v1/auth/login'

Response with custom token lifetime:

{
  "key": "ltcg2p2w7o9vxju313f04rq7lcc4xu2bwso423b3",
  "domain": null
}

Response

Status: 200

Returns object with "key", which is an access token. And the user's domain.

Logout

POST /v1/auth/logout

Logout user, discard auth token. Example request:

curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/auth/logout'

Example response:

{
  "detail": "Successfully logged out."
}

Response

Status: 200

Token Exchange

POST /v1/auth/token

Example token exchange request:

curl -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/auth/token'

Example token exchange response:

{
  "key": "ltcg2p2w7o9vxju313f04rq7lcc4xu2bwso423b3",
  "domain": "example.rossum.app",
  "scope": "default"
}

This endpoint enables the exchange of a one-time token for a longer lived access token.

It is able to receive either one-time tokens provided after registration, or JWT tokens if you have such a setup configured. The token must be provided in a the Bearer authorization header.

JWT authentication

Short-lived JWT tokens can be exchanged for access tokens. A typical use case, for example, is logging in your users via SSO in your own application, and displaying the Rossum app to them embedded.

To enable JWT authentication, one needs to provide Rossum with the public key that shall be used to decode the tokens. Currently only tokens with EdDSA (signed using Ed25519 and Ed448 curves) and RS512 signatures are allowed, and token validity should be 60 seconds maximum.

The expected formats of the header and encoded payload of the JWT token are as follows:

Decoded JWT Header Format

Example JWT header:

{
   "alg":"EdDSA",
   "kid":"urn:rossum.ai:organizations:100",
   "typ":"JWT"
}

Decoded JWT Payload Format

Example JWT payload:

{
   "ver":"1.0",
   "iss":"ACME Corporation",
   "aud":"https://example.rossum.app",
   "sub":"john.doe@rossum.ai",
   "exp":1514764800,
   "email":"john.doe@rossum.ai",
   "name":"John F. Doe",
   "rossum_org":"100",
   "roles": ["annotator"]
}

Response

Status: 200

Single Sign-On (SSO)

Rossum allows customers to integrate with their own identity provider, such as Google, Azure AD or any other provider using OAuth2 OpenID Connect protocol (OIDC). Rossum then acts as a service provider.

When SSO is enabled for an organization, user is redirected to a configured identity provider login page and only allowed to access Rossum application when successfully authenticated. Identity provider user claim (e.g. email (default), sub, preferred_username, unique_name) is used to match a user account in Rossum. If auto-provisioning is enabled for the organization, user accounts in Rossum will be automatically created for users without accounts.

Required setup of the OIDC identity provider:

• Redirect URI (also known as Reply URL): https://example.rossum.app/api/v1/oauth/code

Required information to allow OIDC setup for the Rossum service provider:

• OIDC endpoint, such as https://accounts.google.com. It should support openid configuration, e.g. https://accounts.google.com/.well-known/openid-configuration
• client id
• client secret
• claim that should be matched in Rossum
• Rossum organization id

If you need to setup SSO for your organization, please contact support@rossum.ai.

Pagination

All object list operations are paged by default, so you may need several API calls to obtain all objects of given type.

Cursor-Based Pagination

List endpoints use cursor-based pagination, which provides better performance and consistency for large datasets. The pagination response includes next and previous URLs that contain an opaque signed cursor query parameter.

Important: Do not attempt to construct or modify cursor values manually. Always use the complete URLs provided in the next and previous fields to navigate through pages.

Example pagination response:

{
  "pagination": {
    "next": "https://example.rossum.app/api/v1/annotations?cursor=eyJpZCI6MTIzNDU2fQ",
    "previous": null
  },
  "results": [...]
}

To fetch the next page, simply make a GET request to the URL provided in the next field. The cursor is automatically included and managed by the API.

Parameters

^(*) Maximum page size differs for some endpoints:

• 1,000 for exporting data in CSV format via POST on /annotations
• 500 for searching in annotations via annotations/search (if sideload=content is not included)

Rate Limiting

To maintain platform stability and ensure fair usage, the Rossum API implements rate limiting. If you exceed the allowable request threshold, the API will respond with a 429 Too Many Requests status code and a Retry-After header.

Handling Rate Limits

We recommend designing your application to respect the limits and handle 429 status codes gracefully. If a request is rate-limited, your application should:

1. Respect the Header: Pause requests for the duration specified in the Retry-After header.
2. Retry Strategy: Implement an exponential backoff strategy for subsequent retries to prevent overwhelming the server.

Current Rate Limits

Our Acceptable Use Schedule is detailed in the Rossum Terms of Use. The current default rate limits for the Rossum API are listed below:

Filters and ordering

Example of filtering and ordering queues:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/queues?workspace=7540&locale=en_US&ordering=name&pages=1,2'

Lists may be filtered using various attributes.

Multiple attributes are combined with & in the URL, which results in more specific response. Please refer to the particular object description.

Multiple values within the same attribute can be used, resulting in OR condition. Use comma to separate values.

Ordering of results may be enforced by the ordering parameter and one or more keys delimited by a comma. Preceding key with a minus sign - enforces descending order.

Metadata

Example document object with metadata:

{
  "id": 319768,
  "url": "https://example.rossum.app/api/v1/documents/319768",
  "s3_name": "05feca6b90d13e389c31c8fdeb7fea26",
  "annotations": [
    "https://example.rossum.app/api/v1/annotations/319668"
  ],
  "mime_type": "application/pdf",
  "arrived_at": "2019-02-11T19:22:33.993427Z",
  "original_file_name": "document.pdf",
  "content": "https://example.rossum.app/api/v1/documents/319768/content",
  "metadata": {
    "customer-id": "f205ec8a-5597-4dbb-8d66-5a53ea96cdea",
    "source": 9581,
    "authors": ["Joe Smith", "Peter Doe"]
  }
}

When working with API objects, it may be useful to attach some information to the object (e.g. customer ID to a document). You can store custom JSON object in a metadata section available in most objects.

List of objects with metadata support: organization, workspace, user, queue, schema, connector, inbox, document, annotation, page, survey.

Total metadata size may be up to 4 kB per object.

Versioning

API Version is part of the URL, e.g. https://example.rossum.app/api/v1/users.

To allow API progress, we consider addition of a field in a JSON object as well as addition of a new item in an enum object to be backward-compatible operations that may be introduced at any time. Clients are expected to deal with such changes.

Internal

Endpoints and other information not described in this documentation are considered internal and should not be used or relied upon (they can change without backward compatibility).

Beta

Some endpoints and attributes in our API are marked with a Beta label. This indicates that the functionality is currently in beta and may be subject to changes in the future. While we encourage you to try out these features, please be aware that:

• The API contract may change in backward-incompatible ways
• Features might be modified or removed in future releases

We welcome your feedback on these beta features to help us improve them before they reach general availability.

Dates

All dates fields are represented as ISO 8601 formatted strings, e.g. 2018-06-01T21:36:42.223415Z. All returned dates are in UTC timezone.

Errors

Our API uses conventional HTTP response codes to indicate the success or failure of an API request.