Batches endpoint

The Batches endpoint lets you create and manipulate batches. A batch is a RESTful object that contains a user-defined list of files. A batch can be used as input for an AI Hub app, allowing for batch processing of all files you’ve added to the batch. Batches are useful for logically grouping files that you want to easily and repeatedly use as an app’s input.

In this document, URL_BASE refers to the root URL of your Instabase instance, such as aihub.instabase.com. API_ROOT defines where to route API requests for file operations, and its value is URL_BASE appended by /api/v2/batches.

import json, requests

url_base = "https://aihub.instabase.com"
api_root = url_base + '/api/v2/batches'

To make calls to AI Hub APIs, you must define your API token and send it with your requests. API_TOKEN in the following examples refers to your API token.

You can generate and manage API tokens from your AI Hub user settings. See the authorization documentation for details.

Create a batch

Description

Create a new batch by sending a PUT request. You must upload files to the batch separately.

Request headers

Request body

Response status

A 2XX status code indicates the request was successful.

Response schema

Example request

import requests

url = api_root

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

data = {
  'batch_name': 'my new batch'

}

resp = requests.put(url, headers=headers, data=data)

Upload file to batch

Description

Use this endpoint to upload a file to a batch, or to update the contents of a previously uploaded file in a batch. In the request URL, <BATCH_ID> is the batch’s ID and <FILENAME> is a user-defined name for the file. The file name must include the file extension.

Files can be uploaded one at a time and the suggested max size for each file is 10 MB. For larger files, use the multipart file upload endpoint.

Request headers

Request body

Supply the raw contents of file to be uploaded. See the example request, being sure to define the <LOCAL_FILEPATH> with the full path to the file in the machine that’s running the script.

Response status

Response schema

There is no response body.

Example request

import requests

url = api_root + f'/<BATCH_ID>/files/<FILENAME>'

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

with open('<LOCAL_FILEPATH>') as f:
    data = f.read()
resp = requests.put(url, headers=headers, data=data)

Where <LOCAL_FILEPATH> is the full path to the file in the machine that’s running the script.

Get batch

Description

Retrieve information about a batch by sending this GET request.

Request headers

There are no additional request headers.

Request body

There is no request body. Use the request URL to provide the batch’s batch ID (BATCH_ID).

Response status

Response schema

{
  "id": 2465, 
  "name": "my new batch",
  "workspace_name": "my-repo",
  "mount_point_name": "Instabase Drive",
  "repo_owner": "test_admin",
  "batch_owner": "test_admin", 
  "created_at_ms": 1709592306000, 
  "updated_at_ms": 1709592306000, 
  "path_suffix": "file-batches/c53a8a50-6b7b-4184-9aa3-132e9e8fa780"
}

Example request

import requests

url = api_root + f'/<BATCH_ID>'

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

resp = requests.get(url, headers=headers)

List batches

Description

Return a list of batches, with results filtered using query parameters.

Request headers

Request body

There is no request body. Use the request URL’s query parameters to filter the list of batches.

Response status

Response schema

Example request

import requests

# define filters
workspace_name = 'my-workspace'
limit = 100

headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'IB-Context': 'my-org'
}

url = api_root

resp = requests.get(url, headers=headers, params={ 'workspace_name': workspace_name, 'limit': limit })

Delete batch

Description

Delete a batch and all of its files. This is an asynchronous operation that must be checked for completion. See details on polling jobs.

Specify the <BATCH_ID> in the URL to identify the batch to be deleted.

Request headers

There are no additional request headers.

Request body

There is no request body. Use the request URL to specify the batch to be deleted.

Response status

Response schema

Example request

import requests

url = api_root + f'/<BATCH_ID>'

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

resp = requests.delete(url, headers=headers)
poll_url = api_root + f'/jobs/{resp.json()['job_id']}'

# poll until complete
while True:
    resp = requests.get(poll_url, headers=headers)
    if resp.json()['state'] == 'COMPLETE':
        break

Delete file from batch

Description

Delete a file from a batch by sending this DELETE request. Use <BATCH_ID> and <FILENAME> in the request URL to specify the file to be deleted.

Request headers

There are no additional request headers.

Request body

There is no request body. Use the request URL to specify the file to be deleted.

Response status

A 2XX status code indicates the request was successful.

Response headers

Response schema

There is no response body.

Example request

import requests

url = api_root + f'/<BATCH_ID>/files/<FILENAME>'

headers = {
'Authorization': f'Bearer {API_TOKEN}'
}
resp = requests.delete(url, headers=headers)

Poll batches job

Description

Use this endpoint to poll asynchronous jobs created when deleting a batch or deletinng a file from a batch. In the request URL, <JOB_ID> is the job_id value returned by a Delete batch request or the Location header value returned by a Delete file from a batch request.

Request headers

There are no additional request headers.

Request body

There is no request body. Use the request URL to specify the job to poll.

Response status

Response schema

Multipart file upload

To upload a file larger than 10 MB in size to a batch, you must use multipart upload. Multipart upload involves three endpoints and the following steps:

1. Start a multipart upload session, specifying the batch ID, file name, and file size. This call returns a session ID and maximum part_size to reference when uploading each part.

2. Split the file into parts, according to the specified part_size, and upload each part individually.

3. When all parts are uploaded, commit the session.

Multipart upload example request

headers = {
  'Authorization': f'Bearer {API_TOKEN}'
}
# 1. create session
local_filepath = '<LOCAL_FILEPATH>'
size = os.path.getsize(local_filepath)
resp = requests.post(f'<API_ROOT>/multipart-upload',
                     headers=headers,
                     data=json.dumps({'path': destination_filepath, 'file_size': size}))
session_endpoint = resp.headers['location']
part_size = resp.json()['part_size']

# 2. upload parts
parts = []
part_num = 1
with open(local_filepath, 'rb') as input_file:
    part = input_file.read(part_size)
while part:
    part_resp = requests.put(f'{session_endpoint}/parts/{part_num}', headers=headers, data=part)
    parts.append({'part_num': part_num, 'part_id': part_resp.json()['part_id']})
    part = input_file.read(part_size)
    part_num += 1

# 3. Commit all the uploaded parts.
commit_resp = requests.post(session_endpoint, headers=headers, data=json.dumps({'action': 'commit', 'parts': parts}))

Where <LOCAL_FILEPATH> is the full path to the file in the machine that’s running the script.

Start multipart upload session

Description

Start a multipart upload session. Use this endpoint when you need to upload a file larger than 10 MB to a batch.

Request headers

There are no additional request headers.

Request body

Response status

A 2XX status code indicates the request was successful.

Response headers

Response schema

Example request

See full multipart upload request.

Upload part to session

Description

Upload part of a file to the multipart upload session, where each part’s size matches the part_size returned by the Start multipart upload session call. Each part should match the part_size, except for the final part, which can be smaller than the part_size.

<SESSION_ID> should be obtained in the Location header from the start multipart upload session response, and <PART_NUM> is an increasing consecutive integer sequence starting at 1 for every part uploaded.

Request headers

There are no additional request headers.

Request body

Raw content of the part to be uploaded.

Response status

A 2XX status code indicates the request was successful.

Response schema

Example request

See full multipart upload request.

Commit session

Description

After uploading all parts to a multipart upload session, use this endpoint to commit and close the multipart upload session, or to cancel the session.

Request headers

There are no additional request headers.

Request body

Response status

A 2XX status code indicates the request was successful.

Response schema

There is no response body.

Example request

See full multipart upload request.