Hypatos REST API (2.68.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Introduction

The Hypatos API is organized around REST. The majority of the endpoints provide CRUD functionality for resources. The API is also exposing Intent Resources which mimic user intents or actions.

The Hypatos API uses OAuth 2.0 Client Credential Grant to authenticate requests. Before making any requests to any endpoint a client must authenticate with the authorization server and requests an access token from the token endpoint.

  POST /auth/token HTTP/1.1
  Host: api.cloud.hypatos.ai
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

  grant_type=client_credentials

Authorization header contains client_id:client_secret encoded as explained in RFC Client Password section.

If the authorization server authenticated the client successfully, an access token is issued. Here is an example successful response:

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
    "access_token": "mF_9.B5f-4.1JqM",
    "expires_in": 86400,
    "scope": "enrichment.write files.read",
    "token_type": "Bearer",
  }

This token can be used to authenticate the requests to API endpoints by sending a Bearer token in the Authorization HTTP header. The following example demonstrates how to use the access token to retrieve a list of documents.

  GET /v2/documents HTTP/1.1
  Host: api.cloud.hypatos.ai
  Authorization: Bearer mF_9.B5f-4.1JqM

Versioning

Changes to this API are released regularly. We use Semantic Versioning 2.0.0 scheme for versioning so that the clients can identify any backward-incompatible changes easily. Briefly summarized one can say, if the MAJOR version of the new API version didn't change you can expect the new version to be backward-compatible.

Rate limits

In order to maximise the stability of our API, we institue rate limits for all of API endpoints. Clients who send too many requests over a given period of time will see error responses that show up as status code 429 Too Many Requests.

When you see error responses with status code 429, it means you exhausted your current quota and need to withhold from sending further requests until the quota is reset. We encourage you not to wait until you get a 429 error but to monitor your quota in each request. In each response you receive from the API, you will find HTTP headers providing the details about your current quota. Here is the list of the HTTP headers:

x-ratelimit-limit: Indicates the quota associated to the client in the current time-window followed by the description of the quota policy.
x-ratelimit-remaining: Indicates the number of remaining requests in the current time-window
x-ratelimit-reset: Indicates the number of seconds until quota reset of the current time-window

Please note that IETF is currently in the process of publishing a standard for these headers. Please explore the draft for more details.

A basic technique to gracefully handle rate limits is watch for your quota permanently and increase the time between your request as the quota is decreasing. To recover from a 429 error you need a retry mechanism following an exponential backoff schedule.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License

Apache 2.0

Servers

API EU

https://api.cloud.hypatos.ai/v2

API US

https://api.cloud.hypatos.com/v2

Mock server

https://hypatos.redocly.app/_mock/openapi

Authorization

Endpoints for handling the OAuth 2.0 Client Credentials Grant flow.

Operations

Files

Endpoints for management of files

Operations

Documents

Endpoints for document management

Operations

Cases

Endpoints for case management

Operations

Request processing of a file batch into cases

Request

Request processing of a batch of files that were previously uploaded. The fileIds in the request body represent the identifiers of the files returned by the upload endpoint.

This is an asynchronous operation. A successful response confirms that the request has been accepted; the actual case creation is carried out in the background by AI Agents that analyze the file batch to determine which files belong to which case and what role each file plays. Use the returned fileBatchId to track the resulting cases via GET /cases.

The projectId in the request body is the identifier of the project in which the cases will be created.

The optional externalId and externalData fields will be associated with both the file batch and propagated to each case created from it.

Security

OAuth2(Required scopes:

cases.write

)

Bodyapplication/jsonrequired

Payload for processing the given file batch

fileIdsArray of stringsnon-emptyrequired

List of file identifiers to be processed as a batch into cases.

Example: ["375514e5-dac7-4b8d-963f-7f7b9e6d3d04","96844098-0059-4664-95b8-c4c072aa94e3"]

projectIdstringrequired

Identifier of the project in which the cases will be created.

Example: "69bbd0546290cc2162b433de"

externalIdstring

External identifier of the file batch. Can be used to link the batch with an identifier in your system. Will be propagated to all cases created from this batch.

Example: "batch-0001"

externalDataobject(ExternalData)

Associated external data. Will be applied to the case or to all cases in a batch. Provided as a flat JSON object. The properties are case-insensitive. The maximum amount of properties is limited to 20.

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/cases/process-file-batch \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileIds": [
      "bf105800-594d-48df-a5df-4d9d0554708d",
      "3efd83f6-5009-4f9f-bc0c-4891c9a44e06"
    ],
    "projectId": "69bbd0fbf8dbeab5f8db7675"
  }'

Responses

File batch processing request accepted. Cases will be created asynchronously.

Bodyapplication/json

fileBatchIdstringrequired

Identifier of the file batch. Can be used to retrieve the cases created from this batch via GET /cases once processing is complete.

Example: "0e99a5b2-9010-4e86-a906-19c45e903fe8"

fileIdsArray of stringsrequired

List of file identifiers that are part of this batch.

Example: ["2a77b5c8-30de-4e35-b078-3bba981cf80c","2c6fe52d-26c0-4a7a-80a9-97d497b1a078"]

projectIdstringrequired

Identifier of the project in which the cases will be created.

Example: "69bbd1d72f6eb584a70e79f0"

Response

application/json

{
  "fileBatchId": "0e99a5b2-9010-4e86-a906-19c45e903fe8",
  "fileIds": [
    "2a77b5c8-30de-4e35-b078-3bba981cf80c",
    "2c6fe52d-26c0-4a7a-80a9-97d497b1a078"
  ],
  "projectId": "69bbd1d72f6eb584a70e79f0"
}

Create a case manually

Request

Manually create a case from a list of previously uploaded files. Each file in the request must be accompanied by a type indicating the role the file plays in the case (e.g. main document, attachment).

This is the manual case creation path, intended for API clients that determine case composition directly, as opposed to the AI-driven case creation triggered by POST /cases/process-file-batch.

This is an asynchronous operation. A successful response confirms that the request has been accepted and returns the identifier of the case being created. The case will be processed in the background.

The projectId in the request body is the identifier of the project in which the case will be created.

Security

OAuth2(Required scopes:

cases.write

)

Bodyapplication/jsonrequired

Payload for creating a case

filesArray of objects(CaseFile)non-emptyrequired

List of files to include in the case, each with their assigned role.

files[].idstring^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

Identifier of the file as returned by the upload endpoint.

Example: "197c997c-4bab-41e7-b33d-bad287046914"

files[].typestring^[a-zA-Z]+$required

The role the file plays in the case (e.g. mainDocument, attachment). Must only contain letters from the Latin alphabet with no whitespace or special characters.

Example: "salesOrder"

files[].mainFilebooleanrequired

Indicates whether this file is the main document of the case.

Example: true

projectIdstringrequired

Identifier of the project in which the case will be created.

Example: "69bbd1e18cab258833c9ecf8"

externalIdstring

External identifier of the case. Can be used to link the case with an identifier in your system.

Example: "case-0001"

externalDataobject(ExternalData)

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/cases/create \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "files": [
      {
        "id": "92b5be52-ce1e-4c74-b1ba-b6897c5d447a",
        "type": "salesOrder",
        "mainFile": true
      },
      {
        "id": "76bf4146-3ab2-4a8b-8c93-081f1de780b7",
        "type": "attachment",
        "mainFile": false
      }
    ],
    "projectId": "69bbd13093eba3eee76f3918"
  }'

Responses

Case creation request accepted. The case will be created asynchronously.

Bodyapplication/json

caseIdstringrequired

Identifier of the case being created. Can be used to retrieve the case via GET /cases/{id} once processing is complete.

Example: "8512a5dd-91b9-4363-a869-db17394a955d"

projectIdstringrequired

Identifier of the project in which the case is being created.

Example: "69bbd20e5c155a70e763bc8d"

Response

application/json

{
  "caseId": "8512a5dd-91b9-4363-a869-db17394a955d",
  "projectId": "69bbd20e5c155a70e763bc8d"
}

Retrieve a list of cases

Request

Retrieve a list of cases.

Security

OAuth2(Required scopes:

cases.read

)

Query

projectIdsArray of strings

Used to retrieve cases belonging to specific projects only. Multiple project identifiers can be provided. By default, cases from all accessible projects are returned.

offsetinteger>= 0

A zero-based offset of the first item in the data collection to return.

limitinteger[ 0 .. 50 ]

Limit the amount of items returned in the response. If the value exceeds the maximum, then the maximum value will be used.

Default 20

sortstring

The field to sort reponse items by.

Default "-createdAt"

Enum"createdAt""-createdAt""+createdAt""updatedAt""-updatedAt""+updatedAt"

stateArray of strings(CaseState)

Used to retrieve cases that are in specific states only. Multiple states can be used for this filtering. By default, cases in all states are returned.

Items Enum"done""doneAutomatically""failed""inCompletion""new""processing""rejected""reviewRequired""transferFailed""transferred"

fileBatchIdstring

File batch identifier to retrieve cases that were created from that file batch.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/cases?projectIds=string&offset=0&limit=20&sort=createdAt&state=done&fileBatchId=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

List of cases

Bodyapplication/json

dataArray of objects(CaseResponse)required

data[].idstringrequired

Example: "69c5a545-7b2f-4f4a-833b-45feff1056c7"

data[].createdAtstring(date-time)required

Example: "2020-01-01T15:00:00Z"

data[].createdBystringrequired

data[].completedAtstring(date-time)

Example: "2020-01-01T15:00:00Z"

data[].completedBystring

data[].updatedAtstring(date-time)

Example: "2020-01-01T15:00:00Z"

data[].updatedBystring

data[].transferSuccessfulboolean

Indicates whether the case was transferred successfully to the target system. Will be null if the transfer status is not yet known (e.g. because the case is still being processed or the transfer information has not been provided yet).

Example: true

data[].transferMessagestring

May contain additional information about the transfer, especially in the case of a failed transfer.

Example: "Upload failed due to ERP being down"

data[].filesArray of objects(CaseFile)required

List of files that are part of the case, each with their assigned role and main document flag.

data[].files[].idstring^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

Identifier of the file as returned by the upload endpoint.

Example: "197c997c-4bab-41e7-b33d-bad287046914"

data[].files[].typestring^[a-zA-Z]+$required

The role the file plays in the case (e.g. mainDocument, attachment). Must only contain letters from the Latin alphabet with no whitespace or special characters.

Example: "salesOrder"

data[].files[].mainFilebooleanrequired

Indicates whether this file is the main document of the case.

Example: true

data[].entitiesobject

Entities extracted from the case by the AI Agents.

Example: {"currency":"EUR","items":[{"name":"High quality cement for rabbit hole sealing","qty":1}],"number":"2018-DE-0011122351","qty":2}

data[].externalIdstring

Example: "case-0001"

data[].externalDataobject

Example: {"internalSystemId":"sap-01"}

data[].projectIdstringrequired

Example: "69bbd22c92f3c3ee4a097784"

data[].fileBatchIdstring

Identifier of the file batch this case was created from. Only present for cases created via POST /cases/process-file-batch.

Example: "a1b0020b-8ef9-4801-aeef-979224af0bab"

data[].previewFileIdstring

Identifier of the file used as the case preview, if any.

Example: "197c997c-4bab-41e7-b33d-bad287046914"

data[].statestring(CaseState)required

Enum"done""doneAutomatically""failed""inCompletion""new""processing""rejected""reviewRequired""transferFailed""transferred"

data[].urlstring

URL to access the case.

Example: "https://example.com/cases/6040dc9680b782b365ea77d5"

limitinteger

The limit used for this page of results. This will be the same as the limit query parameter unless it exceeds the maximum allowed value.

Example: 20

offsetinteger

The offset used for this page of results. This will be the same as the offset query parameter.

Example: 0

totalCountinteger

The total number of elements in the data attribute.

Example: 1000

Response

application/json

{
  "data": [
    { … }
  ],
  "limit": 20,
  "offset": 0,
  "totalCount": 1000
}

Retrieve a case by id

Request

Retrieve a case by id.

Security

OAuth2(Required scopes:

cases.read

)

Path

idstringrequired

Id of the case to get.

Example: d43447fc-4e23-42e2-86cc-b35e16fa5e6f

curl -i -X GET \
  https://api.cloud.hypatos.ai/v2/cases/d43447fc-4e23-42e2-86cc-b35e16fa5e6f \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Case retrieved.

Bodyapplication/json

idstringrequired

Example: "69c5a545-7b2f-4f4a-833b-45feff1056c7"

createdAtstring(date-time)required

Example: "2020-01-01T15:00:00Z"

createdBystringrequired

completedAtstring(date-time)

Example: "2020-01-01T15:00:00Z"

completedBystring

updatedAtstring(date-time)

Example: "2020-01-01T15:00:00Z"

updatedBystring

transferSuccessfulboolean

Example: true

transferMessagestring

May contain additional information about the transfer, especially in the case of a failed transfer.

Example: "Upload failed due to ERP being down"

filesArray of objects(CaseFile)required

List of files that are part of the case, each with their assigned role and main document flag.

files[].idstring^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

Identifier of the file as returned by the upload endpoint.

Example: "197c997c-4bab-41e7-b33d-bad287046914"

files[].typestring^[a-zA-Z]+$required

The role the file plays in the case (e.g. mainDocument, attachment). Must only contain letters from the Latin alphabet with no whitespace or special characters.

Example: "salesOrder"

files[].mainFilebooleanrequired

Indicates whether this file is the main document of the case.

Example: true

entitiesobject

Entities extracted from the case by the AI Agents.

Example: {"currency":"EUR","items":[{"name":"High quality cement for rabbit hole sealing","qty":1}],"number":"2018-DE-0011122351","qty":2}

externalIdstring

Example: "case-0001"

externalDataobject

Example: {"internalSystemId":"sap-01"}

projectIdstringrequired

Example: "69bbd22c92f3c3ee4a097784"

fileBatchIdstring

Identifier of the file batch this case was created from. Only present for cases created via POST /cases/process-file-batch.

Example: "a1b0020b-8ef9-4801-aeef-979224af0bab"

previewFileIdstring

Identifier of the file used as the case preview, if any.

Example: "197c997c-4bab-41e7-b33d-bad287046914"

statestring(CaseState)required

Enum"done""doneAutomatically""failed""inCompletion""new""processing""rejected""reviewRequired""transferFailed""transferred"

urlstring

URL to access the case.

Example: "https://example.com/cases/6040dc9680b782b365ea77d5"

Response

application/json

{
  "id": "69c5a545-7b2f-4f4a-833b-45feff1056c7",
  "createdAt": "2020-01-01T15:00:00Z",
  "createdBy": "string",
  "completedAt": "2020-01-01T15:00:00Z",
  "completedBy": "string",
  "updatedAt": "2020-01-01T15:00:00Z",
  "updatedBy": "string",
  "transferSuccessful": true,
  "transferMessage": "Upload failed due to ERP being down",
  "files": [
    { … }
  ],
  "entities": {
    "currency": "EUR",
    "items": [ … ],
    "number": "2018-DE-0011122351",
    "qty": 2
  },
  "externalId": "case-0001",
  "externalData": {
    "internalSystemId": "sap-01"
  },
  "projectId": "69bbd22c92f3c3ee4a097784",
  "fileBatchId": "a1b0020b-8ef9-4801-aeef-979224af0bab",
  "previewFileId": "197c997c-4bab-41e7-b33d-bad287046914",
  "state": "done",
  "url": "https://example.com/cases/6040dc9680b782b365ea77d5"
}

Provide information about a transfer of a case to the target system

Request

Update information about the transfer for the given case.

Security

OAuth2(Required scopes:

cases.write

)

Path

idstringrequired

Id of the case to update.

Bodyapplication/jsonrequired

Payload about the transfer

successfulbooleanrequired

Indicates if the transfer was successful or not.

Example: true

messagestring

May be used to provide additional details about the transfer. Especially valuable in the erroneous case.

curl -i -X POST \
  'https://api.cloud.hypatos.ai/v2/cases/{id}/transfer' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "successful": true
  }'

Responses

Case transfer info accepted

Response

No content

Download files of a case

Request

Download the files that are part of a case. The response format is determined by the Accept header:

multipart/mixed — returns all files as a multipart response, where each part contains the binary content of a file with its own Content-Type and Content-Disposition headers. This allows the client to iterate over the parts and attach each file individually to a workflow without any unzipping.
application/zip — returns all files packaged as a ZIP archive. Each file is stored under its original filename as provided during upload. Use this if your HTTP client does not support multipart response parsing.

The files returned can be filtered by their mainFile flag or by their type using the query parameters below. If no filters are provided, all files of the case are returned.

Security

OAuth2(Required scopes:

cases.read

)

Path

idstringrequired

Id of the case whose files should be downloaded.

Query

mainFileboolean

If set to true, only the main file of the case is returned. If set to false, only non-main files are returned. If omitted, all files are returned regardless of their main file flag.

typeArray of strings

Used to retrieve only files of specific types. Multiple types can be provided. If omitted, files of all types are returned.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/cases/{id}/files?mainFile=true&type=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Files of the case.

Headers

Content-Dispositionstring

For application/zip responses, suggests a filename for the downloaded archive in the format case-{id}-files.zip.

Example: "attachment; filename=\"case-6040dc9680b782b365ea77d5-files.zip\""

Body

object

A multipart response where each part corresponds to one file of the case. Each part contains the binary content of the file and the following headers:

Content-Type: the media type of the file (e.g. application/pdf, image/jpeg)
Content-Disposition: contains the filename of the file
X-Hy-File-Id: the identifier of the file
X-Hy-File-Type: the type of the file as defined in the case
X-Hy-File-Main: true if this is the main file of the case, false otherwise

Response

--boundary-separator
Content-Type: application/json

{}
--boundary-separator
Content-Type: application/json

{}
--boundary-separator
Content-Type: application/json

{}
--boundary-separator--

Enrichment

Endpoints for data enrichment

Operations

Companies

Endpoints for company management

Operations

Projects

Endpoints for project management

Operations

E-Invoices

Endpoints for e-invoices

Operations

Documents XML

Endpoints serving project-scoped documents as XML

Operations

Agent Management

Endpoints for managing agents and agent workflows

Operations

Emails

Operations

Document Routing

Operations

Enrichment workflows

Operations

Users

Operations

Hypatos REST API (2.68.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Introduction

Versioning

Rate limits

Authorization

Files

Documents

Cases

Request processing of a file batch into cases

RequestExpand all

Responses

Was this helpful?

Create a case manually

RequestExpand all

Responses

Was this helpful?

Retrieve a list of cases

Request

Responses

Was this helpful?

Retrieve a case by id

Request

Responses

Was this helpful?

Provide information about a transfer of a case to the target system

Request

Responses

Was this helpful?

Download files of a case

Request

Responses

Was this helpful?

Enrichment

Companies

Projects

E-Invoices

Documents XML

Agent Management

Emails

Document Routing

Enrichment workflows

Users

Hypatos REST API (2.68.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Request