Using the API and SDK — Instabase Documentation

With the AI Hub API and SDK, you can integrate AI Hub functionality into your own workflows and tooling by controlling AI Hub programmatically.

The API accepts RESTful HTTP requests made from a variety of tools or almost any programming language.

The SDK wraps API calls in Python classes and methods, providing a convenient way to interact with AI Hub programmatically.

Both the API and SDK cover the major use cases of AI Hub. However, their feature set isn’t identical.

The API can access most, but not all, of the same features as the graphical user interface.
The SDK can access most, but not all, of the same features as the API.

Prerequisites

Before using the API or SDK, you must complete several prerequisites.

You must have an AI Hub account. See Getting started to learn how to create a community account or join or start an organization.
You must have an API token. After creating an account, you can generate an API token.
You must have your user ID or organization ID to use in the IB-Context header that’s included with every API or SDK call. Read the context identification documentation to understand how the IB-Context header is used, its default behavior, and where to find your user ID and organization ID.

If you belong to an organization, your API token is tied to both your community account and your organization account. Passing your organization ID in the IB-Context header is the only way to identify a request as coming from your organization account.

If the IB-Context header is undefined, AI Hub will use consumption units from your community account, not your organization account.

Using the API

You can call API endpoints with any of these techniques.

Use the curl command.
Use code in any language that makes HTTP requests.
Use the AI Hub Postman collection.

curl

The curl command line tool makes HTTP requests, including calls to API endpoints. The documentation for every AI Hub API operation includes sample code for calling the API with curl.

For example, running this command in a terminal sends a POST verb to the batches endpoint, to create a resource called a batch.

$ curl -X POST "${API_ROOT}/v2/batches" \
> -H "Authorization: Bearer ${API_TOKEN}" \
> -H "IB-Context: ${IB_CONTEXT}"\
> -H "Content-Type: application/json" \
> -d '{"name": "test"}'

Before calling the API with curl, set these environment variables:

Variable	Value
`API_ROOT`	The root API URL. Combine the base URL of your AI Hub instance and `/api`. For community accounts • Use `https://aihub.instabase.com/api`. For organization accounts • If your organization has a custom AI Hub domain, include it in the URL, such as `https://my-organization.instabase.com/api`. • If your organization doesn’t have a custom AI Hub domain, use `https://aihub.instabase.com/api`.
`API_TOKEN`	Your API token.
`IB_CONTEXT`	The value to use for the `IB-Context` header. • To use your community account, use your user ID or omit the `IB-Context` header. • To use your organization account, use your organization ID.

With the environment variables defined, the previous create batch command returns a JSON object with the ID of the new batch and no errors.

The API call to create a batch is a free operation. It doesn’t use any consumption units.

Code

Most languages can make HTTP requests. To call an API endpoint using code, submit an HTTP request with the appropriate HTTP verb and parameters.

These snippets of code send the POST verb with a { "name": "test" } JSON payload to the batches endpoint in different languages.

Go

Java

Node

Python

1 package main
2 
3 import (
4 	"bytes"
5 	"encoding/json"
6 	"fmt"
7 	"io"
8 	"net/http"
9 	"os"
10 )
11 
12 func main() {
13 	jsonData, _ := json.Marshal(map[string]string{"name": "test"})
14 	apiRootUrl := os.Getenv("API_ROOT")
15 	req, _ := http.NewRequest(
16 		"POST",
17 		apiRootUrl+"/v2/batches",
18 		bytes.NewBuffer(jsonData))
19 	req.Header.Set("Authorization", "Bearer "+os.Getenv("API_TOKEN"))
20 	req.Header.Set("IB-Context", os.Getenv("IB_CONTEXT"))
21 	req.Header.Set("Content-Type", "application/json")
22 
23 	client := &http.Client{}
24 	resp, _ := client.Do(req)
25 	defer resp.Body.Close()
26 
27 	bodyBytes, _ := io.ReadAll(resp.Body)
28 	fmt.Println(string(bodyBytes))
29 }

Before making API calls from code, set the environment variables API_ROOT, API_TOKEN, and IB_CONTEXT.

Variable	Value
`API_ROOT`	The root API URL. Combine the base URL of your AI Hub instance and `/api`. For community accounts • Use `https://aihub.instabase.com/api`. For organization accounts • If your organization has a custom AI Hub domain, include it in the URL, such as `https://my-organization.instabase.com/api`. • If your organization doesn’t have a custom AI Hub domain, use `https://aihub.instabase.com/api`.
`API_TOKEN`	Your API token.
`IB_CONTEXT`	The value to use for the `IB-Context` header. • To use your community account, use your user ID or omit the `IB-Context` header. • To use your organization account, use your organization ID.

If you set these environment variables and run any of the code snippets, the API returns the ID of the newly created batch and no errors.

The API call to create a batch is a free operation. It doesn’t use any consumption units.

Postman

An AI Hub API collection is available in Postman, a platform for building and using APIs. The AI Hub collection includes automation, so responses from one API call are automatically populated in later calls.

Configure Postman

To get started, click Run in Postman and fork or import the collection. If given the option, enable notifications for any changes to the collection.

After making a copy of the collection, set up your authorization and context identification variables.

In Postman, in the left sidebar, click Instabase AI Hub.
Click the Variables tab.

The Variables tab of a Postman collection, viewed in Postman's desktop app

Update the Current value column for the following variables.

Variable	Value
`API_ROOT`	Your AI Hub root URL. For community accounts • Use `https://aihub.instabase.com/api`. For organization accounts • If your organization has a custom AI Hub domain, use your organization’s root API URL, such as `https://my-organization.instabase.com/api`. • If your organization doesn’t have a custom AI Hub domain, use `https://aihub.instabase.com/api`.
`API_KEY`	Your API token.
`CONTEXT`	The value for the `IB-Context` header. • To use your community account, enter `{{USER_ID}}` • To use your organization account, enter `{{ORGANIZATION_ID}}`
`USER_ID`	Your user ID.
`ORGANIZATION_ID`	Your organization ID. • For community accounts, accept the default. • For organization accounts, enter your organization ID.

Click Save to complete Postman configuration. It’s now ready to call the AI Hub API.

Instructions for using Postman are beyond the scope of this page. Refer to Postman documentation for more information.

To test your Postman configuration, make an API call to create a batch. Making a batch is a free operation that doesn’t use any consumption units.

Navigate to the App Run > Create batch endpoint.
Click Send.

The Body tab shows a JSON object with an id key and an integer value.

Using the SDK

The SDK requires Python 3.7 or higher. No other languages are supported.

Install the SDK

The SDK is published to the Python Package Index (PyPI). This command installs the SDK if it’s not installed, upgrades the SDK if an earlier version is installed, and does nothing if the latest version is installed.

$ pip install --upgrade instabase-aihub

If you’re new to installing Python packages, see the Python Packaging User Guide tutorial for installing packages. The tutorial covers getting started topics such as installation requirements and creating a virtual environment.

Initialize the SDK

The first step in using the SDK is initializing a client object with custom api_root, api_key, and ib_context values. The client handles authorization and context identification and provides methods for making API calls.

To initialize the SDK, start a Python script with this code.

1 from aihub import AIHub
2 
3 client = AIHub(api_root=<API-ROOT>,
4                api_key=<API-TOKEN>,
5                ib_context=<IB-CONTEXT>)

Parameter reference

Parameter	Type	Value	Description
`api_root`	str	No	The root URL of your AI Hub API. For community accounts • Omit setting `api_root`. For organization accounts • If your organization has a custom AI Hub domain, use your organization’s root API URL, such as `https://my-org.instabase.com/api`. • If your organization doesn’t have a custom AI Hub domain, omit setting `api_root`.
`api_key`	str	Yes	Your API token.
`ib_context`	str	No, but recommended	The value for the `IB-Context` header that the SDK includes with all API requests. For community accounts • Omit setting `ib_context`. For commercial accounts • To use your personal account, set to your user ID. • To use your organization account, set to your organization ID. If `ib_context` isn’t explicitly set, requests use consumption units from your community account.

With the SDK installed and initialized, you can use any SDK sample code provided in the API or SDK documentation pages.

Selecting Python from the API code sample language dropdown

SDK sample code from an API documentation page

Test the SDK

Confirm that the SDK is installed and initialized by adding this line under your initialization code and running the whole script.

1 batch = client.batches.create(name='test-batch')
2 print(batch)

If the output includes id=<INTEGER> and no errors, the SDK is working as expected.

Next steps

With your setup complete and tested, you’re ready to interact with the AI Hub API by making direct calls or by using the SDK.

Here are some things you can try next.

Run an AI Hub app using the SDK.
Create a Converse conversation using the SDK.
Learn about API endpoints with the API reference documentation.
If you prefer to make API calls using the SDK, look for SDK examples in the documentation for supported endpoints.
Learn how to track billing and usage and how unit consumption is calculated for AI Hub operations.
Learn about service accounts, which let your organization make API or SDK calls that aren’t tied to a particular user.
Review AI Hub release notes, which include API and SDK changes.

$	curl -X POST "${API_ROOT}/v2/batches" \
>	-H "Authorization: Bearer ${API_TOKEN}" \
>	-H "IB-Context: ${IB_CONTEXT}"\
>	-H "Content-Type: application/json" \
>	-d '{"name": "test"}'

1	package main
2
3	import (
4	"bytes"
5	"encoding/json"
6	"fmt"
7	"io"
8	"net/http"
9	"os"
10	)
11
12	func main() {
13	jsonData, _ := json.Marshal(map[string]string{"name": "test"})
14	apiRootUrl := os.Getenv("API_ROOT")
15	req, _ := http.NewRequest(
16	"POST",
17	apiRootUrl+"/v2/batches",
18	bytes.NewBuffer(jsonData))
19	req.Header.Set("Authorization", "Bearer "+os.Getenv("API_TOKEN"))
20	req.Header.Set("IB-Context", os.Getenv("IB_CONTEXT"))
21	req.Header.Set("Content-Type", "application/json")
22
23	client := &http.Client{}
24	resp, _ := client.Do(req)
25	defer resp.Body.Close()
26
27	bodyBytes, _ := io.ReadAll(resp.Body)
28	fmt.Println(string(bodyBytes))
29	}

1	from aihub import AIHub
2
3	client = AIHub(api_root=<API-ROOT>,
4	api_key=<API-TOKEN>,
5	ib_context=<IB-CONTEXT>)

1	batch = client.batches.create(name='test-batch')
2	print(batch)