Deployed Solutions API

The Deployed Solutions API lets you add, manage, and run solutions that you indicate are deployed, so you can monitor their automation metrics in the Solution Dashboard.

To authorize your request, the Deployed Solutions API requires an Authorization header with the value Bearer XYZ, where XYZ is your access token. See API authorization.

In this document, URL_BASE refers to the root URL of your Instabase instance, such as https://www.instabase.com.

import requests

url_base = "https://www.instabase.com"
deployed_solutions_api_url = f'{url_base}/api/v2/solutions/deployed'

Deploy a solution

Method Syntax
POST URL_BASE/api/v2/solutions/deployed

Description

Use this API to deploy an .ibsolution file to production.

Request parameters

Parameter Type Description Values
solution_path string The path to the solution to deploy. Path of a valid .ibsolution file.

To package a flow binary into an .ibsolution, use the Create Solution API and the solution packaging guide. This process differs from deploying via the UI, where the .ibsolution file is automatically created from the flow binary before deploying.

The key file to package in with your Flow binary is the package.json file. For Deployed Solutions specifically, this file must include name, version, owner, and solution_type. See the example package.json file below.

{
  "name": "My Solution Name",
  "version": "0.0.1",
  "short_description": "short solution description",
  "long_description": "this is a much longer solution description",
  "owner": "thisismyusername",
  "solution_type": "ibflowbin",
  "visibility": "PRIVATE"
}

Response schema

Key Description
job_id The unique identifier for the deploy job.

You can check the status of the deploy job with the Job API. The type of the job is async.

Get solutions

Method Syntax
GET URL_BASE/api/v2/solutions/deployed

Description

Get a list of deployed solutions.

Request parameters

Parameters are required unless marked as optional.

Parameter Type Description Values
limit integer Optional. The maximum number of deployed solutions to return. Solutions limit per response (default 20).
offset integer Optional. Initial deployed solution start index. Used for pagination with limit. Starting index (default 0).
state string Optional. The state of deployed solutions to return. ACTIVE, INACTIVE
name string Optional. The name of deployed solutions to return. Any string. Solutions is returned only if there is a matching solution name.
author string Optional. The author of deployed solutions to return. A valid username.
owner string Optional. The owner of deployed solutions to return. A valid username for private solutions or IB_DEPLOYED for public solutions.
visibility string Optional. The visibility of deployed solutions to return. PUBLIC, PRIVATE, PENDING_REVIEW

Response schema

Key Type Description Value
has_more List [bool] Whether there are more solutions to list on a later page. [true], [false]
next_offset List [int] The value to use for the offset of a future request to get the next page. [-1] if has_more is false.
solutions list The list of returned solutions.
solutions/id string The unique ID of the solution. A valid UUID.
solutions/name string The name of the solution.
solutions/version string The version of the solution .
solutions/owner string The owner of the solution. A valid username or IB_DEPLOYED.
solutions/createdAtMs int When the solution was created. Unix timestamp in epoch milliseconds.
solutions/updatedAtMs int When the solution was last updated. Unix timestamp in epoch milliseconds.
solutions/summary str Short description of the solution.
solutions/state str Current state of the solution. ACTIVE, INACTIVE
solutions/author str The username of the user who published the solution.
solutions/solution_path str The path to the solution files.

For non-admin users, this API returns public solutions and private solutions owned only by the current user.

Example

Request
import json, requests, time

solution_name = '{YOUR-SOLUTION-NAME}'
url = f'{url_base}/api/v2/solutions/deployed?state=ACTIVE&name={solution_name}'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "has_more": [false],
  "next_offset": [-1],
  "solutions": [
    {
      "id": "example-uuid-1",
      "name": "My Solution",
      "version": "0.0.1",
      "owner": "example-owner",
      "createdAtMs": 12345,
      "updatedAtMs": 12345,
      "summary": "A short description",
      "state": "ACTIVE",
      "author": "user1"
    },
    {
      "id": "example-uuid-2",
      "name": "My Solution",
      "version": "0.0.2",
      "owner": "example-owner",
      "createdAtMs": 67890,
      "updatedAtMs": 67890,
      "summary": "A short description",
      "state": "ACTIVE",
      "author": "user2"
    }
  ]
}

Get single solution API

Method Syntax
GET URL_BASE/api/v2/solutions/deployed/<solution-uuid>

Description

Get more detailed information about a single solution. This API takes no parameters.

Response schema

Key Type Description Value
solution dict The returned solution.
solution/id string The unique ID of the solution. A valid UUID.
solution/name string The name of the solution.
solution/version string The version of the solution.
solution/owner string The owner of the solution. A valid username or IB_DEPLOYED.
solution/createdAtMs int When the solution was created. Unix timestamp in epoch milliseconds.
solution/updatedAtMs int When the solution was last updated. Unix timestamp in epoch milliseconds.
solution/summary str Short description of the solution.
solution/description str Long description of the solution.
solution/state str Current state of the solution. ACTIVE, INACTIVE
solution/author str The username of the user who published the solution.
solution/metadata str Serialized JSON metadata for the solution.
solution/solution_path str The path to the solution files.

Example

Request
import json, requests, time

solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "solution": {
      "id": "example-uuid-1",
      "name": "My Solution",
      "version": "0.0.1",
      "owner": "example-owner",
      "createdAtMs": 12345,
      "updatedAtMs": 12345,
      "summary": "A short description",
      "description": "A longer description",
      "state": "ACTIVE",
      "author": "user1",
      "metadata" "{\"authors\": [\"user1\"]}"
    },
}

Run a solution

Method Syntax
POST URL_BASE/api/v2/solutions/deployed/<solution-uuid>/run

Description

This request runs the specified deployed solution.

Request parameters

Parameter Type Description Values
input_dir string The path to the input folder. Path of a valid directory.
output_dir string Optional. The path to the output folder. Path of a valid directory. If left empty, an output directory is created within the input folder.
job_id string Optional. The job ID for this job. If omitted, a job ID is generated automatically. The job ID must be no more than 50 characters long.
settings dict Settings for the run. Format is identical to the settings for running a flow binary.

Response schema

Key Type Description
job_id string The id of the triggered job.

Example

Request
import json, requests, time

solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}/run'

headers = {
  'Authorization': f'Bearer {token}'
}

args = {
  'input_dir': "jaydoe/my_repo/fs/Instabase Drive/proj/data/input",
  'settings': {
    'delete_out_dir': False,
    'output_has_run_id': True,
    'notification_emails': ["me@domain.com"],
  },
}
json_data = json.dumps(args)

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "job_id": "example-job-id"
}

Run a solution by name/version

Method Syntax
POST URL_BASE/api/v2/solutions/deployed/run

Description

This request runs the specified deployed solution.

Request parameters

Parameter Type Description Values
name string The name of the solution to run. Valid solution name.
version string Optional. The version of the solution to run. Valid solution version. If not specified, the request defaults to running the most recently created solution.
owner string Optional. The owner of the solution to run. A valid username or IB_DEPLOYED. If not specified, the request defaults to IB_DEPLOYED.
input_dir string The path to the input folder. Path of a valid directory.
output_dir string Optional. The path to the output folder. Path of a valid directory. If not specified, an output directory is created within the input folder.
job_id string Optional. The job ID for this job, not exceeding 50 characters. If not specified, a job ID is generated automatically.
settings dict Settings for the run. Format is identical to the settings for running a flow binary.

Response schema

Key Type Description
job_id string The id of the triggered job.

Example

Request
import json, requests, time

solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
solution_name = '{YOUR-SOLUTION-NAME}'
url = f'{url_base}/api/v2/solutions/deployed/run'

headers = {
  'Authorization': f'Bearer {token}'
}

args = {
  'name': solution_name,
  'input_dir': "jaydoe/my_repo/fs/Instabase Drive/proj/data/input",
  'settings': {
    'delete_out_dir': False,
    'output_has_run_id': True,
    'notification_emails': ["me@domain.com"],
  },
}
json_data = json.dumps(args)

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "job_id": "example-job-id"
}

Delete a solution

Method Syntax
DELETE URL_BASE/api/v2/solutions/deployed/<solution-uuid>

Description

This request deletes the specified deployed solution via an asynchronous job. This API takes no parameters.

Response schema

Key Type Description
job_id string The unique identifier for the deletion job.

You can check the status of the deletion job with the Status API. The type of the job is async.

Example

Request
import json, requests, time

solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.delete(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "job_id": "example-job-id"
}

Update a solution’s attributes

Method Syntax
PATCH URL_BASE/api/v2/solutions/deployed/<solution-uuid>

Description

This request updates the attributes of the specified deployed solution.

Request parameters

Parameter Type Description Values
visibility string Optional. The visibility to set the solution to. PUBLIC, PRIVATE, PENDING_REVIEW
state string Optional. The state to set the solution to. ACTIVE, INACTIVE

Response schema

Key Type Description
solution dict The updated solution.
solution/id string The unique ID of the solution.
solution/name string The name of the solution.
solution/version string The version of the solution.
solution/owner string The owner of the solution.
solution/createdAtMs int When the solution was created.
solution/updatedAtMs int When the solution was last updated.
solution/summary str Short description of the solution.
solution/description str Long description of the solution.
solution/state str Current state of the solution.
solution/author str The username of the user who published the solution.
solution/metadata str Serialized JSON metadata for the solution.

Example

Request
import json, requests, time

solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
visibility = 'PUBLIC'  # or 'PRIVATE'
state = 'ACTIVE'  # or 'INACTIVE'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}?visibility={visibility}&state={state}'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.patch(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
  "solution": {
      "id": "example-uuid-1",
      "name": "My Solution",
      "version": "0.0.1",
      "owner": "example-owner",
      "createdAtMs": 12345,
      "updatedAtMs": 12345,
      "summary": "A short description",
      "description": "A longer description",
      "state": "ACTIVE",
      "author": "user1",
      "metadata" "{\"authors\": [\"user1\"]}"
    },
}

Get jobs for a single solution API

Method Syntax
GET URL_BASE/api/v2/solutions/deployed/<solution-uuid>/jobs

Description

Get information about all runs of a single solution.

Request parameters

Parameter Type Description Values
user string Optional. Returns only jobs started by this user. This API can accept multiple user parameters. Valid Instabase usernames.
job_id string Optional. Returns only job with the provided IDs. This API can accept multiple job_id parameters. Valid job IDs.
state string Optional. Returns only jobs in the provided states. This API can accept multiple state parameters. Valid job states.
output_repo string Optional. Returns only jobs outputting to the provided spaces. This API can accept multiple output_repo parameters. Spaces in the format <space-owner>/<space-name>. If not provided, defaults to all spaces owned by the current user. If the current user owns more than 900 spaces, this parameter is required.
limit int Optional. The maximum number of jobs to return. Jobs limit per response (default 20).
offset int Optional. Initial job start index. Used for pagination with limit. Starting index (default 0).
sort_by string Optional. Sorts the jobs by the specified attribute. startTimeNs, name, version, username, timeTakenNs, state (default startTimeNs).
order string Optional. Controls the sort order. ASCENDING, DESCENDING (default DESCENDING).

Response schema

Key Type Description Value
jobs list A list of jobs.
jobs/id string The unique ID of the job. A valid UUID.
jobs/accountId string The ID of the user who ran the job. A valid user private ID.
jobs/jobType string The type of the job. FLOW
jobs/startTimeNs string The start time of the job. An epoch-nanoseconds timestamp.
jobs/modifiedTimeNs string When the job was last modified. An epoch-nanoseconds timestamp.
jobs/completionTimeNs string When the job completed. An epoch-nanoseconds timestamp.
jobs/state string The current state of the job. RUNNING, COMPLETE, FAILED, CANCELLED, STOPPED_AT_CHECKPOINT
jobs/metadata string JSON metadata about this job. Serialized JSON metadata.
jobs/lastStartTimeNs string When the job was last started or resumed. An epoch-nanoseconds timestamp.
jobs/timeTakenNs string The amount of time that the flow spent running. An epoch-nanoseconds timestamp.
jobs/timeTakenNs string A message with details on Flow execution status.
jobs/deployedSolutionId string The ID of the solution corresponding to the job. A valid solution UUID.
jobs/outputFolder string The output folder of the job.

Example

Request
import json, requests, time

solution_name = '{YOUR-SOLUTION-NAME}'
solution_uuid = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}/jobs'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
    "jobs": [
        {
            "id": "example-job-id",
            "accountId": "example-account-id",
            "jobType": "FLOW",
            "startTimeNs": "1683159463986732303",
            "modifiedTimeNs": "1683159471011951164",
            "completionTimeNs": "1683159471011951164",
            "state": "COMPLETE",
            "lastStartTimeNs": "1683159463986732303",
            "timeTakenNs": "7025218861",
            "message": "Completed single_flow",
            "deployedSolutionId": "example-solution-id",
            "outputFolder": "path/to/output/folder"
        }
    ]
}

Get jobs for multiple solutions API

Method Syntax
GET URL_BASE/api/v2/solutions/deployed/jobs

Description

Get information about runs for multiple solutions.

Request parameters

Parameter Type Description Values
solution_id string Optional. Returns only jobs run by the specified deployed solutions. This API can accept multiple solution_id parameters. Valid solution UUIDs.
user string Optional. Returns only jobs started by this user. This API can accept multiple user parameters. Valid Instabase usernames.
job_id string Optional. Returns only jobs with the provided IDs. This API can accept multiple job_id parameters. Valid job IDs.
state string Optional. Returns only jobs in the provided states. This API can accept multiple state parameters. Valid job states.
owner string Optional. Returns only jobs run by solutions with the provided owners. This API can accept multiple owner parameters. Valid usernames.
name string Optional. Returns only jobs run by solutions with the provided names. This API can accept multiple name parameters. Valid solution names.
output_repo string Optional. Returns only jobs outputting to the provided spaces. This API can accept multiple output_repo parameters. Spaces in the format <space-owner>/<space-name>. If not provided, defaults to all spaces owned by the current user. If the current user owns more than 900 spaces, this parameter is required.
limit int Optional. The maximum number of jobs to return. Jobs limit per response (default 20).
offset int Optional. Initial job start index. Used for pagination with limit. Starting index (default 0).
sort_by string Optional. Sorts the jobs by the specified attribute. startTimeNs, name, version, username, timeTakenNs, state (default startTimeNs).
order string Optional. Controls the sort order. ASCENDING, DESCENDING (default DESCENDING).

Response schema

Key Type Description Value
jobs list A list of jobs.
jobs/id string The unique ID of the job. A valid UUID.
jobs/accountId string The ID of the user who ran the job. A valid user private ID.
jobs/jobType string The type of the job. FLOW
jobs/startTimeNs string The start time of the job. An epoch-nanoseconds timestamp.
jobs/modifiedTimeNs string When the job was last modified. An epoch-nanoseconds timestamp.
jobs/completionTimeNs string When the job completed. An epoch-nanoseconds timestamp.
jobs/state string The current state of the job. RUNNING, COMPLETE, FAILED, CANCELLED, STOPPED_AT_CHECKPOINT
jobs/metadata string JSON metadata about this job. Serialized JSON metadata.
jobs/lastStartTimeNs string When the job was last started or resumed. An epoch-nanoseconds timestamp.
jobs/timeTakenNs string The amount of time that the flow spent running. An epoch-nanoseconds timestamp.
jobs/timeTakenNs string A message with details on Flow execution status.
jobs/deployedSolutionId string The ID of the solution corresponding to the job. A valid solution UUID.
jobs/outputFolder string The output folder of the job.

Example

Request
import json, requests, time

solution_name = '{YOUR-SOLUTION-NAME}'
solution_uuid1 = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
solution_uuid12 = '{UUID-FROM-GET-SOLUTIONS-RESPONSE}'
url = f'{url_base}/api/v2/solutions/deployed/{solution_uuid}/jobs?solution_id={solution_uuid1}&solution_id={solution_uuid2}'

headers = {
  'Authorization': f'Bearer {token}'
}

r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)
Response
{
    "jobs": [
        {
            "id": "example-job-id",
            "accountId": "example-account-id",
            "jobType": "FLOW",
            "startTimeNs": "1683159463986732303",
            "modifiedTimeNs": "1683159471011951164",
            "completionTimeNs": "1683159471011951164",
            "state": "COMPLETE",
            "lastStartTimeNs": "1683159463986732303",
            "timeTakenNs": "7025218861",
            "message": "Completed single_flow",
            "deployedSolutionId": "example-solution-id",
            "outputFolder": "path/to/output/folder"
        }
    ]
}