APIs
Instabase APIs share common conventions, authorization, and responses for errors and successful executions.
Looking for AI Hub APIs? Instabase AI Hub uses large language models to help you understand and get information from any kind of document. See our AI Hub API documentation.
- 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.
-
Click on your user icon at the top right of your Instabase homepage.
-
Click View profile.
-
Click OAuth management.
-
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)
v2 APIs use the following classes for non-error responses:
-
Informational responses (100–199)
-
Successful responses (200–299)
-
Redirects (300–399)
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 tohttps://www.instabase.com/api/v1
For an on-premises installation of Instabase, your
URL_BASE
will be different. -
api_root
refers tohttps://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"
.