APIs

Instabase APIs share common conventions, authorization, and responses for errors and successful executions.

• Account API

  Create and deactivate users, return a list of all site admins, and set and remove site admins.

• Audit Log API

  Get audit log metadata and audit log results.

• Auth API

  Manage OAuth2 apps, Oath2 tokens, and SAML mappings.

• Automation Metrics API

  Query automation metrics to learn more about performance of deployed solutions.

• Database API

  Manage and query databases.

• Deployed Solutions API

  Add, manage, and run deployed solutions to view their automation metrics in the Deployed Solutions app.

• Deployment Manager API

  Perform deployment manager and cluster management operations.

• Diagnostics API

  Run diagnostic tests.

• Diffs API

  Run a diff operation.

• Filesystem API (deprecated)

  Perform file management operations.

• Filesystem API (V2)

  Perform file management operations.

• Flow API

  Run flows and flow steps.

• Flow Binary API

  Compile, run, change output schema at runtime, get status, get list, pause, resume, cancel, and retry flows.

• Flow Metrics API

  Get metrics describing how a flow performed over a period of time.

• Flow Pipeline API

  Retrieve flow pipelines information

• Flow Results API

  Parse a flow result.

• Flow Results Export API

  Start a job that exports flow results to an annotation set.

• Group API

  Manage groups.

• HTTP Endpoint API

  Manage and use custom HTTP endpoints.

• Installer API

  Install Instabase.

• Job API

  Read and modify the status of jobs.

• License Usage API

  Get usage information about licenses.

• Marketplace and Solution API

  Package, publish, install, run, and get execution status for Marketplace solutions.

• Metrics APIs

  Create and run metrics queries.

• Model API

  Get model job information.

• Model Service API

  Use and test models without the Intelligence Platform SDK.

• Mount API

  Mount drives and databases.

• Organization API

  Manage organization spaces.

• Repo API

  Create and manage Instabase repos.

• Scheduler API

  Schedule operations for flows, and create, list, delete, enable, and disable scheduled jobs.

• Search API

  Search documents and update document index attributes.

• Security API

  Manage multifactor authentication.

• Site API

  Get and set site configurations and site ACLs.

• Space API

  Get spaces metadata.

• Test Runner API (Deprecated)

  Run a regression test that leverages the previous output of flows that were successfully run and compares the ground truth to the test output.

• Test Runner API (V2)

  Run a regression test that leverages the previous output of flows that were successfully run and compares the ground truth to the test output.

• Upgrade API

  Upgrade Instabase.

API authorization

To get started, you must register an app to generate an authentication token. The token is used in all of your API requests for the registered app.

1. Click on your user icon at the top right of your Instabase homepage.

2. Click View profile.

3. Click OAuth management.

4. Click Create app.

Provide an app name, description, and a Redirect URI. You can provide any filler URL for Redirect URI. The option to create a token is toggled on by default, but you can create a new token later if needed.

The generated token authenticates your API calls from the app to all of the repositories you have access to.

Keep track of this authentication token. The token grants programmatic access to everything you can do using the Instabase web interface. You can create, change, and delete API tokens using the web interface.

All API requests must contain the header Authorization with the value Bearer XYZ, where XYZ is your access token.

API errors

Instabase has both v1 and v2 APIs. Version is indicated in the endpoint itself, such as the Filesystem v2 API (/api/v2/files) or the Job API (/api/v1/jobs/status). v1 and v2 APIs communicate errors differently.

v1 APIs

v1 API endpoints return a 200 status code and rely on the response message body to communicate errors. If an API execution error occurs, the response is in the form of:

HTTP STATUS CODE 200

# body
{
  "status": "ERROR",
  "msg": <string>
}

v2 APIs

v2 API endpoints use HTTP status codes to communicate errors. Responses are grouped in the following classes:

• Client errors (400–499)

  • A 401 code indicates an authorization error. This can be caused by an invalid API token or calling an API that requires permissions you don’t have.

  • A 403 code indicates a license error, such as being out of credits or calling an API for a product not included in your license.

• Server errors (500–599)

Responses in other forms are specified.

Output

Add ?pretty=true to the end of the query URL to return the JSON response in a more human readable, indented format. For example:

GET URL_BASE/<api>?pretty=true

Successful executions

If an API execution is successful, the response is in this form:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
}

Documentation conventions

In the API documentation:

• URL_BASE refers to https://www.instabase.com/api/v1

  For an on-premises installation of Instabase, your URL_BASE will be different.

• api_root refers to https://www.instabase.com/api/v1/<some_api_prefix>

  where: some_api_prefix is the API. For example, api_root = "https://www.instabase.com/api/v1/accounts".