Marketplace and Solution API

Table of Contents

URL_BASE refers to the root URL of your Instabase instance, such as https://www.instabase.com. API_ROOT is URL_BASE appended by /api/v1.

import json, requests
url_base = "https://www.instabase.com"
api_root = url_base + '/api/v1'

Package a solution

Send a POST request to API_ROOT/solution/create with the request body encoded as JSON:

POST API_ROOT/solution/create

# body
{
  "content_folder": <string>,
  "output_folder": <string>
}

Request

The body of the request must be a JSON object with the following fields:

content_folder: The path to the folder that contains the solution content.
output_folder: The path to the folder that the created solution will be in.

Response

Response:

{
    "status": "OK"
}

The response body is a JSON object with the following fields:

status: OK or ERROR
msg: The error message. Only exists if status is ERROR.

Publish a solution to Marketplace

Send a POST request to API_ROOT/marketplace/publish with the request body encoded as JSON:

POST API_ROOT/marketplace/publish

# body
{
  "ibsolution_path": <string>
}

Request

The body of the request must be a JSON object with the following fields:

ibsolution_path: The file path to the ibsolution file.

Response

Response:

{
    "status": "OK"
}

The response body is a JSON object with the following fields:

status: OK or ERROR
msg: The error message. Only exists if status is ERROR.

Install a Marketplace solution

Send a POST request to API_ROOT/marketplace/install with the request body encoded as JSON:

POST API_ROOT/marketplace/install

# body
{
  "name": <string>,
  "version": <string>
}

Request

The body of the request must be a JSON object with the following fields:

name: The name of the solution.
version: The version of the solution.

Response

Response:

{
    "status": "OK"
}

The response body is a JSON object with the following fields:

status: OK or ERROR
msg: The error message. Only exists if status is ERROR.

Run a solution

Request

Run a solution by sending a POST request to API_ROOT/solution/run with the request body encoded as JSON. The user can provide the solution name and version to run an installed Marketplace solution, or provide the solution filepath to run an unpublished solution.

POST API_ROOT/solution/run

# body
{
  "name": "w2", # running an installed Marketplace solution
  "version": "1.0.0",
  "input_folder": "path/to/input/folder",
  "settings": {}
}

#RESPONSE
{
  "status": "OK",
  "solution": {
      "name": "w2",
      "version": "1.0.0",
  },   
  "job_id": "xxxxxxxxxx"
}

The body of the request must be a JSON object with the following fields:

input_folder: The folder that contains the data to run the solution on.
settings: (optional) An object with additional settings. See Run a Flow Binary API for supported settings. To run an installed Marketplace solution (see example above):
name: The name of the solution.
version: The version of the solution. Or, to run an unpublished solution (see example below):
solution_path: The path to the .ibsolution file

Example (Python):

url = url_base + 'solution/run'

args = {
  'input_folder': '/jaydoe/my_repo/fs/Instabase Drive/flow_proj/data/input',
  'solution_path': '/jaydoe/my_repo/fs/Instabase Drive/flow_proj/my_solution.ibsolution', # running an uninstalled solution
  'settings': {
    'delete_out_dir': False,
    'output_has_run_id': True,
    'notification_emails': ["me@domain.com"],
  },
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(uri, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The HTTP call returns immediately while the binary execution proceeds asynchronously in the background. If successful, the response contains a job_id field that you can use to check the status of your execution.

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "data": {
    "job_id": <string>,
    "output_folder": <string>
  }
}

The response body is a JSON object with the following fields:

status: "OK"
data: A JSON object with the following fields:
- job_id: A unique identifier for the job.
- output_folder: The full path to the root output folder.

Run a solution in sync mode

Method	Syntax
POST	`API_ROOT/solution/run_sync`

Description

This API is used to synchronously run a solution and return the output in the specified format. It accepts one or more files as input, runs the solution, blocks until it finishes, and then returns the results.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`name`	string	Name of a published solution. Must be paired with `version`. Required unless you specify `solution_path`.
`version`	string	The version of a published solution. Must be paired with `name`. Required unless you specify `solution_path`.
`solution_path`	string	Path to an unpublished solution binary `.ibsolution` file. Required unless you specify a (`name`, `version`) pair.
`files`	array	An array of dictionaries where each dictionary defines an input file.
`files/file_name`	string	The name of the input file.
`files/file_content`	string	Base64-encoded file data.
`output_dir`	string	Optional. The path to the directory to extract the .ibsolution contents.
`options`	dict	Optional. Dictionary of options.
`options/result_format`	string	Optional. The output structure.	`json` (default), `csv`
`write_to_cache`	string	Optional. Whether to write the output to the cache.	`true` (default), `false`
`repo_name`	string	Optional. The name of the repository.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`records`	An array of records.
`records/output_file_path`	Path to the `.ibdoc` output file.
`records/results`	An array of key-value pairs for each field specified in the Refiner program.
`records/file_name`	The name of the input file.
`records/file_index`	The index of the input file.
`records/record_index`	The index of the output record.
`binary_path`	The path to the Flow binary `.iflowbin` file.
`job_id`	The Job ID for the Flow run.

Examples

Request

import base64

encoded_string = base64.b64encode(open("test.pdf", "rb").read()).decode('utf-8')

url = url_base + '/api/v1/solution/run_sync'

api_args = {
  'name' :  "Demo Solution",
  'version' : "1.0.0",
  'files': [{
    'file_name': "test.pdf",
    'file_content': encoded_string,
  }]
}
json_data = json.dumps(api_args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers, verify=False)
resp_data = json.loads(r.content)

Response

{
  "records": [
    {
      "results": [
        {
          "key": "first_name",
          "value": "Coder"
        },
        {
          "key": "last_name",
          "value": "Maloder"
        }
      ],
      "file_name": "test.pdf",
      "file_index": 0,
      "record_index": 0
    }
  ],
  "binary_path": "jaydoe/my_repo/fs/InstabaseDrive/build/bin/workflow/my_flow.ibflowbin",
  "job_id": "5eb7df69-7506-41b3-bd3a-eb69d8b8a36d"
}

Get Solution Execution Status

Use this API to get the execution status.

Request

Send a GET request to API_ROOT/jobs/status?job_id={job_id}.

GET API_ROOT/jobs/status?job_id={job_id}

Response

The response body is a JSON object reporting the status of the execution:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "state": <string: one of a number of states>,
  "job_id": <string>,
  "cur_status": <string>
}

status: "OK" or "ERROR"
state: Possible values: "PENDING" or "DONE"
job_id: The unique identifier for the job.

Warning

Use the cur_status field only for informational and debugging purposes. Some of the sub-fields, such as total and index, can return erratic values. Verify the validity of these status fields before using them.

cur_status: A stringified JSON object with the following fields:
- total: The total number of stages in the job.
- index: The index of the currently processing stage.
- curMsg: A human-readable status message.

Example response:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "state": "PENDING",
  "job_id": "this-execution-job-id",
  "cur_status": "{\"index\": 3, \"total\": 3, \"curMsg\": \"Completed 3/3 files\"}"
}