openapi: 3.0.0
info:
title: AI Hub API
version: "0.1"
description: The AI Hub REST API. See https://docs.instabase.com/api-sdk/ for more details.
termsOfService: https://www.instabase.com/terms-of-service/
contact:
name: Instabase Support
url: https://help.instabase.com/
license:
name: MIT
url: https://github.com/instabase/aihub-python/blob/master/LICENSE
servers:
- url: https://aihub.instabase.com/api
security:
- bearerAuth: []
paths:
/v2/batches:
post:
operationId: createBatch
x-fern-audiences:
- public
tags:
- Batches
summary: Create batch
description: |
Create a new batch.
<Note>[Upload files to the batch](/api-sdk/api-reference/batches/add-file-to-batch) in a separate request.</Note>
parameters:
- $ref: '#/components/parameters/ib_context'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the batch. Maximum length is 255 characters.
workspace:
type: string
description: |
The name of the workspace in which to add the batch. If not specified, the default location is your personal workspace.
When making this call from a service account, you must specify a workspace.
<Info>For organization members, if the default drive changes but is still connected, you can still use the batch as input for running an app. However, you can't upload any additional files to the batch. If the default drive is disconnected, you can't use batches stored on that drive as input for any app run.</Info>
required:
- name
responses:
'200':
description: Batch created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/batch'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl "${API_ROOT}/v2/batches" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}" \
-H "Content-Type: application/json" \
-d '{"name": "test"}'
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
response = client.batches.create(
name="MyBatch",
workspace="MyWorkspace"
)
print(f"batch_id: {response.id}")
- sdk: python
name: without SDK
code: |
import requests
url = "https://aihub.instabase.com/api/v2/batches"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# create the request payload
data = {
"name": "MyBatch",
"workspace": "MyWorkspace"
}
# make the POST request
response = requests.post(url, headers=headers, json=data)
# handle the response
if response.status_code == 200:
print(f"Batch created with ID: {response.json()['id']}")
else:
print(f"Error: {response.status_code} - {response.text}")
get:
operationId: listBatches
x-fern-audiences:
- public
tags:
- Batches
summary: List batches
description: Return a list of batches. Use query parameters to filter results.
parameters:
- in: query
name: workspace
schema:
type: string
description: Filter to batches in the specified workspace.
- in: query
name: username
schema:
type: string
description: Filter to batches created by the specified username (user ID).
- in: query
name: limit
schema:
type: integer
description: If paginating results, specify how many batches to return.
- in: query
name: offset
schema:
type: integer
description: If paginating results, specify the offset of the returned list.
- $ref: '#/components/parameters/ib_context'
responses:
'200':
description: Request successful.
content:
application/json:
schema:
type: object
properties:
batches:
type: array
description: List of batches. See response schema for each batch object.
items:
$ref: '#/components/schemas/batchInfo'
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl "${API_ROOT}/v2/batches" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}" \
-G \
--data-urlencode "workspace=my-workspace" \
--data-urlencode "limit=100"
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
response = client.batches.list(
workspace="MyWorkspace",
username="john.doe_acme.com",
limit=3,
offset=6
)
for batch in response.batches:
print(f"id: {batch.id}")
print(f"name: {batch.name}")
- sdk: python
name: without SDK
code: |
import requests
url = "https://aihub.instabase.com/api/v2/batches"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# create query parameters
params = {
"workspace": "MyWorkspace",
"limit": 3,
"offset": 6
}
# make the GET request
response = requests.get(url, headers=headers, params=params)
# handle the response
if response.status_code == 200:
print(f"Retrieved {len(response.json()['batches'])} batches")
else:
print(f"Error: {response.status_code} - {response.text}")
/v2/batches/{batch_id}:
get:
operationId: getBatch
x-fern-audiences:
- public
tags:
- Batches
summary: Get batch information
description: Retrieve information about a batch.
parameters:
- $ref: '#/components/parameters/batch_id'
- $ref: '#/components/parameters/ib_context'
responses:
'200':
description: Batch successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/batchInfo'
'404':
description: Batch does not exist, or denied access.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl "${API_ROOT}/v2/batches/<BATCH-ID>" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}"
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
batch_info = client.batches.get(batch_id=12345)
print(f"id: {batch_info.id}")
print(f"name: {batch_info.name}")
- sdk: python
name: without SDK
code: |
import requests
batch_id = 12345
url = f"https://aihub.instabase.com/api/v2/batches/{batch_id}"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# make the GET request
response = requests.get(url, headers=headers)
# handle the response
if response.status_code == 200:
print(f"id: {response.json()['id']}")
print(f"name: {response.json()['name']}")
else:
print(f"Error: {response.status_code} - {response.text}")
delete:
operationId: deleteBatch
x-fern-audiences:
- public
tags:
- Batches
summary: Delete batch
description: Delete a batch and all its files. This is an asynchronous operation that must be [checked for completion](/api-sdk/api-reference/batches/poll-batches-job).
parameters:
- $ref: '#/components/parameters/batch_id'
- $ref: '#/components/parameters/ib_context'
responses:
'202':
description: Batch deletion request accepted. [Poll the job ID](/api-sdk/api-reference/batches/poll-batches-job) to check completion status.
content:
application/json:
schema:
$ref: '#/components/schemas/batchDeletionJobResponse'
'404':
description: Batch does not exist.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl -X DELETE "${API_ROOT}/v2/batches/<BATCH-ID>" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}"
- sdk: python
name: with SDK
code: |
import time
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
delete_response = client.batches.delete(batch_id=12345)
# check delete job status until done
while True:
poll_response = client.batches.poll_job(
job_id=delete_response.job_id
)
if poll_response.state not in ["PENDING", "RUNNING"]:
break
time.sleep(3) # pause before polling the status again
- sdk: python
name: without SDK
code: |
import requests
batch_id = 12345
url = f"https://aihub.instabase.com/api/v2/batches/{batch_id}"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# make the DELETE request
response = requests.delete(url, headers=headers)
# handle the response
if response.status_code == 202:
print("Batch deletion job started with ID: "
f"{response.json()['job_id']}")
else:
print(f"Error: {response.status_code} - {response.text}")
# not included here: check status of deletion job until it's done
/v2/batches/{batch_id}/files:
get:
operationId: listFiles
x-fern-audiences:
- public
tags:
- Batches
summary: List files in a batch
description: Return a list of files in a batch.
parameters:
- $ref: '#/components/parameters/batch_id'
- in: query
name: page_size
schema:
type: integer
description: The number of files to return in each page.
- in: query
name: start_token
schema:
type: string
description: The token to start the list from.
- $ref: '#/components/parameters/ib_context'
responses:
'200':
description: Request successful.
content:
application/json:
schema:
$ref: '#/components/schemas/listBatchFilesResponse'
example:
nodes:
- full_path: "/path/to/document1.pdf"
metadata:
node_type: "file"
size: 1024
modified_timestamp: 1647532800
perms:
can_read: true
can_write: true
can_delete: true
name: "document1.pdf"
- full_path: "/path/to/document2.pdf"
metadata:
node_type: "file"
size: 2048
modified_timestamp: 1647619200
perms:
can_read: true
can_write: false
can_delete: false
name: "document2.pdf"
next_page_token: "eyJwYWdlIjogMn0="
has_more: true
'404':
description: Batch does not exist, or denied access.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl "${API_ROOT}/v2/batches/<BATCH-ID>/files" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}"
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
response = client.batches.list_files(
batch_id=12345,
page_size=2,
start_token="abcd...<snip>...1234"
)
print(f"Has more files? {response.has_more}")
for node in response.nodes:
print(f"File name: {node.name}")
- sdk: python
name: without SDK
code: |
import requests
batch_id = 12345
url = f"https://aihub.instabase.com/api/v2/batches/{batch_id}/files"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
page_size = 2
start_token = None
# make repeated calls to fetch more files until there are no more
while True:
params = {
"page_size": page_size,
"start_token": start_token
}
# make the GET request
response = requests.get(url, headers=headers, params=params)
# handle the response
if response.status_code != 200:
print(f"Error: {response.status_code} - {response.text}")
break
for node in response.json()['nodes']:
print(f"File name: {node['name']}")
if not response.json().get("has_more"):
break
start_token = response.json().get("next_page_token")
/v2/batches/{batch_id}/files/{filename}:
put:
operationId: addFileToBatch
x-fern-audiences:
- public
tags:
- Batches
summary: Upload file to batch
description: |
Upload a file to a batch or update the contents of a previously uploaded file in a batch.
<Info>Files can be uploaded one at a time and the suggested max size for each file is 10 MB. For larger files, see [Multipart file upload](/api-sdk/api-reference/batches/create-multipart-upload-session).</Info>
<Note>If you upload a password-protected PDF, provide the password when you process the PDF with an AI Hub app. See instructions for configuring the `settings.runtime_config.instabase.pdf.passwords` property for the [Run deployment](/api-sdk/api-reference/runs/run-deployment#request.body.settings.runtime_config.instabase.pdf.passwords) or [Run app](/api-sdk/api-reference/runs/run-app#request.body.settings.runtime_config.instabase.pdf.passwords) operations.</Note>
parameters:
- $ref: '#/components/parameters/batch_id'
- name: filename
in: path
required: true
description: A user-defined name for the file on the Instabase filesystem. Include the file extension. This doesn't need to be the same as its name on your local filesystem.
schema:
type: string
- $ref: '#/components/parameters/ib_context'
requestBody:
required: true
content:
application/octet-stream:
schema:
description: The raw contents of the file to upload. See the example request, being sure to define the `<LOCAL_FILEPATH>` with the full path to the file in the machine running the script.
type: string
format: binary
responses:
'204':
description: File uploaded successfully.
'404':
description: Batch with ID <BATCH-ID> does not exist.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl -X PUT "${API_ROOT}/v2/batches/<BATCH-ID>/files/<FILENAME>" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}" \
-H "Content-Type: application/octet-stream" \
--upload-file '<LOCAL_FILEPATH>' # Full path to the file in the machine that's making the request
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
local_filepath = "/local/path/to/file1.pdf"
# returns None
with open(local_filepath, "rb") as local_file:
client.batches.add_file(
batch_id=12345,
file_name="MyFile1.pdf", # AI Hub filesystem
file=local_file # local filesystem
)
- sdk: python
name: without SDK
code: |
import requests
batch_id = 12345
ai_hub_filename = "MyFile1.pdf"
url = f"https://aihub.instabase.com/api/v2/batches/{batch_id}/files/{ai_hub_filename}"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com",
"Content-Type": "application/octet-stream"
}
local_filepath = "/local/path/to/file1.pdf"
# read the file contents
with open(local_filepath, "rb") as local_file:
file_content = local_file.read()
# make the PUT request
response = requests.put(url, headers=headers, data=file_content)
# handle the response
if response.status_code == 204:
print("File uploaded successfully")
else:
print(f"Error: {response.status_code} - {response.text}")
delete:
operationId: deleteFileFromBatch
x-fern-audiences:
- public
tags:
- Batches
summary: Delete file from batch
description: Delete a file from a batch.
parameters:
- $ref: '#/components/parameters/batch_id'
- name: filename
in: path
required: true
description: The name of the file.
schema:
type: string
- $ref: '#/components/parameters/ib_context'
responses:
'202':
description: File deletion request accepted. Poll the deletion job for completion status.
'404':
description: Batch does not exist.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl -X DELETE "${API_ROOT}/v2/batches/<BATCH-ID>/files/<FILENAME>" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}"
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
# returns None
client.batches.delete_file(
batch_id=12345,
file_name="MyFile.txt"
)
- sdk: python
name: without SDK
code: |
import requests
batch_id = 12345
ai_hub_filename = "MyFile.txt"
url = f"https://aihub.instabase.com/api/v2/batches/{batch_id}/files/{ai_hub_filename}"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# make the DELETE request
response = requests.delete(url, headers=headers)
# handle the response
if response.status_code == 202:
print("File deletion request accepted")
else:
print(f"Error: {response.status_code} - {response.text}")
/v2/batches/multipart-upload:
post:
operationId: createMultipartUploadSession
x-fern-audiences:
- public
tags:
- Batches
summary: 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.
The multipart upload process consists of three steps:
1. Create a multipart upload session (this endpoint)
2. [Upload file parts](/api-sdk/api-reference/batches/upload-multipart-part) to the session
3. [Commit the session](/api-sdk/api-reference/batches/commit-multipart-upload-session) to finalize the upload
parameters:
- $ref: '#/components/parameters/ib_context'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
batch_id:
type: integer
description: The batch ID to upload the file to.
filename:
type: string
description: A file name for the uploaded file on the AI Hub filesystem, including the file extension. Maximum of 255 characters.
file_size:
type: integer
description: The file size, in bytes. Can be an integer or a string.
required:
- batch_id
- filename
- file_size
responses:
'201':
description: The multipart upload session was initiated.
headers:
Location:
schema:
type: string
description: The session endpoint URL to use in subsequent multipart upload requests, in the form `<API-ROOT>/v2/batches/multipart-upload/sessions/<SESSION-ID>`.
content:
application/json:
schema:
$ref: '#/components/schemas/multipartUploadSessionResponse'
'404':
description: Batch with the specified ID doesn't exist.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl "${API_ROOT}/v2/batches/multipart-upload" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}" \
-H "Content-Type: application/json" \
-d '{
"batch_id": <BATCH-ID>,
"filename": "large-file.pdf",
"file_size": 15728640
}'
- sdk: python
name: with SDK
code: |
import os
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
ai_hub_filename = "large-file.pdf"
# get file size
local_filepath = "/local/path/to/large-file.pdf"
file_size = os.path.getsize(local_filepath)
# create multipart upload session
response = client.batches.create_multipart_upload_session(
batch_id=12345,
filename=ai_hub_filename,
file_size=file_size
)
print(f"Session ID: {response.session_id}")
print(f"Part size: {response.part_size}")
- sdk: python
name: without SDK
code: |
import os
import requests
ai_hub_filename = "large-file.pdf"
# get file size
local_filepath = "/local/path/to/large-file.pdf"
file_size = os.path.getsize(local_filepath)
url = "https://aihub.instabase.com/api/v2/batches/multipart-upload"
headers = {
"Authorization": "Bearer abcdefghijklmnopqrst1234567890",
"IB-Context": "john.doe_acme.com"
}
# create the request payload
data = {
"batch_id": 12345,
"filename": ai_hub_filename,
"file_size": file_size
}
# make the POST request
response = requests.post(url, headers=headers, json=data)
# handle the response
if response.status_code == 201:
print(f"Session ID: {response.json()['session_id']}")
print(f"Part size: {response.json()['part_size']}")
else:
print(f"Error: {response.status_code} - {response.text}")
/v2/batches/multipart-upload/sessions/{session_id}/parts/{part_num}:
put:
operationId: uploadMultipartPart
x-fern-audiences:
- public
tags:
- Batches
summary: Upload part to multipart session
description: |
Upload part of a file to the multipart upload session. The size of each part must match the `part_size` returned by the [Start multipart upload session](/api-sdk/api-reference/batches/create-multipart-upload-session) call, except for the final part, which can be smaller.
Parts must be uploaded with consecutive part numbers starting at 1.
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: The session ID obtained from the Start multipart upload session response.
- name: part_num
in: path
required: true
schema:
type: integer
description: The part number, starting at 1 and increasing consecutively for each part.
- $ref: '#/components/parameters/ib_context'
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
description: Raw content of the part to be uploaded.
responses:
'201':
description: The part was successfully uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/multipartUploadPartResponse'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: |
curl -X PUT "${API_ROOT}/v2/batches/multipart-upload/sessions/<SESSION_ID>/parts/1" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "IB-Context: ${IB_CONTEXT}" \
-H "Content-Type: application/octet-stream" \
--data-binary "@part1.bin"
- sdk: python
name: with SDK
code: |
from aihub import AIHub
client = AIHub(
api_root="https://aihub.instabase.com/api",
api_key="abcdefghijklmnopqrst1234567890",
ib_context="john.doe_acme.com"
)
# --- truncated at 32 KB (175 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instabase/refs/heads/main/openapi/instabase-aihub-openapi.yaml