Run apps endpoint

In this document, API_ROOT defines where to route API requests for file operations, and its value is aihub.instabase.com/api/v2/zero-shot-idp/projects/app.

import requests, base64

API_ROOT = 'https://aihub.instabase.com/api/v2/zero-shot-idp/projects/app'
APP_ID = '<EXAMPLE-APP-ID>' # Enter your app id
API_KEY = '<API-KEY>' # Enter your API Key

Using file paths as app input

When running apps by name or by app ID, there are two methods to specify the app’s input:

• Preferred: Use the batch_id parameter to process all files in the specified batch. See the Batches endpoint for more information.

• Supported: Use the input_dir parameter to process all files in a specific input folder in the filesystem. This requires specifying the file path to a location in a connected drive.

The format of the file path varies if you have community or commercial account.

• Community accounts: /<USER-ID>/my-repo/fs/<DRIVE-NAME>/<INPUT-FOLDER>/

• Commercial accounts: /<ORGANIZATION-ID>/<WORKSPACE>/fs/<DRIVE-NAME>/<INPUT-FOLDER>/

  Tip

  You can find your user ID and organization ID on Settings > APIs. All workspaces that you can access and their connected drives are listed in the My Hub tab.

See the following table for how to define <DRIVE-NAME>. Amazon S3 buckets and Azure Blob storage are only supported in commercial organizations.

Running apps by app ID

Run an app by its app ID through sending a POST request to API_ROOT/<string:app_id>/run with the request body encoded as JSON.

Request parameters

Parameters are required unless marked as optional.

Response schema

Examples

Request

Example (Python):

run_app_payload = {
      'batch_id': 'BATCH-ID',
    # optional: 'output_dir': '<IB-OUTPUT-FILE-DIR>', if not specified, assumes it is your input_dir/out
}

API_HEADERS = {
  'Authorization': f'Bearer {API_KEY}',
  'IB-Context': '<USER-ID or ORGANIZATION-ID>'
}

url = f'{API_ROOT}/{APP_ID}/run'
run_app_resp = requests.post(url, headers=API_HEADERS, data=run_app_payload)

job_id = run_app_resp.json().get('job_id')
print(f'Job Running: {job_id}')

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  job_id: '53275652-abc8-479e-89f2-ccb12af401a0'  # Example Job ID
}

Running apps by name

Run an app by its name through sending a POST request to API_ROOT/run with the request body encoded as JSON.

Request parameters

Parameters are required unless marked as optional.

Response schema

Examples

Request

Example (Python):

run_app_payload = {
      'batch_id': 'BATCH-ID',
      'name': APP_NAME
	# optional: 'owner': '<OWNER-USERNAME>', if not specified, assumes it is your username
}

API_HEADERS = {
  'Authorization': f'Bearer {API_KEY}',
  'IB-Context': '<USER-ID or ORGANIZATION-ID>'
}

url = f'{API_ROOT}/run'
run_app_resp = requests.post(url, headers=API_HEADERS, data=run_app_payload)

job_id = run_app_resp.json().get('job_id')
print(f'Job Running: {job_id}')

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  job_id: '53275652-abc8-479e-89f2-ccb12af401a0'  # Example Job ID
}

Running apps in memory

Apps can also be run in memory by sending a POST request to API_ROOT/<string:app_id>/run/sync with the request body encoded as JSON.

Request parameters

Parameters are required unless marked as optional.

Response schema

The response contains all extracted fields. Extracted fields are dependent on how the app is built. If a field isn’t found, an empty string '' is returned instead

Examples

Request

Example (Python):

encoded_string = base64.b64encode(open('file_name.jpg', 'rb').read()).decode('utf-8')
url = f'{API_ROOT}/{APP_ID}/run/sync'

run_app_payload = {
    'files': [{
    'file_name': 'chips.jpg',
    'file_content': encoded_string,
  }]
}

API_HEADERS = {
  'Authorization': f'Bearer {API_KEY}',
  'IB-Context': '<USER-ID or ORGANIZATION-ID>'
}

run_app_resp = requests.post(url, data=run_app_payload, headers=API_HEADERS)
print(f'Job Results: {run_app_resp.json()}')

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  'response': {
    'records': [
      {
        'output_file_path': 'IBMSG_FILE_PATH',
        'results': [
          {
            'key': 'EXTRACTION_FIELD',
            'value': 'EXTRACTION_VALUE',
            'field_type': 'STRING',
            'model_confidence': 0.9
          }
        ],
        'record_index': 0,
        'file_name': 'PATH_TO_chips.jpg',
        'document_path': 'PATH_TO_chips.jpg',
        'flow_index': 0,
        'file_index': 0,
        'is_manually_reviewed': false,
        'current_step_index': 2,
        'is_human_corrected': false,
        'absolute_ibocr_path': 'OCR_PATH',
        'was_classified': false,
        'is_finalized': true
      }
    ],
    'binary_path': 'IBFLOWBIN_PATH',
    'job_id': '53275652-abc8-479e-89f2-ccb12af401a0',
    'num_tasks': 1,
    'has_more_tasks': false,
    'next_offset': 1,
    'can_resume': false,
    'on_last_resumable_step': false
  }
}

Webhook parameters

You can use the webhook_config setting to ensure your application is notified when an app run completes. Instabase POSTs JSON-encoded data of the format below to the webhook endpoint:

# body
{
"status": <string>,
"msg": <string>,
"job_id": <string>,
"binary_path": <string>,
"input_dir": <string>,
"output": <string>
}

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 job.

• binary_path: The path reference to flow binary file used to execute the app.

• 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 Instabase that you did not receive the event.

If Instabase does not receive a 2xx HTTP status code, the notification attempt is repeated up to 7 times.