API Clients

The Rossum API SDK provides both synchronous and asynchronous clients for interacting with the Rossum API. Both clients offer identical functionality, so choose the one that best fits your application architecture.

Overview

The external clients are the primary interfaces for interacting with Rossum API. They handle authentication, pagination, error handling, and provide convenient methods for all API operations.

When to use async vs sync:

  • Use AsyncRossumAPIClient when:

    • Your application is already async-based

    • You need to make concurrent API calls

    • You want optimal performance for I/O-bound operations

  • Use SyncRossumAPIClient when:

    • You’re working in a traditional synchronous application

    • You’re scripting or prototyping

Asynchronous Client

class rossum_api.clients.external_async_client.AsyncRossumAPIClient(base_url, credentials, *, deserializer=None, timeout=None, n_retries=3, retry_backoff_factor=1.0, retry_max_jitter=1.0, max_in_flight_requests=4, response_post_processor=None)[source]

Asynchronous Rossum API Client.

Parameters:

  • base_url (str) – Base API URL including the “/api” and version (“/v1”) in the url path. For example “https://elis.rossum.ai/api/v1”.

  • credentials (UserCredentials | Token) – User credentials or API token used for authentication.

  • deserializer (Callable[[Resource, dict[str, Any]], TypeVar(RossumApiType)] | None) – Pass a custom deserialization callable if different model classes should be returned.

  • timeout (float | None) – The timeout configuration (in seconds) to use when sending requests.

  • n_retries (int) – Number of request retries before raising an exception.

  • retry_backoff_factor (float) – Backoff factor for exponential backoff between retries (multiplies the delay).

  • retry_max_jitter (float) – Maximum random jitter (in seconds) added to retry delays.

  • max_in_flight_requests (int) – Maximum number of concurrent requests allowed.

  • response_post_processor (Callable[[Response], Any] | None) – pass a custom response post-processing callable. Applied only if http_client is not provided.

async retrieve_queue(queue_id)[source]

Retrieve a single Queue object.

Parameters:

queue_id (int) – ID of a queue to be retrieved.

Return type:

QueueType

References

https://elis.rossum.ai/api/docs/#retrieve-a-queue-2.

https://elis.rossum.ai/api/docs/#queue.

async list_queues(ordering=(), **filters)[source]

Retrieve all Queue objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'workspace', 'connector', 'webhooks', 'schema', 'inbox', 'locale']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Queue.

    name: Name of a Queue.

    workspace: ID of a Workspace.

    inbox: ID of an Inbox.

    connector: ID of an Connector.

    webhooks: IDs of a Hook.

    hooks: IDs of a Hook.

    locale: Queue object locale.

    dedicated_engine: ID of a dedicated engine.

    generic_engine: ID of a generic engine.

    deleting: Boolean filter - queue is being deleted (delete_after is set)

Return type:

AsyncIterator[QueueType]

References

https://elis.rossum.ai/api/docs/#list-all-queues.

https://elis.rossum.ai/api/docs/#queue.

async create_new_queue(data)[source]

Create a new Queue object.

Parameters:

data (dict[str, Any]) – Queue object configuration.

Return type:

QueueType

References

https://elis.rossum.ai/api/docs/#create-new-queue.

https://elis.rossum.ai/api/docs/#queue.

async delete_queue(queue_id)[source]

Delete Queue object.

Parameters:

queue_id (int) – ID of a queue to be deleted.

Notes

By default, the deletion will start after 24 hours.

Warning

It also deletes all the related objects. Please note that while the queue and related objects are being deleted the API may return inconsistent results. We strongly discourage from any interaction with the queue after being scheduled for deletion.

References

https://elis.rossum.ai/api/docs/#delete-a-queue.

https://elis.rossum.ai/api/docs/#queue.

async import_document(queue_id, files, values=None, metadata=None)[source]

https://elis.rossum.ai/api/docs/#import-a-document.

Deprecated now, consider upload_document.

Parameters:

  • queue_id (int) – ID of the queue to upload the files to

  • files (Sequence[tuple[str | Path, str]]) – 2-tuple containing current filepath and name to be used by Elis for the uploaded file

  • metadata (dict[str, Any] | None) – metadata will be set to newly created annotation object

  • values (dict[str, Any] | None) – may be used to initialize datapoint values by setting the value of rir_field_names in the schema

Returns:

list of IDs of created annotations, respects the order of files argument

Return type:

annotation_ids

async upload_document(queue_id, files, values=None, metadata=None)[source]

https://elis.rossum.ai/api/docs/#create-upload.

Parameters:

  • queue_id (int) – ID of the queue to upload the files to

  • files (Sequence[tuple[str | Path, str]]) – 2-tuple containing current filepath and name to be used by Elis for the uploaded file

  • metadata (dict[str, Any] | None) – metadata will be set to newly created annotation object

  • values (dict[str, Any] | None) – may be used to initialize datapoint values by setting the value of rir_field_names in the schema

Returns:

list of Task object responses, respects the order of files argument Tasks can be polled using poll_task and if succeeded, will contain a link to an Upload object that contains info on uploaded documents/annotations

Return type:

task_responses

async retrieve_upload(upload_id)[source]

Retrieve rossum_api.models.upload.Upload object.

Parameters:

upload_id (int) – ID of an upload to be retrieved.

Return type:

UploadType

References

https://elis.rossum.ai/api/docs/#retrieve-upload.

https://elis.rossum.ai/api/docs/#upload.

async export_annotations_to_json(queue_id, **filters)[source]

Export annotations from the queue to JSON.

Notes

JSON export is paginated and returns the result in a way similar to other list_all methods.

Parameters:

  • queue_id (int) – ID of a queue annotions should be exported from.

  • filters (Any) –

    id

    Id of annotation to be exported, multiple ids may be separated by a comma.

    status

    Annotation status.

    modifier

    User id.

    arrived_at_before

    ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15).

    arrived_at_after

    ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14).

    exported_at_after

    ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00).

    export_failed_at_before

    ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00).

    export_failed_at_after

    ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00).

    page_size

    Number of the documents to be exported. To be used together with page attribute. See pagination.

    page

    Number of a page to be exported when using pagination. Useful for exports of large amounts of data. To be used together with the page_size attribute.

Return type:

AsyncIterator[AnnotationType]

Notes

When the search filter is used, results are limited to 10 000. We suggest narrowing down the search query if there are this many results.

References

https://elis.rossum.ai/api/docs/#export-annotations

async export_annotations_to_file(queue_id, export_format, **filters)[source]

Export annotations from the queue to a desired export format.

Notes

JSON export is paginated and returns the result in a way similar to other list_all methods.

Parameters:

  • queue_id (int) – ID of a queue annotions should be exported from.

  • export_format (ExportFileFormats) – Target export format.

  • filters (Any) –

    id

    Id of annotation to be exported, multiple ids may be separated by a comma.

    status

    Annotation status.

    modifier

    User id.

    arrived_at_before

    ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15).

    arrived_at_after

    ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14).

    exported_at_after

    ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00).

    export_failed_at_before

    ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00).

    export_failed_at_after

    ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00).

    page_size

    Number of the documents to be exported. To be used together with page attribute. See pagination.

    page

    Number of a page to be exported when using pagination. Useful for exports of large amounts of data. To be used together with the page_size attribute.

Return type:

AsyncIterator[bytes]

Notes

When the search filter is used, results are limited to 10 000. We suggest narrowing down the search query if there are this many results.

References

https://elis.rossum.ai/api/docs/#export-annotations

async list_organizations(ordering=(), **filters)[source]

Retrieve all organization objects satisfying the specified filters.

Parameters:
Return type:

AsyncIterator[OrganizationType]

References

https://elis.rossum.ai/api/docs/#list-all-organizations.

async retrieve_organization(org_id)[source]

Retrieve a single Qrganization object.

Parameters:

org_id (int) – ID of an organization to be retrieved.

Return type:

OrganizationType

References

https://elis.rossum.ai/api/docs/#retrieve-an-organization.

async retrieve_own_organization()[source]

Retrieve organization of currently logged in user.

Return type:

OrganizationType

async list_schemas(ordering=(), **filters)[source]

Retrieve all Schema objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Schema

    name: Name of a Schema

    queue: ID of a Queue

Return type:

AsyncIterator[SchemaType]

References

https://elis.rossum.ai/api/docs/#list-all-schemas.

https://elis.rossum.ai/api/docs/#schema.

async retrieve_schema(schema_id)[source]

Retrieve a single Schema object.

Parameters:

schema_id (int) – ID of a schema to be retrieved.

Return type:

SchemaType

References

https://elis.rossum.ai/api/docs/#retrieve-a-schema.

https://elis.rossum.ai/api/docs/#schema.

async create_new_schema(data)[source]

Create a new Schema object.

Parameters:

data (dict[str, Any]) – Schema object configuration.

Return type:

SchemaType

References

https://elis.rossum.ai/api/docs/#create-a-new-schema.

https://elis.rossum.ai/api/docs/#schema.

async delete_schema(schema_id)[source]

Delete Schema object.

Parameters:

schema_id (int) – ID of a schema to be deleted.

Warning

In case the schema is linked to some objects, like queue or annotation, the deletion is not possible and the request will fail with 409 status code.

References

https://elis.rossum.ai/api/docs/#delete-a-schema.

async list_users(ordering=(), **filters)[source]

Retrieve all User objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'username', 'first_name', 'last_name', 'email', 'last_login', 'date_joined', 'deleted', 'not_deleted']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a User

    organization: ID of an Organization

    username: Username of a User

    first_name: First name of a User

    last_name: Last name of a User

    email: Email address of a User

    is_active: Boolean filter - whether the User is active

    last_login: ISO 8601 timestamp filter for last login date

    groups: IDs of Group objects

    queue: ID of a Queue

    deleted: Boolean filter - whether the User is deleted

Return type:

AsyncIterator[UserType]

References

https://elis.rossum.ai/api/docs/#list-all-users.

https://elis.rossum.ai/api/docs/#user.

async retrieve_user(user_id)[source]

Retrieve a single User object.

Parameters:

user_id (int) – ID of a user to be retrieved.

Return type:

UserType

References

https://elis.rossum.ai/api/docs/#retrieve-a-user-2.

https://elis.rossum.ai/api/docs/#user.

async create_new_user(data)[source]

Create a new User object.

Parameters:

data (dict[str, Any]) – User object configuration.

Return type:

UserType

References

https://elis.rossum.ai/api/docs/#create-new-user.

https://elis.rossum.ai/api/docs/#user.

async list_annotations(ordering=(), sideloads=(), content_schema_ids=(), **filters)[source]

Retrieve all Annotation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['document', 'document__arrived_at', 'document__original_file_name', 'modifier', 'modifier__username', 'modified_by', 'modified_by__username', 'creator', 'creator__username', 'queue', 'status', 'created_at', 'assigned_at', 'confirmed_at', 'modified_at', 'exported_at', 'export_failed_at', 'purged_at', 'rejected_at', 'deleted_at', 'confirmed_by', 'deleted_by', 'exported_by', 'purged_by', 'rejected_by', 'confirmed_by__username', 'deleted_by__username', 'exported_by__username', 'purged_by__username', 'rejected_by__username']]) – List of object names. Their URLs are used for sorting the results

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

  • content_schema_ids (Sequence[str]) – List of content schema IDs

  • filters (Any) –

    status: Annotation status, multiple values may be separated using a comma

    id: List of ids separated by a comma

    modifier: User id

    confirmed_by: User id

    deleted_by: User id

    exported_by: User id

    purged_by: User id

    rejected_by: User id

    assignees: User id, multiple values may be separated using a comma

    labels: Label id, multiple values may be separated using a comma

    document: Document id

    queue: List of Queue ids separated by a comma

    queue__workspace: List of Workspace ids separated by a comma

    relations__parent: ID of parent annotation defined in related Relation object

    relations__type: Type of Relation that annotation belongs to

    relations__key: Key of Relation that annotation belongs to

    arrived_at_before: ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15)

    arrived_at_after: ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14)

    assigned_at_before: ISO 8601 timestamp (e.g. assigned_at_before=2019-11-15)

    assigned_at_after: ISO 8601 timestamp (e.g. assigned_at_after=2019-11-14)

    confirmed_at_before: ISO 8601 timestamp (e.g. confirmed_at_before=2019-11-15)

    confirmed_at_after: ISO 8601 timestamp (e.g. confirmed_at_after=2019-11-14)

    modified_at_before: ISO 8601 timestamp (e.g. modified_at_before=2019-11-15)

    modified_at_after: ISO 8601 timestamp (e.g. modified_at_after=2019-11-14)

    deleted_at_before: ISO 8601 timestamp (e.g. deleted_at_before=2019-11-15)

    deleted_at_after: ISO 8601 timestamp (e.g. deleted_at_after=2019-11-14)

    exported_at_before: ISO 8601 timestamp (e.g. exported_at_before=2019-11-14 22:00:00)

    exported_at_after: ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00)

    export_failed_at_before: ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00)

    export_failed_at_after: ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00)

    purged_at_before: ISO 8601 timestamp (e.g. purged_at_before=2019-11-15)

    purged_at_after: ISO 8601 timestamp (e.g. purged_at_after=2019-11-14)

    rejected_at_before: ISO 8601 timestamp (e.g. rejected_at_before=2019-11-15)

    rejected_at_after: ISO 8601 timestamp (e.g. rejected_at_after=2019-11-14)

    restricted_access: Boolean

    automated: Boolean

    has_email_thread_with_replies: Boolean (related email thread contains more than one incoming emails)

    has_email_thread_with_new_replies: Boolean (related email thread contains unread incoming email)

    search: String, see Annotation search

Return type:

AsyncIterator[AnnotationType]

References

https://elis.rossum.ai/api/docs/#list-all-annotations.

https://elis.rossum.ai/api/docs/#annotation.

async search_for_annotations(query=None, query_string=None, ordering=(), sideloads=(), **kwargs)[source]

Search for Annotation objects.

Parameters:

  • query (dict | None) – Query dictionary for advanced search

  • query_string (dict | None) – Query string dictionary for text search

  • ordering (Sequence[Literal['document', 'document__arrived_at', 'document__original_file_name', 'modifier', 'modifier__username', 'modified_by', 'modified_by__username', 'creator', 'creator__username', 'queue', 'status', 'created_at', 'assigned_at', 'confirmed_at', 'modified_at', 'exported_at', 'export_failed_at', 'purged_at', 'rejected_at', 'deleted_at', 'confirmed_by', 'deleted_by', 'exported_by', 'purged_by', 'rejected_by', 'confirmed_by__username', 'deleted_by__username', 'exported_by__username', 'purged_by__username', 'rejected_by__username']]) – List of object names. Their URLs are used for sorting the results

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

  • kwargs (Any) – Additional search parameters

Return type:

AsyncIterator[AnnotationType]

References

https://elis.rossum.ai/api/docs/#search-for-annotations.

https://elis.rossum.ai/api/docs/#annotation.

async retrieve_annotation(annotation_id, sideloads=())[source]

Retrieve a single Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be retrieved.

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#retrieve-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async poll_annotation(annotation_id, predicate, sleep_s=3, sideloads=())[source]

Poll on Annotation until predicate is true.

Sideloading is done only once after the predicate becomes true to avoid spamming the server.

Return type:

AnnotationType

async poll_annotation_until_imported(annotation_id, **poll_kwargs)[source]

Wait until annotation is imported.

Return type:

AnnotationType

async poll_task(task_id, predicate, sleep_s=3)[source]

Poll on Task until predicate is true.

As with Annotation polling, there is no innate retry limit.

Return type:

TaskType

async poll_task_until_succeeded(task_id, sleep_s=3)[source]

Poll on Task until it is succeeded.

Return type:

TaskType

async retrieve_task(task_id)[source]

Retrieve a single Task object.

Parameters:

task_id (int) – ID of a task to be retrieved.

Return type:

TaskType

References

https://elis.rossum.ai/api/docs/#retrieve-task.

https://elis.rossum.ai/api/docs/#task.

async upload_and_wait_until_imported(queue_id, filepath, filename, **poll_kwargs)[source]

Upload a single file and waiting until its annotation is imported in a single call.

Return type:

AnnotationType

async start_annotation(annotation_id)[source]

Start annotation processing.

Parameters:

annotation_id (int) – ID of an annotation to be started.

References

https://elis.rossum.ai/api/docs/#start-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async update_annotation(annotation_id, data)[source]

Update an Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • data (dict[str, Any]) – Annotation object update data.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#update-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async update_part_annotation(annotation_id, data)[source]

Update part of an Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • data (dict[str, Any]) – Partial Annotation object update data.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#update-part-of-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async bulk_update_annotation_data(annotation_id, operations)[source]

Bulk update annotation data.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • operations (list[dict[str, Any]]) – List of operations to perform on annotation data.

References

https://elis.rossum.ai/api/docs/#bulk-update-annotation-data.

https://elis.rossum.ai/api/docs/#annotation.

async confirm_annotation(annotation_id)[source]

Confirm annotation.

Parameters:

annotation_id (int) – ID of an annotation to be confirmed.

References

https://elis.rossum.ai/api/docs/#confirm-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async create_new_annotation(data)[source]

Create a new Annotation object.

Parameters:

data (dict[str, Any]) – Annotation object configuration.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#create-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async delete_annotation(annotation_id)[source]

Delete Annotation object.

Parameters:

annotation_id (int) – ID of an annotation to be deleted.

References

https://elis.rossum.ai/api/docs/#switch-to-deleted.

https://elis.rossum.ai/api/docs/#annotation.

async cancel_annotation(annotation_id)[source]

Cancel Annotation object.

Parameters:

annotation_id (int) – ID of an annotation to be cancelled.

References

https://elis.rossum.ai/api/docs/#cancel-annotation.

https://elis.rossum.ai/api/docs/#annotation.

async retrieve_document(document_id)[source]

Retrieve a single Document object.

Parameters:

document_id (int) – ID of a document to be retrieved.

Return type:

DocumentType

References

https://elis.rossum.ai/api/docs/#retrieve-a-document.

https://elis.rossum.ai/api/docs/#document.

async retrieve_document_content(document_id)[source]

Retrieve DocumentDocuntent object.

Parameters:

document_id (int) – ID of a document to retrieve content for.

Returns:

Raw document content.

Return type:

bytes

References

https://elis.rossum.ai/api/docs/#document-content.

https://elis.rossum.ai/api/docs/#document.

async create_new_document(file_name, file_data, metadata=None, parent=None)[source]

Create a new Document object.

Parameters:

  • file_name (str) – Name of the file to be created.

  • file_data (bytes) – Raw file data.

  • metadata (dict[str, Any] | None) – Optional metadata for the document.

  • parent (str | None) – Optional parent document URL.

Return type:

DocumentType

References

https://elis.rossum.ai/api/docs/#create-document.

https://elis.rossum.ai/api/docs/#document.

async list_document_relations(ordering=(), **filters)[source]

Retrieve all DocumentRelation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'type', 'annotation']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of DocumentRelation.

    type: Relation type.

    annotation: ID of Annotation.

    key: Document relation key

    documents: ID of related Document.

Return type:

AsyncIterator[DocumentRelationType]

References

https://elis.rossum.ai/api/docs/#list-all-document-relations.

https://elis.rossum.ai/api/docs/#document-relation.

async retrieve_document_relation(document_relation_id)[source]

Retrieve a single DocumentRelation object.

Parameters:

document_relation_id (int) – ID of a document relation to be retrieved.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#retrieve-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

async create_new_document_relation(data)[source]

Create a new DocumentRelation object.

Parameters:

data (dict[str, Any]) – DocumentRelation object configuration.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#create-a-new-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

async update_document_relation(document_relation_id, data)[source]

Update a DocumentRelation object.

Parameters:
Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#update-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

async update_part_document_relation(document_relation_id, data)[source]

Update part of a DocumentRelation object.

Parameters:

  • document_relation_id (int) – ID of a document relation to be updated.

  • data (dict[str, Any]) – DocumentRelation object partial configuration.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#update-part-of-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

async delete_document_relation(document_relation_id)[source]

Delete a DocumentRelation object.

Parameters:

document_relation_id (int) – ID of a document relation to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

async list_relations(ordering=(), **filters)[source]

Retrieve all Relation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['type', 'parent', 'key']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of the Relation.

    type: Relation type, see RelationType.

    parent: ID of parent Annotation.

    key: Relation key.

    annotation: ID of related Annotation.

Return type:

AsyncIterator[RelationType]

References

https://elis.rossum.ai/api/docs/#list-all-relations.

https://elis.rossum.ai/api/docs/#relation.

async create_new_relation(data)[source]

Create a new Relation object.

Parameters:

data (dict[str, Any]) – Relation object configuration.

Return type:

RelationType

References

https://elis.rossum.ai/api/docs/#create-a-new-relation.

https://elis.rossum.ai/api/docs/#relation.

async list_workspaces(ordering=(), **filters)[source]

Retrieve all Workspace objects satisfying the specified filters.

Parameters:
Return type:

AsyncIterator[WorkspaceType]

References

https://elis.rossum.ai/api/docs/#list-all-workspaces.

https://elis.rossum.ai/api/docs/#workspace.

async retrieve_workspace(workspace_id)[source]

Retrieve a single Workspace object.

Parameters:

workspace_id (int) – ID of a workspace to be retrieved.

Return type:

WorkspaceType

References

https://elis.rossum.ai/api/docs/#retrieve-a-workspace.

https://elis.rossum.ai/api/docs/#workspace.

async create_new_workspace(data)[source]

Create a new Workspace object.

Parameters:

data (dict[str, Any]) – Workspace object configuration.

Return type:

WorkspaceType

References

https://elis.rossum.ai/api/docs/#create-a-new-workspace.

https://elis.rossum.ai/api/docs/#workspace.

async delete_workspace(workspace_id)[source]

Delete rossum_api.models.workspace.Workspace object.

Parameters:

workspace_id (int) – ID of a workspace to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-workspace.

https://elis.rossum.ai/api/docs/#workspace.

async create_new_inbox(data)[source]

https://elis.rossum.ai/api/docs/#create-a-new-inbox.

Return type:

InboxType

async retrieve_email(email_id)[source]

Retrieve a single rossum_api.models.email.Email object.

Parameters:

email_id (int) – ID of email to be retrieved

Return type:

EmailType

References

https://elis.rossum.ai/api/docs/#retrieve-an-email.

https://elis.rossum.ai/api/docs/#email.

async import_email(raw_message, recipient, mime_type=None)[source]

Import an email as raw data.

Calling this endpoint starts an asynchronous process of creating an email object and importing its contents to the specified recipient inbox in Rossum.

Parameters:

  • raw_message (bytes) – Raw email data.

  • recipient (str) – Email address of the inbox where the email will be imported.

  • mime_type (str | None) – Mime type of imported files

Return type:

str

References

https://elis.rossum.ai/api/docs/#import-email.

https://elis.rossum.ai/api/docs/#email.

async list_email_templates(ordering=(), **filters)[source]

Retrieve all EmailTemplate objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of an EmailTemplate

    queue: ID of a Queue

    type: Type of the email template

    name: Name of the EmailTemplate

Return type:

AsyncIterator[EmailTemplateType]

References

https://elis.rossum.ai/api/docs/#list-all-email-templates.

https://elis.rossum.ai/api/docs/#email-template.

async retrieve_email_template(email_template_id)[source]

Retrieve a single EmailTemplate object.

Parameters:

email_template_id (int) – ID of an email template to be retrieved.

Return type:

EmailTemplateType

References

https://elis.rossum.ai/api/docs/#retrieve-an-email-template-object.

https://elis.rossum.ai/api/docs/#email-template.

async create_new_email_template(data)[source]

Create a new EmailTemplate object.

Parameters:

data (dict[str, Any]) – EmailTemplate object configuration.

Return type:

EmailTemplateType

References

https://elis.rossum.ai/api/docs/#create-new-email-template-object.

https://elis.rossum.ai/api/docs/#email-template.

async list_connectors(ordering=(), **filters)[source]

Retrieve all Connector objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'service_url']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Connector

    name: Name of the Connector

    service_url: Service URL of the Connector

Return type:

AsyncIterator[ConnectorType]

References

https://elis.rossum.ai/api/docs/#list-all-connectors.

https://elis.rossum.ai/api/docs/#connector.

async retrieve_connector(connector_id)[source]

Retrieve a single Connector object.

Parameters:

connector_id (int) – ID of a connector to be retrieved.

Return type:

ConnectorType

References

https://elis.rossum.ai/api/docs/#retrieve-a-connector.

https://elis.rossum.ai/api/docs/#connector.

async create_new_connector(data)[source]

Create a new Connector object.

Parameters:

data (dict[str, Any]) – Connector object configuration.

Return type:

ConnectorType

References

https://elis.rossum.ai/api/docs/#create-a-new-connector.

https://elis.rossum.ai/api/docs/#connector.

async list_hooks(ordering=(), **filters)[source]

Retrieve all Hook objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'type', 'active', 'config_url', 'config_app_url', 'events']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Hook

    name: Name of a Hook

    type: Hook type. Possible values: webhook, function

    queue: ID of a Queue

    active: If set to true the hook is notified.

    config_url:

    config_app_url:

    extension_source: Import source of the extension. For more, see Extension sources.

Return type:

AsyncIterator[HookType]

References

https://elis.rossum.ai/api/docs/#list-all-hooks.

https://elis.rossum.ai/api/docs/#hook.

async retrieve_hook(hook_id)[source]

Retrieve a single Hook object.

Parameters:

hook_id (int) – ID of a hook to be retrieved.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#retrieve-a-hook.

https://elis.rossum.ai/api/docs/#hook.

async create_new_hook(data)[source]

Create a new Hook object.

Parameters:

data (dict[str, Any]) – Hook object configuration.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#create-a-new-hook.

https://elis.rossum.ai/api/docs/#hook.

async update_part_hook(hook_id, data)[source]

Update part of a Hook object.

Parameters:

  • hook_id (int) – ID of a hook to be updated.

  • data (dict[str, Any]) – Hook object partial configuration.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#update-part-of-a-hook.

https://elis.rossum.ai/api/docs/#hook.

async delete_hook(hook_id)[source]

Delete a Hook object.

Parameters:

hook_id (int) – ID of a hook to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-hook.

https://elis.rossum.ai/api/docs/#hook.

async list_rules(ordering=(), **filters)[source]

Retrieve all Rule objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'organization']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Rule.

    name: Name of a Rule.

    schema: ID of a Schema.

    rule_template: URL of the rule template the rule was created from.

    organization: ID of a Organization.

Return type:

AsyncIterator[RuleType]

References

https://elis.rossum.ai/api/docs/#list-all-rules.

https://elis.rossum.ai/api/docs/#rule.

async retrieve_rule(rule_id)[source]

Retrieve a single Rule object.

Parameters:

rule_id (int) – ID of a rule to be retrieved.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#retrieve-rule.

https://elis.rossum.ai/api/docs/#rule.

async create_new_rule(data)[source]

Create a new Rule object.

Parameters:

data (dict[str, Any]) – Rule object configuration.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#create-a-new-rule.

https://elis.rossum.ai/api/docs/#rule.

async update_part_rule(rule_id, data)[source]

Update part of a Rule object.

Parameters:

  • rule_id (int) – ID of a rule to be updated.

  • data (dict[str, Any]) – Rule object partial configuration.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#update-a-rule.

https://elis.rossum.ai/api/docs/#rule.

async delete_rule(rule_id)[source]

Delete a Rule object.

Parameters:

rule_id (int) – ID of a rule to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-rule.

https://elis.rossum.ai/api/docs/#rule.

async list_user_roles(ordering=(), **filters)[source]

Retrieve all Group objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['name']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) – name: Name of Group

Return type:

AsyncIterator[GroupType]

References

https://elis.rossum.ai/api/docs/#list-all-user-roles.

https://elis.rossum.ai/api/docs/#user-role.

async request_paginated(url, *args, **kwargs)[source]

Request to endpoints with paginated response that do not have direct support in the client.

Return type:

AsyncIterator[dict]

async request_json(method, *args, **kwargs)[source]

Request to endpoints that do not have direct support in the client and return plain JSON.

Return type:

dict[str, Any]

async request(method, *args, **kwargs)[source]

Request to endpoints that do not have direct support in the client and return plain response.

Return type:

Response

async get_token(refresh=False)[source]

Return the current token. Authentication is done automatically if needed.

Parameters:

refresh (bool) – force refreshing the token

Return type:

str

async authenticate()[source]

Synchronous Client

class rossum_api.clients.external_sync_client.SyncRossumAPIClient(base_url, credentials, *, deserializer=None, timeout=None, n_retries=3, response_post_processor=None)[source]

Synchronous Rossum API Client.

Parameters:

  • base_url (str) – base API URL including the “/api” and version (“/v1”) in the url path. For example “https://elis.rossum.ai/api/v1”

  • deserializer (Callable[[Resource, dict[str, Any]], TypeVar(RossumApiType)] | None) – pass a custom deserialization callable if different model classes should be returned

  • response_post_processor (Callable[[Response], Any] | None) – pass a custom response post-processing callable

retrieve_queue(queue_id)[source]

Retrieve a single Queue object.

Parameters:

queue_id (int) – ID of a queue to be retrieved.

Return type:

QueueType

References

https://elis.rossum.ai/api/docs/#retrieve-a-queue-2.

https://elis.rossum.ai/api/docs/#queue.

list_queues(ordering=(), **filters)[source]

Retrieve all queue objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'workspace', 'connector', 'webhooks', 'schema', 'inbox', 'locale']]) – List of object names. Their IDs are used for sorting the results

  • filters (Any) –

    id: ID of a Queue

    name: Name of a Queue

    workspace: ID of a Workspace

    inbox: ID of an Inbox

    connector: ID of an Connector

    webhooks: IDs of a Hooks

    hooks: IDs of a Hooks

    locale: Queue object locale.

    dedicated_engine: ID of a dedicated engine.

    generic_engine: ID of a generic engine.

    deleting: Boolean filter - queue is being deleted (delete_after is set)

Return type:

Iterator[QueueType]

References

https://elis.rossum.ai/api/docs/#list-all-queues.

create_new_queue(data)[source]

Create a new Queue object.

Parameters:

data (dict[str, Any]) – Queue object configuration.

Return type:

QueueType

References

https://elis.rossum.ai/api/docs/#create-new-queue.

https://elis.rossum.ai/api/docs/#queue.

delete_queue(queue_id)[source]

Delete Queue object.

Parameters:

deleted. (ID of a queue to be)

Notes

By default, the deletion will start after 24 hours.

Warning

It also deletes all the related objects. Please note that while the queue and related objects are being deleted the API may return inconsistent results. We strongly discourage from any interaction with the queue after being scheduled for deletion.

References

https://elis.rossum.ai/api/docs/#delete-a-queue.

import_document(queue_id, files, values=None, metadata=None)[source]

https://elis.rossum.ai/api/docs/#import-a-document.

Deprecated now, consider upload_document.

Parameters:

  • queue_id (int) – ID of the queue to upload the files to

  • files (Sequence[tuple[str | Path, str]]) – 2-tuple containing current filepath and name to be used by Elis for the uploaded file

  • values (dict[str, Any] | None) – may be used to initialize datapoint values by setting the value of rir_field_names in the schema

  • metadata (dict[str, Any] | None) – will be set to newly created annotation object

Returns:

list of IDs of created annotations, respects the order of files argument

Return type:

annotation_ids

upload_document(queue_id, files, values=None, metadata=None)[source]

Do the same thing as import_document method, but uses a different endpoint.

Parameters:

  • queue_id (int) – ID of the queue to upload the files to

  • files (Sequence[tuple[str | Path, str]]) – 2-tuple containing current filepath and name to be used by Elis for the uploaded file

  • values (dict[str, Any] | None) – may be used to initialize datapoint values by setting the value of rir_field_names in the schema

  • metadata (dict[str, Any] | None) – will be set to newly created annotation object

Returns:

list of Task object responses, respects the order of files argument Tasks can be polled using poll_task and if succeeded, will contain a link to an Upload object that contains info on uploaded documents/annotations

Return type:

task_responses

References

https://elis.rossum.ai/api/docs/#create-upload

retrieve_upload(upload_id)[source]

Retrieve rossum_api.models.upload.Upload object.

Parameters:

upload_id (int) – ID of an upload to be retrieved.

Return type:

UploadType

References

https://elis.rossum.ai/api/docs/#retrieve-upload.

export_annotations_to_json(queue_id, **filters)[source]

Export annotations from the queue to JSON.

Notes

JSON export is paginated and returns the result in a way similar to other list_all methods.

Parameters:

  • queue_id (int) – ID of a queue annotions should be exported from.

  • filters (Any) –

    id

    Id of annotation to be exported, multiple ids may be separated by a comma.

    status

    Annotation status.

    modifier

    User id.

    arrived_at_before

    ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15).

    arrived_at_after

    ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14).

    exported_at_after

    ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00).

    export_failed_at_before

    ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00).

    export_failed_at_after

    ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00).

    page_size

    Number of the documents to be exported. To be used together with page attribute. See pagination.

    page

    Number of a page to be exported when using pagination. Useful for exports of large amounts of data. To be used together with the page_size attribute.

Return type:

Iterator[AnnotationType]

Notes

When the search filter is used, results are limited to 10 000. We suggest narrowing down the search query if there are this many results.

References

https://elis.rossum.ai/api/docs/#export-annotations

export_annotations_to_file(queue_id, export_format, **filters)[source]

Export annotations from the queue to a desired export format.

Notes

JSON export is paginated and returns the result in a way similar to other list_all methods.

Parameters:

  • queue_id (int) – ID of a queue annotions should be exported from.

  • export_format (ExportFileFormats) – Target export format.

  • filters (Any) –

    id

    Id of annotation to be exported, multiple ids may be separated by a comma.

    status

    Annotation status.

    modifier

    User id.

    arrived_at_before

    ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15).

    arrived_at_after

    ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14).

    exported_at_after

    ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00).

    export_failed_at_before

    ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00).

    export_failed_at_after

    ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00).

    page_size

    Number of the documents to be exported. To be used together with page attribute. See pagination.

    page

    Number of a page to be exported when using pagination. Useful for exports of large amounts of data. To be used together with the page_size attribute.

Return type:

Iterator[bytes]

Notes

When the search filter is used, results are limited to 10 000. We suggest narrowing down the search query if there are this many results.

References

https://elis.rossum.ai/api/docs/#export-annotations

list_organizations(ordering=(), **filters)[source]

Retrieve all organization objects satisfying the specified filters.

Parameters:
Return type:

Iterator[OrganizationType]

References

https://elis.rossum.ai/api/docs/#list-all-organizations.

retrieve_organization(org_id)[source]

Retrieve a single Qrganization object.

Parameters:

org_id (int) – ID of an organization to be retrieved.

Return type:

OrganizationType

References

https://elis.rossum.ai/api/docs/#retrieve-an-organization.

retrieve_own_organization()[source]

Retrieve organization of currently logged in user.

Return type:

OrganizationType

retrieve_my_organization()[source]

Retrieve organization of currently logged in user.

Return type:

OrganizationType

list_schemas(ordering=(), **filters)[source]

Retrieve all Schema objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Schema

    name: Name of a Schema

    queue: ID of a Queue

Return type:

Iterator[SchemaType]

References

https://elis.rossum.ai/api/docs/#list-all-schemas.

https://elis.rossum.ai/api/docs/#schema.

retrieve_schema(schema_id)[source]

Retrieve a single Schema object.

Parameters:

schema_id (int) – ID of a schema to be retrieved.

Return type:

SchemaType

References

https://elis.rossum.ai/api/docs/#retrieve-a-schema.

https://elis.rossum.ai/api/docs/#schema.

create_new_schema(data)[source]

Create a new Schema object.

Parameters:

data (dict[str, Any]) – Schema object configuration.

Return type:

SchemaType

References

https://elis.rossum.ai/api/docs/#create-a-new-schema.

https://elis.rossum.ai/api/docs/#schema.

delete_schema(schema_id)[source]

Delete Schema object.

Parameters:

schema_id (int) – ID of a schema to be deleted.

Notes

Warning

In case the schema is linked to some objects, like queue or annotation, the deletion is not possible and the request will fail with 409 status code.

References

https://elis.rossum.ai/api/docs/#delete-a-schema.

https://elis.rossum.ai/api/docs/#schema.

list_users(ordering=(), **filters)[source]

Retrieve all User objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'username', 'first_name', 'last_name', 'email', 'last_login', 'date_joined', 'deleted', 'not_deleted']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a User

    username: Username of a User

    first_name: First name of a User

    last_name: Last name of a User

    email: Email address of a User

    is_active: Boolean filter - whether the User is active

    last_login: ISO 8601 timestamp filter for last login date

    groups: IDs of Group objects

    queue: ID of a Queue

    deleted: Boolean filter - whether the User is deleted

Return type:

Iterator[UserType]

References

https://elis.rossum.ai/api/docs/#list-all-users.

https://elis.rossum.ai/api/docs/#user.

retrieve_user(user_id)[source]

Retrieve a single User object.

Parameters:

user_id (int) – ID of a user to be retrieved.

Return type:

UserType

References

https://elis.rossum.ai/api/docs/#retrieve-a-user-2.

https://elis.rossum.ai/api/docs/#user.

create_new_user(data)[source]

https://elis.rossum.ai/api/docs/#create-new-user.

Return type:

UserType

retrieve_annotation(annotation_id, sideloads=())[source]

Retrieve a single Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be retrieved.

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#retrieve-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

list_annotations(ordering=(), sideloads=(), content_schema_ids=(), **filters)[source]

Retrieve all Annotation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['document', 'document__arrived_at', 'document__original_file_name', 'modifier', 'modifier__username', 'modified_by', 'modified_by__username', 'creator', 'creator__username', 'queue', 'status', 'created_at', 'assigned_at', 'confirmed_at', 'modified_at', 'exported_at', 'export_failed_at', 'purged_at', 'rejected_at', 'deleted_at', 'confirmed_by', 'deleted_by', 'exported_by', 'purged_by', 'rejected_by', 'confirmed_by__username', 'deleted_by__username', 'exported_by__username', 'purged_by__username', 'rejected_by__username']]) – List of object names. Their URLs are used for sorting the results

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

  • content_schema_ids (Sequence[str]) – List of content schema IDs

  • filters (Any) –

    status: Annotation status, multiple values may be separated using a comma

    id: List of ids separated by a comma

    modifier: User id

    confirmed_by: User id

    deleted_by: User id

    exported_by: User id

    purged_by: User id

    rejected_by: User id

    assignees: User id, multiple values may be separated using a comma

    labels: Label id, multiple values may be separated using a comma

    document: Document id

    queue: List of Queue ids separated by a comma

    queue__workspace: List of Workspace ids separated by a comma

    relations__parent: ID of parent annotation defined in related Relation object

    relations__type: Type of Relation that annotation belongs to

    relations__key: Key of Relation that annotation belongs to

    arrived_at_before: ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15)

    arrived_at_after: ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14)

    assigned_at_before: ISO 8601 timestamp (e.g. assigned_at_before=2019-11-15)

    assigned_at_after: ISO 8601 timestamp (e.g. assigned_at_after=2019-11-14)

    confirmed_at_before: ISO 8601 timestamp (e.g. confirmed_at_before=2019-11-15)

    confirmed_at_after: ISO 8601 timestamp (e.g. confirmed_at_after=2019-11-14)

    modified_at_before: ISO 8601 timestamp (e.g. modified_at_before=2019-11-15)

    modified_at_after: ISO 8601 timestamp (e.g. modified_at_after=2019-11-14)

    deleted_at_before: ISO 8601 timestamp (e.g. deleted_at_before=2019-11-15)

    deleted_at_after: ISO 8601 timestamp (e.g. deleted_at_after=2019-11-14)

    exported_at_before: ISO 8601 timestamp (e.g. exported_at_before=2019-11-14 22:00:00)

    exported_at_after: ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00)

    export_failed_at_before: ISO 8601 timestamp (e.g. export_failed_at_before=2019-11-14 22:00:00)

    export_failed_at_after: ISO 8601 timestamp (e.g. export_failed_at_after=2019-11-14 12:00:00)

    purged_at_before: ISO 8601 timestamp (e.g. purged_at_before=2019-11-15)

    purged_at_after: ISO 8601 timestamp (e.g. purged_at_after=2019-11-14)

    rejected_at_before: ISO 8601 timestamp (e.g. rejected_at_before=2019-11-15)

    rejected_at_after: ISO 8601 timestamp (e.g. rejected_at_after=2019-11-14)

    restricted_access: Boolean

    automated: Boolean

    has_email_thread_with_replies: Boolean (related email thread contains more than one incoming emails)

    has_email_thread_with_new_replies: Boolean (related email thread contains unread incoming email)

    search: String, see Annotation search

Return type:

Iterator[AnnotationType]

References

https://elis.rossum.ai/api/docs/#list-all-annotations.

https://elis.rossum.ai/api/docs/#annotation.

search_for_annotations(query=None, query_string=None, ordering=(), sideloads=(), **kwargs)[source]

Search for Annotation objects.

Parameters:

  • query (dict | None) – Query dictionary for advanced search

  • query_string (dict | None) – Query string dictionary for text search

  • ordering (Sequence[Literal['document', 'document__arrived_at', 'document__original_file_name', 'modifier', 'modifier__username', 'modified_by', 'modified_by__username', 'creator', 'creator__username', 'queue', 'status', 'created_at', 'assigned_at', 'confirmed_at', 'modified_at', 'exported_at', 'export_failed_at', 'purged_at', 'rejected_at', 'deleted_at', 'confirmed_by', 'deleted_by', 'exported_by', 'purged_by', 'rejected_by', 'confirmed_by__username', 'deleted_by__username', 'exported_by__username', 'purged_by__username', 'rejected_by__username']]) – List of object names. Their URLs are used for sorting the results

  • sideloads (Sequence[Literal['content', 'automation_blockers', 'documents', 'modifiers', 'queues']]) – List of additional objects to sideload

  • kwargs (Any) – Additional search parameters

Return type:

Iterator[AnnotationType]

References

https://elis.rossum.ai/api/docs/#search-for-annotations.

https://elis.rossum.ai/api/docs/#annotation.

poll_annotation(annotation_id, predicate, sleep_s=3, sideloads=())[source]

Poll on Annotation until predicate is true.

Sideloading is done only once after the predicate becomes true to avoid spamming the server.

Return type:

AnnotationType

poll_annotation_until_imported(annotation_id, **poll_kwargs)[source]

Wait until annotation is imported.

Parameters:

  • annotation_id (int) – ID of an annotation to poll.

  • poll_kwargs (Any) – Additional keyword arguments passed to poll_annotation.

Return type:

AnnotationType

retrieve_task(task_id)[source]

https://elis.rossum.ai/api/docs/#retrieve-task.

Return type:

TaskType

poll_task(task_id, predicate, sleep_s=3)[source]

Poll on Task until predicate is true.

As with Annotation polling, there is no innate retry limit.

Return type:

TaskType

poll_task_until_succeeded(task_id, sleep_s=3)[source]

Poll on Task until it is succeeded.

Return type:

TaskType

upload_and_wait_until_imported(queue_id, filepath, filename, **poll_kwargs)[source]

Upload a single file and waiting until its annotation is imported in a single call.

Return type:

AnnotationType

start_annotation(annotation_id)[source]

Start annotation processing.

Parameters:

annotation_id (int) – ID of an annotation to be started.

References

https://elis.rossum.ai/api/docs/#start-annotation.

https://elis.rossum.ai/api/docs/#annotation.

update_annotation(annotation_id, data)[source]

Update an Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • data (dict[str, Any]) – Annotation object update data.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#update-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

update_part_annotation(annotation_id, data)[source]

Update part of an Annotation object.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • data (dict[str, Any]) – Partial Annotation object update data.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#update-part-of-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

bulk_update_annotation_data(annotation_id, operations)[source]

Bulk update annotation data.

Parameters:

  • annotation_id (int) – ID of an annotation to be updated.

  • operations (list[dict[str, Any]]) – List of operations to perform on annotation data.

References

https://elis.rossum.ai/api/docs/#bulk-update-annotation-data.

https://elis.rossum.ai/api/docs/#annotation.

confirm_annotation(annotation_id)[source]

Confirm annotation.

Parameters:

annotation_id (int) – ID of an annotation to be confirmed.

References

https://elis.rossum.ai/api/docs/#confirm-annotation.

https://elis.rossum.ai/api/docs/#annotation.

create_new_annotation(data)[source]

Create a new Annotation object.

Parameters:

data (dict[str, Any]) – Annotation object configuration.

Return type:

AnnotationType

References

https://elis.rossum.ai/api/docs/#create-an-annotation.

https://elis.rossum.ai/api/docs/#annotation.

delete_annotation(annotation_id)[source]

Delete Annotation object.

Parameters:

annotation_id (int) – ID of an annotation to be deleted.

References

https://elis.rossum.ai/api/docs/#switch-to-deleted.

https://elis.rossum.ai/api/docs/#annotation.

cancel_annotation(annotation_id)[source]

Cancel Annotation object.

Parameters:

annotation_id (int) – ID of an annotation to be cancelled.

References

https://elis.rossum.ai/api/docs/#cancel-annotation.

https://elis.rossum.ai/api/docs/#annotation.

retrieve_document(document_id)[source]

Retrieve a single Document object.

Parameters:

document_id (int) – ID of a document to be retrieved.

Return type:

DocumentType

References

https://elis.rossum.ai/api/docs/#retrieve-a-document.

https://elis.rossum.ai/api/docs/#document.

retrieve_document_content(document_id)[source]

Get the binary content of a document.

Parameters:

document_id (int) – ID of a document to retrieve content for.

Return type:

bytes

References

https://elis.rossum.ai/api/docs/#document-content.

https://elis.rossum.ai/api/docs/#document.

create_new_document(file_name, file_data, metadata=None, parent=None)[source]

Create a new Document object.

Parameters:

  • file_name (str) – Name of the file to be created.

  • file_data (bytes) – Binary content of the file.

  • metadata (dict[str, Any] | None) – Optional metadata to attach to the document.

  • parent (str | None) – Optional parent document URL.

Return type:

DocumentType

References

https://elis.rossum.ai/api/docs/#create-document.

https://elis.rossum.ai/api/docs/#document.

list_document_relations(ordering=(), **filters)[source]

Retrieve all DocumentRelation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'type', 'annotation']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of DocumentRelation.

    type: Relation type.

    annotation: ID of Annotation.

    key: Document relation key

    documents: ID of related Document.

Return type:

Iterator[DocumentRelationType]

References

https://elis.rossum.ai/api/docs/#list-all-document-relations.

https://elis.rossum.ai/api/docs/#document-relation.

retrieve_document_relation(document_relation_id)[source]

Retrieve a single DocumentRelation object.

Parameters:

document_relation_id (int) – ID of a document relation to be retrieved.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#retrieve-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

create_new_document_relation(data)[source]

Create a new DocumentRelation object.

Parameters:

data (dict[str, Any]) – DocumentRelation object configuration.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#create-a-new-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

update_document_relation(document_relation_id, data)[source]

Update a DocumentRelation object.

Parameters:
Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#update-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

update_part_document_relation(document_relation_id, data)[source]

Update part of a DocumentRelation object.

Parameters:

  • document_relation_id (int) – ID of a document relation to be updated.

  • data (dict[str, Any]) – DocumentRelation object partial configuration.

Return type:

DocumentRelationType

References

https://elis.rossum.ai/api/docs/#update-part-of-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

delete_document_relation(document_relation_id)[source]

Delete a DocumentRelation object.

Parameters:

document_relation_id (int) – ID of a document relation to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-document-relation.

https://elis.rossum.ai/api/docs/#document-relation.

list_relations(ordering=(), **filters)[source]

Retrieve all Relation objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['type', 'parent', 'key']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of the Relation.

    type: Relation type, see RelationType.

    parent: ID of parent Annotation.

    key: Relation key.

    annotation: ID of related Annotation.

Return type:

Iterator[RelationType]

References

https://elis.rossum.ai/api/docs/#list-all-relations.

https://elis.rossum.ai/api/docs/#relation.

create_new_relation(data)[source]

Create a new Relation object.

Parameters:

data (dict[str, Any]) – Relation object configuration.

Return type:

RelationType

References

https://elis.rossum.ai/api/docs/#create-a-new-relation.

https://elis.rossum.ai/api/docs/#relation.

list_workspaces(ordering=(), **filters)[source]

Retrieve all Workspace objects satisfying the specified filters.

Parameters:
Return type:

Iterator[WorkspaceType]

References

https://elis.rossum.ai/api/docs/#list-all-workspaces.

https://elis.rossum.ai/api/docs/#workspace.

retrieve_workspace(workspace_id)[source]

Retrieve a single Workspace object.

Parameters:

workspace_id (int) – ID of a workspace to be retrieved.

Return type:

WorkspaceType

References

https://elis.rossum.ai/api/docs/#retrieve-a-workspace.

https://elis.rossum.ai/api/docs/#workspace.

create_new_workspace(data)[source]

Create a new Workspace object.

Parameters:

data (dict[str, Any]) – Workspace object configuration.

Return type:

WorkspaceType

References

https://elis.rossum.ai/api/docs/#create-a-new-workspace.

https://elis.rossum.ai/api/docs/#workspace.

delete_workspace(workspace_id)[source]

Delete rossum_api.models.workspace.Workspace object.

Parameters:

workspace_id (int) – ID of a workspace to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-workspace.

https://elis.rossum.ai/api/docs/#workspace.

create_new_inbox(data)[source]

Create a new Inbox object.

Parameters:

data (dict[str, Any]) – Inbox object configuration.

Return type:

InboxType

References

https://elis.rossum.ai/api/docs/#create-a-new-inbox.

https://elis.rossum.ai/api/docs/#inbox.

retrieve_email(email_id)[source]

Retrieve a single rossum_api.models.email.Email object.

Parameters:

email_id (int) – ID of email to be retrieved

Return type:

EmailType

References

https://elis.rossum.ai/api/docs/#retrieve-an-email.

https://elis.rossum.ai/api/docs/#email.

import_email(raw_message, recipient, mime_type=None)[source]

Import an email as raw data.

Calling this endpoint starts an asynchronous process of creating an email object and importing its contents to the specified recipient inbox in Rossum.

Parameters:

  • raw_message (bytes) – Raw email data.

  • recipient (str) – Email address of the inbox where the email will be imported.

  • mime_type (str | None) – Mime type of imported files

Returns:

Task URL that can be used to track the import status.

Return type:

str

References

https://elis.rossum.ai/api/docs/#import-email.

https://elis.rossum.ai/api/docs/#email.

list_email_templates(ordering=(), **filters)[source]

Retrieve all EmailTemplate objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of an EmailTemplate

    queue: ID of a Queue

    type: Type of the email template

    name: Name of the EmailTemplate

Return type:

Iterator[EmailTemplateType]

References

https://elis.rossum.ai/api/docs/#list-all-email-templates.

https://elis.rossum.ai/api/docs/#email-template.

retrieve_email_template(email_template_id)[source]

Retrieve a single EmailTemplate object.

Parameters:

email_template_id (int) – ID of an email template to be retrieved.

Return type:

EmailTemplateType

References

https://elis.rossum.ai/api/docs/#retrieve-an-email-template-object.

https://elis.rossum.ai/api/docs/#email-template.

create_new_email_template(data)[source]

Create a new EmailTemplate object.

Parameters:

data (dict[str, Any]) – EmailTemplate object configuration.

Return type:

EmailTemplateType

References

https://elis.rossum.ai/api/docs/#create-new-email-template-object.

https://elis.rossum.ai/api/docs/#email-template.

list_connectors(ordering=(), **filters)[source]

Retrieve all Connector objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'service_url']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Connector

    name: Name of the Connector

    service_url: Service URL of the Connector

Return type:

Iterator[ConnectorType]

References

https://elis.rossum.ai/api/docs/#list-all-connectors.

https://elis.rossum.ai/api/docs/#connector.

retrieve_connector(connector_id)[source]

Retrieve a single Connector object.

Parameters:

connector_id (int) – ID of a connector to be retrieved.

Return type:

ConnectorType

References

https://elis.rossum.ai/api/docs/#retrieve-a-connector.

https://elis.rossum.ai/api/docs/#connector.

create_new_connector(data)[source]

Create a new Connector object.

Parameters:

data (dict[str, Any]) – Connector object configuration.

Return type:

ConnectorType

References

https://elis.rossum.ai/api/docs/#create-a-new-connector.

https://elis.rossum.ai/api/docs/#connector.

list_hooks(ordering=(), **filters)[source]

Retrieve all Hook objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'type', 'active', 'config_url', 'config_app_url', 'events']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Hook

    name: Name of a Hook

    type: Hook type. Possible values: webhook, function

    queue: ID of a Queue

    active: If set to true the hook is notified.

    config_url:

    config_app_url:

    extension_source: Import source of the extension. For more, see Extension sources.

Return type:

Iterator[HookType]

References

https://elis.rossum.ai/api/docs/#list-all-hooks.

https://elis.rossum.ai/api/docs/#hook.

retrieve_hook(hook_id)[source]

Retrieve a single Hook object.

Parameters:

hook_id (int) – ID of a hook to be retrieved.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#retrieve-a-hook.

https://elis.rossum.ai/api/docs/#hook.

create_new_hook(data)[source]

Create a new Hook object.

Parameters:

data (dict[str, Any]) – Hook object configuration.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#create-a-new-hook.

https://elis.rossum.ai/api/docs/#hook.

update_part_hook(hook_id, data)[source]

Update part of a Hook object.

Parameters:

  • hook_id (int) – ID of a hook to be updated.

  • data (dict[str, Any]) – Hook object partial configuration.

Return type:

HookType

References

https://elis.rossum.ai/api/docs/#update-part-of-a-hook.

https://elis.rossum.ai/api/docs/#hook.

delete_hook(hook_id)[source]

Delete a Hook object.

Parameters:

hook_id (int) – ID of a hook to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-hook.

https://elis.rossum.ai/api/docs/#hook.

list_rules(ordering=(), **filters)[source]

Retrieve all Rule objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['id', 'name', 'organization']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) –

    id: ID of a Rule.

    name: Name of a Rule.

    schema: ID of a Schema.

    rule_template: URL of the rule template the rule was created from.

    organization: ID of a Organization.

Return type:

Iterator[RuleType]

References

https://elis.rossum.ai/api/docs/#list-all-rules.

https://elis.rossum.ai/api/docs/#rule.

retrieve_rule(rule_id)[source]

Retrieve a single Rule object.

Parameters:

rule_id (int) – ID of a rule to be retrieved.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#retrieve-rule.

https://elis.rossum.ai/api/docs/#rule.

create_new_rule(data)[source]

Create a new Rule object.

Parameters:

data (dict[str, Any]) – Rule object configuration.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#create-a-new-rule.

https://elis.rossum.ai/api/docs/#rule.

update_part_rule(rule_id, data)[source]

Update part of a Rule object.

Parameters:

  • rule_id (int) – ID of a rule to be updated.

  • data (dict[str, Any]) – Rule object partial configuration.

Return type:

RuleType

References

https://elis.rossum.ai/api/docs/#update-a-rule.

https://elis.rossum.ai/api/docs/#rule.

delete_rule(rule_id)[source]

Delete a Rule object.

Parameters:

rule_id (int) – ID of a rule to be deleted.

References

https://elis.rossum.ai/api/docs/#delete-a-rule.

https://elis.rossum.ai/api/docs/#rule.

list_user_roles(ordering=(), **filters)[source]

Retrieve all Group objects satisfying the specified filters.

Parameters:

  • ordering (Sequence[Literal['name']]) – List of object names. Their URLs are used for sorting the results

  • filters (Any) – name: Name of Group

Return type:

Iterator[GroupType]

References

https://elis.rossum.ai/api/docs/#list-all-user-roles.

https://elis.rossum.ai/api/docs/#user-role.

request_paginated(url, *args, **kwargs)[source]

Request to endpoints with paginated response that do not have direct support in the client.

Return type:

Iterator[dict]

request_json(method, *args, **kwargs)[source]

Request to endpoints that do not have direct support in the client and return plain JSON.

Return type:

dict[str, Any]

request(method, *args, **kwargs)[source]

Request to endpoints that do not have direct support in the client and return plain response.

Return type:

Response

authenticate()[source]

Client Usage Examples

Authentication

Both clients support authentication via username/password credentials or token-based authentication:

from rossum_api import SyncRossumAPIClient
from rossum_api.dtos import UserCredentials, Token

# Username/password authentication
credentials = UserCredentials(
    username="your.email@example.com",
    password="your-password"
)

# Token-based authentication
credentials = Token(token="your-api-token")

# Initialize the Rossum API client
client = SyncRossumAPIClient(base_url="...", credentials=credentials)

Working with Annotations

Async version:

# Retrieve a single annotation
annotation = await client.retrieve_annotation(12345)

# List annotations with filtering
async for annotation in client.list_annotations(
    status="to_review",
    ordering=["-created_at"]
):
    print(annotation.id, annotation.status)

# Search for annotations
async for annotation in client.search_for_annotations(
    query={"status": "to_review"},
    ordering=["-created_at"]
):
    print(annotation.id, annotation.status)

# Update annotation
updated = await client.update_annotation(
    annotation_id=12345,
    data={"status": "confirmed"}
)

# Poll annotation until imported
annotation = await client.poll_annotation_until_imported(12345)

# Confirm annotation
await client.confirm_annotation(12345)

Sync version:

# Retrieve a single annotation
annotation = client.retrieve_annotation(12345)

# List annotations with filtering
for annotation in client.list_annotations(
    status="to_review",
    ordering=["-created_at"]
):
    print(annotation.id, annotation.status)

# Search for annotations
for annotation in client.search_for_annotations(
    query={"status": "to_review"},
    ordering=["-created_at"]
):
    print(annotation.id, annotation.status)

# Update annotation
updated = client.update_annotation(
    annotation_id=12345,
    data={"status": "confirmed"}
)

# Poll annotation until imported
annotation = client.poll_annotation_until_imported(12345)

# Confirm annotation
client.confirm_annotation(12345)

Working with Documents

Async version:

# Upload documents (creates tasks)
tasks = await client.upload_document(
    queue_id=123,
    files=[("path/to/invoice.pdf", "invoice.pdf")]
)

# Poll task until completion
task = await client.poll_task_until_succeeded(tasks[0].id)

# Retrieve document
document = await client.retrieve_document(12345)

# Get document content
content = await client.retrieve_document_content(12345)

# Create new document
document = await client.create_new_document(
    file_name="invoice.pdf",
    file_data=content,
    metadata={"source": "email"}
)

# Upload and wait for import in one call
annotation = await client.upload_and_wait_until_imported(
    queue_id=123,
    filepath="invoice.pdf",
    filename="invoice.pdf"
)

Sync version:

# Upload documents (creates tasks)
tasks = client.upload_document(
    queue_id=123,
    files=[("path/to/invoice.pdf", "invoice.pdf")]
)

# Poll task until completion
task = client.poll_task_until_succeeded(tasks[0].id)

# Retrieve document
document = client.retrieve_document(12345)

# Get document content
content = client.retrieve_document_content(12345)

# Create new document
document = client.create_new_document(
    file_name="invoice.pdf",
    file_data=content,
    metadata={"source": "email"}
)

# Upload and wait for import in one call
annotation = client.upload_and_wait_until_imported(
    queue_id=123,
    filepath="invoice.pdf",
    filename="invoice.pdf"
)

Working with Workspaces and Queues

Async version:

# Create workspace
workspace = await client.create_new_workspace(data={
    "name": "My Workspace",
    "organization": organization_url,
})

# Retrieve workspace
workspace = await client.retrieve_workspace(123)

# List workspaces
async for workspace in client.list_workspaces():
    print(workspace.name)

# Create queue in workspace
queue = await client.create_new_queue(data={
    "name": "Invoices",
    "workspace": workspace.url,
    "schema": schema_url,
})

# Retrieve queue
queue = await client.retrieve_queue(456)

# List queues with filtering
async for queue in client.list_queues(workspace=workspace.id):
    print(queue.name)

# Delete queue
await client.delete_queue(456)

Sync version:

# Create workspace
workspace = client.create_new_workspace(data={
    "name": "My Workspace",
    "organization": organization_url,
})

# Retrieve workspace
workspace = client.retrieve_workspace(123)

# List workspaces
for workspace in client.list_workspaces():
    print(workspace.name)

# Create queue in workspace
queue = client.create_new_queue(data={
    "name": "Invoices",
    "workspace": workspace.url,
    "schema": schema_url,
})

# Retrieve queue
queue = client.retrieve_queue(456)

# List queues with filtering
for queue in client.list_queues(workspace=workspace.id):
    print(queue.name)

# Delete queue
client.delete_queue(456)

Pagination

The clients handle pagination automatically:

# All `list_*` methods automatically handle pagination
# and yield results one by one
async for user in client.list_users():
    print(user.email)

# Lists can be filtered and ordered
async for queue in client.list_queues(
    workspace=123,
    ordering=["-id"]
):
    print(queue.name)

Export Operations

Both export formats are supported:

# Export annotations to JSON (paginated)
async for annotation in client.export_annotations_to_json(
    queue_id=123,
    status="confirmed"
):
    print(annotation.id)

# Export annotations to file format (CSV, XML, XLSX)
from rossum_api.domain_logic.annotations import ExportFileFormats

async for chunk in client.export_annotations_to_file(
    queue_id=123,
    export_format=ExportFileFormats.CSV,
    status="confirmed"
):
    # Process file chunk
    pass

Working with Relations

Relations represent parent-child relationships between annotations (e.g., duplicates, attachments, edits):

Async version:

from rossum_api.models.relation import RelationType

# List all relations
async for relation in client.list_relations():
    print(relation.id, relation.type)

# Filter by type
async for relation in client.list_relations(type="duplicate"):
    print(relation.id, relation.key)

# Filter by parent annotation
async for relation in client.list_relations(parent=12345):
    print(relation.id, relation.annotations)

# Create a new relation
relation = await client.create_new_relation(data={
    "type": "attachment",
    "parent": "https://elis.rossum.ai/api/v1/annotations/123",
    "annotations": ["https://elis.rossum.ai/api/v1/annotations/456"]
})

Sync version:

from rossum_api.models.relation import RelationType

# List all relations
for relation in client.list_relations():
    print(relation.id, relation.type)

# Filter by type
for relation in client.list_relations(type="duplicate"):
    print(relation.id, relation.key)

# Filter by parent annotation
for relation in client.list_relations(parent=12345):
    print(relation.id, relation.annotations)

# Create a new relation
relation = client.create_new_relation(data={
    "type": "attachment",
    "parent": "https://elis.rossum.ai/api/v1/annotations/123",
    "annotations": ["https://elis.rossum.ai/api/v1/annotations/456"]
})

Working with Additional Resources

The clients also provide methods for managing other API resources:

# Organizations
async for org in client.list_organizations():
    print(org.name)

org = await client.retrieve_organization(123)
my_org = await client.retrieve_my_organization()

# Schemas
schema = await client.create_new_schema(data={
    "name": "Invoice Schema",
    "content": schema_definition
})

async for schema in client.list_schemas():
    print(schema.name)

# Users and Roles
user = await client.create_new_user(data={
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
})

async for role in client.list_user_roles():
    print(role.name)

# Hooks and Connectors
hook = await client.create_new_hook(data={
    "name": "My Hook",
    "target": "https://example.com/webhook"
})

connector = await client.create_new_connector(data={
    "name": "My Connector",
    "connector_type": "webhook"
})

Authentication and Token Management

# Get current authentication token
token = await client.get_token()

# Force refresh the token
token = await client.get_token(refresh=True)

# Manually authenticate (usually not needed)
await client.authenticate()

Generic Request Methods

For advanced use cases, raw request methods are available in both clients:

Async version:

# Make paginated requests to custom endpoints
async for item in client.request_paginated(
    "custom/endpoint",
    ordering=["id"]
):
    print(item)

# Make JSON requests
response = await client.request_json(
    "POST",
    "custom/endpoint",
    json={"data": "value"}
)

# Make raw HTTP requests
response = await client.request(
    "GET",
    "custom/endpoint"
)

Sync version:

# Make paginated requests to custom endpoints
for item in client.request_paginated(
    "custom/endpoint",
    ordering=["id"]
):
    print(item)

# Make JSON requests
response = client.request_json(
    "POST",
    "custom/endpoint",
    json={"data": "value"}
)

# Make raw HTTP requests
response = client.request(
    "GET",
    "custom/endpoint"
)

Error Handling

from httpx import HTTPStatusError

try:
    annotation = await client.retrieve_annotation(99999)
except HTTPStatusError as e:
    if e.response.status_code == 404:
        print("Annotation not found")
    else:
        print(f"API error: {e}")

Client Configuration

Both clients support various configuration options:

from rossum_api.dtos import UserCredentials, Token

# Using username/password
client = AsyncRossumAPIClient(
    base_url="https://elis.rossum.ai/api/v1",
    credentials=UserCredentials("user@example.com", "password"),
    timeout=30.0,
    n_retries=5,
    retry_backoff_factor=2.0,
    retry_max_jitter=1.0,
    max_in_flight_requests=8  # async only
)

# Using token
client = AsyncRossumAPIClient(
    base_url="https://elis.rossum.ai/api/v1",
    credentials=Token("your-api-token")
)

See Also