App runs endpoint
The App runs endpoint lets you create an app run for an AI Hub app and returns a run ID. A deployment-specific version lets you run deployments, also returning a run ID. You can then use the run ID to check the status of an app or deployment run and, when complete, get the results.
- curl examples reference the
API_ROOT
,API_TOKEN
, andIB_CONTEXT
values as variables. If you don’t set up these variables, define them in the request. - For Python request examples, it’s assumed you installed the AI Hub SDK. Python examples include code initializing the API client, with values you must define.
- All endpoints support the IB-Context header. Organization members must set the
IB-Context
header as their organization ID to complete the request with their organization account. While optional, it’s a best practice to include theIB-Context
header in all requests. - All endpoints use the standard HTTP response status codes. For each endpoint, some common status codes are listed.
The AI Hub interface includes an API runner tool you can use to generate end-to-end code samples for running an app or deployment by API.
Run app
Description
Run an app by its name or app ID by sending a POST
request to API_ROOT/v2/apps/runs
. The input for the run is specified using a batch ID or an input file path. To run deployments by API, use the Run deployment endpoint.
IB-Context
header. For example, if the context is set to your community account, but the batch ID used as input for the run is stored in your organization, the call fails.https://aihub.instabase.com/hub/apps/**528c36e8-ac5b-490d-a41b-7eec9c404b87**
.Request body
Parameters are required unless marked as optional.
Response status
Response schema
The response body is a JSON object known as a run object. The run object provides information about the run and its progress, but not the run results. You can use the run’s id
to poll the Run status endpoint and the Run results endpoint.
Examples
Request (curl)
Request (Python SDK)
Response
Run deployment
Description
Run a deployment by sending a POST
request to API_ROOT/v2/aihub/deployments/<DEPLOYMENT-ID>/run
, using the request URL to specify the ID of the deployment. The input for the run is specified using a batch ID or an input file path.
IB-Context
header. For example, if the context is set to your community account, but the batch ID used as input for the run is stored in your organization, the call fails.https://aihub.instabase.com/deployments/**01902d6f-bb35-74cb-bd27-c09b38bbf20a**/runs
.Request body
Parameters are required unless marked as optional.
Response status
Response schema
The response body contains the run ID, that you can use to poll the Run status endpoint and the Run results endpoint.
Examples
Request (curl)
Response
Run status
Description
Get the status of a run by sending a GET
request to API_ROOT/v2/apps/runs/<RUN-ID>
. The run’s id
value is returned in the response of the initial run.
Request body
There is no request body. Use the request URL to specify a run id
.
Response status
Response schema
The response body is a JSON object known as a run object. The run object provides information about the run and its progress, but not the run results. You can use the run’s id
to poll the Run results endpoint.
Examples
Request (curl)
Request (Python SDK)
Response
Run results
Description
Get the results of a completed run by sending a GET
request to API_ROOT/v2/apps/runs/<RUN-ID>/results
. The run id
value is returned in the response of the initial run.
Query parameters
Response status
Response schema
The response body is a JSON object containing the results of the run.
For each extracted field, there is a <DOCUMENT-FIELD>
object structure:
Depending on the included query parameters, the following information can also be included in the results.
include_review_results
The following fields are included in the response when using the include_review_results
query parameter.
Run or document level:
Extracted field level:
include_confidence_scores
The following fields are included in the response when using the include_confidence_scores
query parameter.
Run or document level:
Extracted field level:
include_validation_results
The following fields are included in the response when using the include_validation_results
query parameter.
Run or document level:
Extracted field level:
include_source_info
The following fields are included in the response when using the include_source_info
query parameter.
Run or document level:
Extracted field level:
Examples
Simple request (curl)
A simple request returns extracted field names and values:
Simple request (Python SDK)
Response (simple request)
Request with query parameters (curl)
This request includes the include_confidence_scores
and include_source_info
query parameters. Confidence scores and source information (coordinates) are returned:
Request with query parameters (Python SDK)
Response (request with query parameters)
Runtime config
You can use the runtime_config
setting to specify key-value pairs to pass into the run at runtime. These values are propagated to downstream processes and can be referenced in validation functions.
For example, if your validation function’s behavior varies based on time of year, you might use runtime_config
to pass in the current date, for example:
Webhook parameters
You can use the webhook_config
setting to ensure your application is notified when a run completes. AI Hub POSTs JSON-encoded data of the format below to the webhook endpoint:
The response body contains the following fields:
-
status
:"OK"
|"ERROR"
-
msg
: (optional) Error message. Present only if status is ERROR. -
job_id
: A unique identifier for the run. -
input_dir
: Input directory. -
output
: The full path to the root output folder.
To acknowledge receipt of the event, your endpoint must return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, indicate to AI Hub that you did not receive the event.
If AI Hub does not receive a 2xx HTTP status code, the notification attempt is repeated up to 7 times.
Specifying file paths
When running an app using the v2/apps/runs
endpoint, there are two methods to specify the app’s input:
-
Batch: Create a batch using the Batches endpoint, upload files from your local filesystem, then use the
batch_id
parameter to specify the batch. All files in the batch are processed. -
Connected drive: Use the
input_dir
parameter to specify a file path to an input folder in a connected drive. All files in the input folder are processed.
When specifying a file path in a connected drive, the format varies if you have a community or organization account.
-
Community account:
/<USER-ID>/my-repo/fs/<DRIVE-NAME>/<FOLDER>/
-
Organization account:
/<ORGANIZATION-ID>/<WORKSPACE>/fs/<DRIVE-NAME>/<FOLDER>/