Skip to content

Hypatos REST API (2.51.0)

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
Languages
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

Retrieve a list of documents

Request

Retrieve a list of documents.

Security
OAuth2(Required scopes:
documents.read
)
Query
projectIdArray of strings

Project ids to to find items by. If ommitted, items from all existing 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(DocumentState)

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

Items Enum"done""doneAutomatically""extracted""failed""inCompletion""junk""new""processing""rejected""reviewRequired"
fileIdstring

File identifier to retrieve documents that were created from that file

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

Responses

List of documents

Bodyapplication/json
dataArray of objects(DocumentResponse)
limitinteger

The limit used for this page of results. This will be the same as the limit query parameter unless it exceeds the maximal 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
}

Request processing of a file

Request

Request a processing of a file that was previously uploaded. The fileId in the request body is representing the identifier of the file that was returned by the upload endpoint. As a result of this request a document will be created and its identifier will be returned in the response. The projectId in the request body is an identifier of the project to create the document in.

Security
OAuth2(Required scopes:
documents.write
)
Bodyapplication/jsonrequired

Payload for processing the given file

fileIdstringrequired
Example: "5349b4ddd2781d08c09890f4"
projectIdstringrequired
Example: "00000020f51bb4362eee2a4d"
externalIdstring

External id of the file. Can be used if you want to link the file with an identifier in your system.

Example: "doc-0001"
externalDataobject(DocumentsUpdateExternalDataRequest)

External data to be associated with the document. The data are provided as a flat JSON object. The properties of that object are case-insensitive. The maximum amount of properties is limited to 20.

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/documents/process-file \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileId": "5349b4ddd2781d08c09890f4",
    "projectId": "00000020f51bb4362eee2a4d",
    "externalId": "doc-0001",
    "externalData": {
      "key1": "value1",
      "key2": "value2"
    }
  }'

Responses

Processing accepted

Bodyapplication/json
documentIdstringrequired
Example: "6040dc9680b782b365ea77d5"
fileIdstringrequired
Example: "5349b4ddd2781d08c09890f4"
projectIdstringrequired
Example: "00000020f51bb4362eee2a4d"
Response
application/json
{
  "documentId": "6040dc9680b782b365ea77d5",
  "fileId": "5349b4ddd2781d08c09890f4",
  "projectId": "00000020f51bb4362eee2a4d"
}

Retrieve a document by id

Request

Retrieve a document by id

Security
OAuth2(Required scopes:
documents.read
)
Path
idstringrequired

Id of the document to get.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/documents/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Document retrieved.

Bodyapplication/json
idstringrequired
Example: "6040dc9680b782b365ea77d5"
completedAtstring(date-time)
Example: "1990-12-31T15:59:60-08:00"
completedBystring
createdAtstring(date-time)required
Example: "1990-12-31T15:59:60-08:00"
createdBystringrequired
fileIdstring

Identifier of the primary file associated with this document.

Example: "5349b4ddd2781d08c09890f4"
filesArray of objects(DocumentFile)

List of files associated with this document, each with their assigned role and main file flag.

Example: [{"id":"5349b4ddd2781d08c09890f4","type":"salesOrder","mainFile":true}]
entitiesobject
Example: {"currency":"EUR","items":[{"name":"High quality cement for rabbit hole sealing","qty":1}],"number":"2018-DE-0011122351","qty":2}
externalIdstring
Example: "doc-0001"
externalDataobject
Example: {"internalSystemId":"sap-01"}
projectIdstring
Example: "6040dc9680b782b365ea77d5"
statestring(DocumentState)required
Enum"done""doneAutomatically""extracted""failed""inCompletion""junk""new""processing""rejected""reviewRequired"
titlestringrequired
Example: "scan-doc-1.jpg"
updatedAtstring(date-time)
Example: "1990-12-31T15:59:60-08:00"
updatedBystring
urlstring

URL to access the document

Example: "https://example.com/documents/6040dc9680b782b365ea77d5"
Response
application/json
{
  "id": "6040dc9680b782b365ea77d5",
  "completedAt": "1990-12-31T15:59:60-08:00",
  "completedBy": "string",
  "createdAt": "1990-12-31T15:59:60-08:00",
  "createdBy": "string",
  "fileId": "5349b4ddd2781d08c09890f4",
  "files": [
    { … }
  ],
  "entities": {
    "currency": "EUR",
    "items": [ … ],
    "number": "2018-DE-0011122351",
    "qty": 2
  },
  "externalId": "doc-0001",
  "externalData": {
    "internalSystemId": "sap-01"
  },
  "projectId": "6040dc9680b782b365ea77d5",
  "state": "done",
  "title": "scan-doc-1.jpg",
  "updatedAt": "1990-12-31T15:59:60-08:00",
  "updatedBy": "string",
  "url": "https://example.com/documents/6040dc9680b782b365ea77d5"
}

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

Request

Update information about the transfer for the given document

Security
OAuth2(Required scopes:
documents.write
)
Path
idstringrequired

Id of of the document 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 in the erroneous case this field is valueable.

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

Responses

Document transfer infor accepted

Response
No content

Provide information about the rejection of a document in the target system

Request

Update information about the rejection for the given document

Security
OAuth2(Required scopes:
documents.write
)
Path
idstringrequired

Id of of the document to update.

Bodyapplication/json

Payload about the rejection

messagestring

May be used to provide additional details about the rejection.

curl -i -X POST \
  'https://api.cloud.hypatos.ai/v2/documents/{id}/reject' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Document was rejected!"
  }'

Responses

Document rejection request accepted

Response
No content

Provide external data for a document with given id

Request

Update the external data for a document with given identifier. The external data are provided as a flat JSON object. The payload of this requests completley overrides the existing external data of a document. To remove the data, justsend empty JSON object {} in the payload.

Please note that the maximum lenght of an key is 50 characters. Any value with a longer key will be omitted. The maximum amount of key-value pairs is limited to 20.

Security
OAuth2(Required scopes:
documents.write
)
Path
idstringrequired

Id of the document to update.

Bodyapplication/jsonrequired

Payload containing the external data.

key1string
Example: "value1"
key2string
Example: "value2"
curl -i -X POST \
  'https://api.cloud.hypatos.ai/v2/documents/{id}/external-data' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "key1": "value1",
    "key2": "value2"
  }'

Responses

External data provided for the document accepted.

Response
No content

Provide an external identifier for a document with given id

Request

Provide an external identifier for a document with given id

Security
OAuth2(Required scopes:
documents.write
)
Path
idstringrequired

Id of the document to update.

Bodytext/plainrequired

Update external id for a given document.

string(DocumentsUpdateExternalIdRequest)

External ID

curl -i -X POST \
  'https://api.cloud.hypatos.ai/v2/documents/{id}/external-id' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: text/plain' \
  -d 15b884b0-d551-4865-bda9-4168800c9d87

Responses

External ID provided for the document accepted.

Response
No content

Provide a title for a document with given id

Request

Provide a title for a document with given id.

Security
OAuth2(Required scopes:
documents.write
)
Path
idstringrequired

Id of the document to update.

Bodytext/plainrequired

Title for a given document.

string(DocumentsUpdateTitleRequest)<= 256 characters

New Title

curl -i -X POST \
  'https://api.cloud.hypatos.ai/v2/documents/{id}/title' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: text/plain' \
  -d 'New Title of Document'

Responses

Document title provided for the document accepted.

Response
No content

Retrieve Document States

Request

Provides a list of states that the specified document has passed through. If the document is still being processed, the number of returned states should not be considered final. Subsequent calls to this endpoint may return additional states as the document continues to progress through the processing pipeline.

Security
OAuth2(Required scopes:
documents.read
)
Path
idstringrequired

Id of the document to get states of.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/documents/{id}/states' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Document states.

Bodyapplication/jsonArray [
statestring(DocumentState)
Enum"done""doneAutomatically""extracted""failed""inCompletion""junk""new""processing""rejected""reviewRequired"
updatedAtstring(date-time)
Example: "1990-12-31T15:59:60-08:00"
]
Response
application/json
[
  {
    "state": "done",
    "updatedAt": "1990-12-31T15:59:60-08:00"
  }
]

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

Emails

Operations

Document Routing

Operations

Users

Operations