# Hyperscience API Overview

- Updated on Jul 17, 2025
- Published on Mar 18, 2025
- 2 minute(s) read

The Hyperscience API uses REST API endpoints and returns responses in JSON. The API supports a variety of use cases, including:

- Submitting and retrieving files.
- Submitting and retrieving cases.
- Retrieving documents, pages, fields, tables, and data types.
- Generating reports.

To learn more about the API, see our [API documentation](https://docs.hyperscience.ai/).

## Authentication

Only users with the API Access permission can make API calls. To make API calls, you need to authenticate your user. There are two ways to authenticate, depending on your instance’s type:

- For on-premise / private cloud instances, see [Managing API Tokens](https://help.hyperscience.ai/v41/docs/managing-api-tokens).
- For SaaS instances, see [API Access for SaaS Instances](https://help.hyperscience.ai/deployment/docs/api-access-for-saas-instances).

## Files submission

The Submission Creation endpoint gives you the option to submit files seamlessly through the API. To submit files, you need to make a POST request to _/api/v5/submissions_. This endpoint provides three ways of submitting files:

- By submitting the image files into the Submission Creation endpoint as _multipart/form-data_ via the _file_ parameter.
- By passing Base64-encoded file data in JSON format to the Submission Creation endpoint as _multipart/json_ via the _files_ parameter.
- By referencing the location of the files in the Submission Creation endpoint via the _file_ or _files_ parameter. The application will retrieve them on its own. In this case, you would use _application/x-www-form-urlencoded_ encoding, or you would use _application/json_ encoding with _file_url_ in the _files_ parameter.

### Accepted file types

The API supports submitting files in the following formats:

- .zip, .pdf, .xps, .tif, .tiff, .jpg, .jpeg, .png, .gif

Note that if the ZIP file is password-protected or the images are encrypted, an error will appear.

Support for other file types is possible but with limitations. For more information, contact your Hyperscience representative.

### Parameters

The only required parameter for processing files through the API is:

- _file_ for _multipart/form-data_ and _application/x-www-form-urlencoded_ encoding.
- _files_ for _application/json_ encoding.

It is also possible to add optional parameters to your submissions for your convenience. To learn more about parameters, see our [API documentation](https://docs.hyperscience.ai/#submission-creation).

## JSON outputs and objects

All API responses are in JSON format. Our main API data structure is an _object_. Within its structure, each of the objects contain arrays and other objects.

You can use the JSON outputs from each of the objects to:

- Integrate with connectors such as Bizagi and UiPath. Bizagi is only available for on-prem / private cloud instances.

- To learn more about these integrations, see [Bizagi](https://help.hyperscience.ai/v41/docs/bizagi) and [UiPath Notifier](https://help.hyperscience.ai/v41/docs/uipath-notifier).
- Connect to other systems downstream.

## OpenAPI specifications

OpenAPI specifications (f.k.a. Swagger specifications) provide standardized ways to interact with REST APIs and provide information about them. These standardizations make it easier for developers to create integrations with APIs in the languages of their choosing. To learn more about OpenAPI specifications, see Swagger's [OpenAPI Specification](https://swagger.io/specification/) page.

Hyperscience has built OpenAPI specifications for the following endpoints:

- Submissions
- Create Submissions

You can download these specifications from our [API documentation](https://docs.hyperscience.ai/#openapi-schema).

For more information on our OpenAPI specifications, see MuleSoft's [Anypoint Exchange](https://www.mulesoft.com/exchange/com.mulesoft.muleesb.modules/hyperscience-open-api/minor/1.0/pages/home/).