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

Enrichment

Endpoints for data enrichment

Operations

Companies

Endpoints for company management

Operations

Projects

Endpoints for project management

Operations

Create a project

Request

Creates a project based on the request

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

Project data

namestring(ProjectName)[ 1 .. 60 ] charactersrequired

Project name

Example: "My Project"
notestring(ProjectNote)[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
ocranyrequired
ocr.​enginestringrequired
Value"abbyy"
Discriminator
ocr.​featuresArray of strings(ProjectOCRAbbyyFeatures)required
Items Value"barcodes"
ocr.​languagesArray of strings(ProjectOCRAbbyyLanguages)[ 1 .. 5 ] itemsrequired

Array of abbyy ocr languages used within a project

Items Enum"Arabic""ArmenianEastern""ArmenianGrabar""ArmenianWestern""Bulgarian""Catalan""ChinesePRC""ChineseTaiwan""Croatian""Czech"
Example: ["German","English"]
extractionModelIdstring(ProjectExtractionModelId)required

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
completionstring(ProjectCompletion)

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
duplicatesstring(ProjectDuplicates)

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
membersanyrequired
members.​allowstring
Value"all"
Discriminator
schemaobject(Schema)
retentionDaysinteger[ 1 .. 3650 ]

Project document retention in days

Default 180
Example: 180
isLiveboolean(ProjectIsLive)

Indicates if a project is live or not

Default false
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/projects \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Project",
    "note": "My project description note",
    "ocr": {
      "engine": "abbyy",
      "features": [
        "barcodes"
      ],
      "languages": [
        "German",
        "English"
      ]
    },
    "extractionModelId": "63e6663823b4c1f5287398bb",
    "completion": "manual",
    "duplicates": "allow",
    "members": {
      "allow": "all"
    },
    "schema": {
      "version": 1,
      "dataPoints": [
        {
          "internalName": "type",
          "displayName": "Type",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "number",
          "displayName": "Number",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "issuedAt",
          "displayName": "Issued At",
          "type": "date",
          "preferDayOfMonth": "last",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "deliveredAt",
          "displayName": "Delivered At",
          "type": "date",
          "preferDayOfMonth": "last",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "currency",
          "displayName": "Currency",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        }
      ],
      "features": {
        "derivation": false
      },
      "enrichment": {},
      "normalization": {},
      "validation": {}
    },
    "retentionDays": 180,
    "isLive": false
  }'

Responses

Project created

Bodyapplication/json
idstring(ProjectId)required

Project ID

Example: "63e6663823b4c1f5287398bb"
createdAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
createdBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
updatedAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
updatedBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
namestring(ProjectName)[ 1 .. 60 ] charactersrequired

Project name

Example: "My Project"
notestring(ProjectNote)[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
extractionModelIdstring(ProjectExtractionModelId)required

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
ocranyrequired
ocr.​enginestringrequired
Value"abbyy"
Discriminator
ocr.​featuresArray of strings(ProjectOCRAbbyyFeatures)required
Items Value"barcodes"
ocr.​languagesArray of strings(ProjectOCRAbbyyLanguages)[ 1 .. 5 ] itemsrequired

Array of abbyy ocr languages used within a project

Items Enum"Arabic""ArmenianEastern""ArmenianGrabar""ArmenianWestern""Bulgarian""Catalan""ChinesePRC""ChineseTaiwan""Croatian""Czech"
Example: ["German","English"]
completionstring(ProjectCompletion)required

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
duplicatesstring(ProjectDuplicates)required

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
membersanyrequired
members.​allowstring
Value"all"
Discriminator
retentionDaysinteger(ProjectRetentionDays)[ 1 .. 3650 ]

Project document retention in days

Example: 180
isLiveboolean(ProjectIsLive)required

Indicates if a project is live or not

Default false
Response
application/json
{
  "id": "63e6663823b4c1f5287398bb",
  "createdAt": "1990-12-31T15:46:19.384990Z",
  "createdBy": "63e6663823b4c1f5287398bb",
  "updatedAt": "1990-12-31T15:46:19.384990Z",
  "updatedBy": "63e6663823b4c1f5287398bb",
  "name": "My Project",
  "note": "My project description note",
  "extractionModelId": "63e6663823b4c1f5287398bb",
  "ocr": {
    "engine": "abbyy",
    "features": [ … ],
    "languages": [ … ]
  },
  "completion": "manual",
  "duplicates": "allow",
  "members": {
    "allow": "all"
  },
  "retentionDays": 180,
  "isLive": false
}

Retrieve a projects list for given search criteria

Request

Security
OAuth2(Required scopes:
projects.read
)
Query
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"
isLiveboolean
searchstring(Search text used to find projects.)

Search text is used against projects name and id

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/projects?offset=0&limit=20&sort=-createdAt&isLive=true&search=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Projects list retrieved

Bodyapplication/json
dataArray of objects(Data)required
data[].​idstring(ProjectId)required

Project ID

Example: "63e6663823b4c1f5287398bb"
data[].​createdAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
data[].​createdBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
data[].​updatedAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
data[].​updatedBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
data[].​namestring(ProjectName)[ 1 .. 60 ] charactersrequired

Project name

Example: "My Project"
data[].​notestring(ProjectNote)[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
data[].​extractionModelIdstring(ProjectExtractionModelId)required

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
data[].​ocranyrequired
data[].​ocr.​enginestringrequired
Value"abbyy"
Discriminator
data[].​ocr.​featuresArray of strings(ProjectOCRAbbyyFeatures)required
Items Value"barcodes"
data[].​ocr.​languagesArray of strings(ProjectOCRAbbyyLanguages)[ 1 .. 5 ] itemsrequired

Array of abbyy ocr languages used within a project

Items Enum"Arabic""ArmenianEastern""ArmenianGrabar""ArmenianWestern""Bulgarian""Catalan""ChinesePRC""ChineseTaiwan""Croatian""Czech"
Example: ["German","English"]
data[].​completionstring(ProjectCompletion)required

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
data[].​duplicatesstring(ProjectDuplicates)required

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
data[].​membersanyrequired
data[].​members.​allowstring
Value"all"
Discriminator
data[].​retentionDaysinteger(ProjectRetentionDays)[ 1 .. 3650 ]

Project document retention in days

Example: 180
data[].​isLiveboolean(ProjectIsLive)required

Indicates if a project is live or not

Default false
limitinteger(limit)required
Example: 20
offsetinteger(offset)required
Example: 0
totalCountinteger(Totalcount)required
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "limit": 20,
  "offset": 0,
  "totalCount": 1
}

Retrieve a project by id

Request

Retrieve a project by id

Security
OAuth2(Required scopes:
projects.read
)
Path
idstring(ProjectId)required

Project id

Example: 63e6663823b4c1f5287398bb
curl -i -X GET \
  https://api.cloud.hypatos.ai/v2/projects/63e6663823b4c1f5287398bb \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Project by id

Bodyapplication/json
idstring(ProjectId)required

Project ID

Example: "63e6663823b4c1f5287398bb"
createdAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
createdBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
updatedAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
updatedBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
namestring(ProjectName)[ 1 .. 60 ] charactersrequired

Project name

Example: "My Project"
notestring(ProjectNote)[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
extractionModelIdstring(ProjectExtractionModelId)required

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
ocranyrequired
ocr.​enginestringrequired
Value"abbyy"
Discriminator
ocr.​featuresArray of strings(ProjectOCRAbbyyFeatures)required
Items Value"barcodes"
ocr.​languagesArray of strings(ProjectOCRAbbyyLanguages)[ 1 .. 5 ] itemsrequired

Array of abbyy ocr languages used within a project

Items Enum"Arabic""ArmenianEastern""ArmenianGrabar""ArmenianWestern""Bulgarian""Catalan""ChinesePRC""ChineseTaiwan""Croatian""Czech"
Example: ["German","English"]
completionstring(ProjectCompletion)required

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
duplicatesstring(ProjectDuplicates)required

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
membersanyrequired
members.​allowstring
Value"all"
Discriminator
retentionDaysinteger(ProjectRetentionDays)[ 1 .. 3650 ]

Project document retention in days

Example: 180
isLiveboolean(ProjectIsLive)required

Indicates if a project is live or not

Default false
Response
application/json
{
  "id": "63e6663823b4c1f5287398bb",
  "createdAt": "1990-12-31T15:46:19.384990Z",
  "createdBy": "63e6663823b4c1f5287398bb",
  "updatedAt": "1990-12-31T15:46:19.384990Z",
  "updatedBy": "63e6663823b4c1f5287398bb",
  "name": "My Project",
  "note": "My project description note",
  "extractionModelId": "63e6663823b4c1f5287398bb",
  "ocr": {
    "engine": "abbyy",
    "features": [ … ],
    "languages": [ … ]
  },
  "completion": "manual",
  "duplicates": "allow",
  "members": {
    "allow": "all"
  },
  "retentionDays": 180,
  "isLive": false
}

Update a project

Request

Update a project by id. This endpoint supports partial updates using PATCH semantics:

  • Only fields present in the request will be updated
  • Null values will clear optional fields (note, retentionDays)
  • Absent fields will remain unchanged
  • Required fields (name, extractionModelId, ocr, completion, duplicates, isLive, members, schema) cannot be set to null
  • At least one field must be provided in the request
Security
OAuth2(Required scopes:
projects.write
)
Path
idstring(ProjectId)required

Project id

Example: 63e6663823b4c1f5287398bb
Bodyapplication/jsonrequired

Project update data (all fields optional for partial update)

namestring(ProjectName)[ 1 .. 60 ] characters

Project name

Example: "My Project"
notestring[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
ocrany
extractionModelIdstring(ProjectExtractionModelId)

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
completionstring(ProjectCompletion)

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
duplicatesstring(ProjectDuplicates)

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
retentionDaysinteger[ 1 .. 3650 ]

Project document retention in days

Example: 180
isLiveboolean(ProjectIsLive)

Indicates if a project is live or not

Default false
membersany
schemaobject(Schema)
curl -i -X PATCH \
  https://api.cloud.hypatos.ai/v2/projects/63e6663823b4c1f5287398bb \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Project",
    "note": "My project description note",
    "ocr": {
      "engine": "abbyy",
      "features": [
        "barcodes"
      ],
      "languages": [
        "German",
        "English"
      ]
    },
    "extractionModelId": "63e6663823b4c1f5287398bb",
    "completion": "manual",
    "duplicates": "allow",
    "retentionDays": 180,
    "isLive": false,
    "members": {
      "allow": "all"
    },
    "schema": {
      "version": 1,
      "dataPoints": [
        {
          "internalName": "type",
          "displayName": "Type",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "number",
          "displayName": "Number",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "issuedAt",
          "displayName": "Issued At",
          "type": "date",
          "preferDayOfMonth": "last",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "deliveredAt",
          "displayName": "Delivered At",
          "type": "date",
          "preferDayOfMonth": "last",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        },
        {
          "internalName": "currency",
          "displayName": "Currency",
          "type": "string",
          "source": {
            "type": "extractor"
          },
          "normalization": [],
          "rules": {}
        }
      ],
      "features": {
        "derivation": false
      },
      "enrichment": {},
      "normalization": {},
      "validation": {}
    }
  }'

Responses

Project updated

Bodyapplication/json
idstring(ProjectId)required

Project ID

Example: "63e6663823b4c1f5287398bb"
createdAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
createdBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
updatedAtstring(date-time)required
Example: "1990-12-31T15:46:19.384990Z"
updatedBystring(ProjectMemberId)required

Project member id

Example: "63e6663823b4c1f5287398bb"
namestring(ProjectName)[ 1 .. 60 ] charactersrequired

Project name

Example: "My Project"
notestring(ProjectNote)[ 1 .. 1000 ] characters

Project note

Example: "My project description note"
extractionModelIdstring(ProjectExtractionModelId)required

Extraction Model id

Example: "63e6663823b4c1f5287398bb"
ocranyrequired
ocr.​enginestringrequired
Value"abbyy"
Discriminator
ocr.​featuresArray of strings(ProjectOCRAbbyyFeatures)required
Items Value"barcodes"
ocr.​languagesArray of strings(ProjectOCRAbbyyLanguages)[ 1 .. 5 ] itemsrequired

Array of abbyy ocr languages used within a project

Items Enum"Arabic""ArmenianEastern""ArmenianGrabar""ArmenianWestern""Bulgarian""Catalan""ChinesePRC""ChineseTaiwan""Croatian""Czech"
Example: ["German","English"]
completionstring(ProjectCompletion)required

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Default "manual"
Enum"automatic""manual"
Example: "manual"
duplicatesstring(ProjectDuplicates)required

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Default "fail"
Enum"allow""fail"
Example: "allow"
membersanyrequired
members.​allowstring
Value"all"
Discriminator
retentionDaysinteger(ProjectRetentionDays)[ 1 .. 3650 ]

Project document retention in days

Example: 180
isLiveboolean(ProjectIsLive)required

Indicates if a project is live or not

Default false
Response
application/json
{
  "id": "63e6663823b4c1f5287398bb",
  "createdAt": "1990-12-31T15:46:19.384990Z",
  "createdBy": "63e6663823b4c1f5287398bb",
  "updatedAt": "1990-12-31T15:46:19.384990Z",
  "updatedBy": "63e6663823b4c1f5287398bb",
  "name": "My Project",
  "note": "My project description note",
  "extractionModelId": "63e6663823b4c1f5287398bb",
  "ocr": {
    "engine": "abbyy",
    "features": [ … ],
    "languages": [ … ]
  },
  "completion": "manual",
  "duplicates": "allow",
  "members": {
    "allow": "all"
  },
  "retentionDays": 180,
  "isLive": false
}

Retrieve a schema by project id

Request

Retrieve a schema by project id

Security
OAuth2(Required scopes:
projects.read
)
Path
idstring(ProjectId)required

Project id

Example: 63e6663823b4c1f5287398bb
curl -i -X GET \
  https://api.cloud.hypatos.ai/v2/projects/63e6663823b4c1f5287398bb/schema \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Schema retrieved

Bodyapplication/json
versioninteger(Version)
Example: 1
dataPointsArray of objects(DataPoints)
Example: [{"internalName":"type","displayName":"Type","type":"string","source":{"type":"extractor"},"normalization":[],"rules":{}},{"internalName":"number","displayName":"Number","type":"string","source":{"type":"extractor"},"normalization":[],"rules":{}},{"internalName":"issuedAt","displayName":"Issued At","type":"date","preferDayOfMonth":"last","source":{"type":"extractor"},"normalization":[],"rules":{}},{"internalName":"deliveredAt","displayName":"Delivered At","type":"date","preferDayOfMonth":"last","source":{"type":"extractor"},"normalization":[],"rules":{}},{"internalName":"currency","displayName":"Currency","type":"string","source":{"type":"extractor"},"normalization":[],"rules":{}}]
featuresobject
enrichmentobject
normalizationobject
validationobject
Response
application/json
{
  "version": 1,
  "dataPoints": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "features": {
    "derivation": false
  },
  "enrichment": {},
  "normalization": {},
  "validation": {}
}

E-Invoices

Endpoints for e-invoices

Operations

Documents XML

Endpoints serving project-scoped documents as XML

Operations

Emails

Operations

Document Routing

Operations

Users

Operations