> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.instabase.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server. # Run apps endpoint (Deprecated) > API reference for running apps. > **Warning** > > The [runs](/api-sdk/api-reference/runs/) endpoints offer a simpler and more robust way to run apps and manage app runs. This page remains temporarily available for reference but is not actively maintained. 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`. ```python import requests, base64 API_ROOT = 'https://aihub.instabase.com/api/v2/zero-shot-idp/projects/app' APP_ID = '' # Enter your app id API_KEY = '' # Enter your API Key ``` > **Note** > > Organization members must include [an `IB-Context` header](/api-sdk/authorization#ib-context-header) in all Run apps API requests for the call to complete in the organization context. This context is validated against any specified input directory or output workspace value. For example, if the `IB-Context` is a user's community account but the API request lists a shared workspace in an organization as the output workspace, the call fails. The same applies if the `IB-Context` header is omitted, in which case the default community context is used. ## 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](/api-sdk/api-reference/batches/) 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 a community or organization account. * **Community accounts:** `//my-repo/fs///` * **Organization accounts:** `///fs///` | Value | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ` ` | Enter your user ID. You can find this on the **Settings** > **APIs** page, under **User ID**. | | `` | Enter your organization ID. You can find this on the **Settings** > **APIs** page, under **Organization ID**. | | ` ` | This value reflects the workspace name (shared workspaces) or your user ID (personal workspaces). You can find this value by selecting the workspace in Workspaces, then looking at the `workspace` query string in the URL. For example: - `https://aihub.instabase.com/workspaces/create?workspace=*New_Workspace*` - `https://aihub.instabase.com/workspaces/create?workspace=*john.doe_gmail.com*` | | `` | Use the drive's display name. You can see a drive's display name by opening the **Data Sources** panel in a workspace where the drive is connected. For example, the Instabase Drive's display name is `Instabase Drive`. | | `` | Use the exact name of the folder, as displayed in the filesystem. | ## Running apps by app ID Run an app by its app ID through sending a `POST` request to `API_ROOT//run` with the request body encoded as JSON. You can find the app ID in the app's AI Hub URL. For example, https\://aihub.instabase.com/hub/apps/**528c36e8-ac5b-490d-a41b-7eec9c404b87**. | Method | Syntax | | ------ | ------------------------------ | | POST | `API_ROOT//run` | ### Request parameters Parameters are required unless marked as optional. | Parameter | Type | Description | Values | | --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `batch_id` | string | Optional, preferred. The batch ID of the batch you created. All files uploaded to the batch are used as input for the app run. | A valid integer batch ID. | | `input_dir` | string | Optional, supported. The path of the input folder, in a connected drive or Instabase Drive. | A complete path to the input folder. See [using file paths as input](#using-file-paths-as-app-input). | | `output_workspace` | string | Optional. The workspace in which to run the app. The output is saved to the [default drive](/admin/data-sources/default-drives) of the specified workspace. If not defined, the default is: - **Community accounts**: Runs in and saves to the personal workspace's Instabase Drive (`/my-repo/Instabase Drive`). - **Organization accounts**: Runs in and saves to the organization's default drive (`//`). | A valid name of a workspace in the specified community or organization context, such as `shared-workspace-accounting`. | | `output_dir` | string | Optional. Defines a specific location for the output to be saved in a connected drive or Instabase drive. If defined, overrides the `output_workspace` value. | A complete path to the output folder. | | `settings` | dict | Optional. Advanced settings for your app run. | | | `settings/webhook_config` | dict | Optional. Configure the webhook URL that's called on app run completion. See [Webhook Parameters](#webhook-parameters) for more details | | | `settings/webhook_config/url` | string | Optional. Webhook URL to which a HTTP request is sent when the run is completed. | | | `settings/webhook_config/headers` | dict | Optional. Configure the headers that are sent alongside HTTP request. Format is `{ "": ""}` | | ### Response schema | Key | Type | Description | Value | | -------- | ------ | ------------------------------------ | ----- | | `job_id` | string | The id of the job that was triggered | | ### Examples #### Request Example (Python): ```python run_app_payload = { 'batch_id': 'BATCH-ID', # optional: 'output_dir': '', if not specified, assumes it is your input_dir/out } API_HEADERS = { 'Authorization': f'Bearer {API_KEY}', 'IB-Context': '' } 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: ```javascript 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. | Method | Syntax | | ------ | -------------- | | POST | `API_ROOT/run` | ### Request parameters Parameters are required unless marked as optional. | Parameter | Type | Description | Values | | --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `batch_id` | string | Optional, preferred. The batch ID of the batch you created. All files uploaded to the batch are used as input for the app run. | A valid integer batch ID. | | `input_dir` | string | Optional, supported. The path of the input folder, in a connected drive or Instabase Drive. | A complete path to the input folder. See [using file paths as input](#using-file-paths-as-app-input). | | `name` | string | The name of the AI Hub app through which you want to process the files. | A valid name of a prebuilt or custom AI Hub app. | | `output_workspace` | string | Optional. The workspace in which to run the app. The output is saved to the [default drive](/admin/data-sources/default-drives) of the specified workspace. If not defined, the default is: - **Community accounts**: Runs in and saves to the personal workspace's Instabase Drive (`/my-repo/Instabase Drive`). - **Organization accounts**: Runs in and saves to the organization's default drive (`//`). | A valid name of a workspace in the specified community or organization context, such as `shared-workspace-accounting`. | | `output_dir` | string | Optional. Defines a specific location for the output to be saved in a connected drive or Instabase drive. If defined, overrides the `output_workspace` value. | A complete path to the output folder. | | `owner` | string | Optional. The account that generated the app. If not specified, defaults to your AI Hub username. | For custom AI Hub apps belonging to you, don't specify a value. For public AI Hub apps published by Instabase, specify `instabase`. | | `settings` | dict | Optional. Advanced settings for your app run. | | | `settings/webhook_config` | dict | Optional. Configure a webhook url that is called on app run completion. See [Webhook parameters](#webhook-parameters) for more details | | | `settings/webhook_config/url` | string | Optional. Webhook URL to which a HTTP request is sent when the run is completed. | | | `settings/webhook_config/headers` | dict | Optional. Configure headers that is sent alongside HTTP request. Format is `{ "": ""}` | | ### Response schema | Key | Type | Description | Value | | -------- | ------ | ------------------------------------ | ----- | | `job_id` | string | The id of the job that was triggered | | ### Examples #### Request Example (Python): ```python run_app_payload = { 'batch_id': 'BATCH-ID', 'name': APP_NAME # optional: 'owner': '', if not specified, assumes it is your username } API_HEADERS = { 'Authorization': f'Bearer {API_KEY}', 'IB-Context': '' } 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: ```javascript 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//run/sync` with the request body encoded as JSON. > **Note** > > When running apps in memory, neither the input file contents nor the app run's results are saved. The app run's results can only be retrieved through the API response. | Method | Syntax | | ------ | ----------------------------------- | | POST | `API_ROOT//run/sync` | ### Request parameters Parameters are required unless marked as optional. | Parameter | Type | Description | Values | | -------------- | --------------- | ------------------------------------- | ---------------------------------------------------------------------------------- | | `files` | list | A list of files to process. | Each file is represented by a `file_name` : `file_content` dictionary (see below). | | `file_name` | string | The name of the file to be processed. | File name must be a string. | | `file_content` | Base64 encoding | The content of a file to process. | Base64 representation of the content of a file. | ### 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): ```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': '' } 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: ```javascript 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: ```shell # body { "status": , "msg": , "job_id": , "binary_path": , "input_dir": , "output": } ``` 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.