Using the API and SDK

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.

    To make API or SDK calls that aren’t tied to a particular user, use a service account.

  • 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.

  • Use the playground feature in the API reference documentation.

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:

VariableValue
API_ROOTThe 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_TOKENYour API token.
IB_CONTEXTThe 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.

1package main
2
3import (
4	"bytes"
5	"encoding/json"
6	"fmt"
7	"io"
8	"net/http"
9	"os"
10)
11
12func 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.

VariableValue
API_ROOTThe 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_TOKENYour API token.
IB_CONTEXTThe 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.
The documentation page for each API operation includes sample code for calling the API in Python. The API playground includes sample code in Typescript.

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.

button to run postman

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

  1. In Postman, in the left sidebar, click Instabase AI Hub.

  2. Click the Variables tab.

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

  1. Update the Current value column for the following variables.
VariableValue
API_ROOTYour 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_KEYYour API token.
CONTEXTThe value for the IB-Context header.
• To use your community account, enter {{USER_ID}}
• To use your organization account, enter {{ORGANIZATION_ID}}
USER_IDYour user ID.
ORGANIZATION_IDYour organization ID.
• For community accounts, accept the default.
• For organization accounts, enter your organization ID.
  1. 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.

  1. Navigate to the App Run > Create batch endpoint.

  2. Click Send.

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

Playground

The playground is a feature of the AI Hub documentation, not of the AI Hub app.

Every page in the API reference section of the AI Hub documentation includes an interactive playground that lets you build and send requests. The playground isn’t suitable for production use, but is a convenient way to learn about the API.

For example, use the navigation pane on the left side of this page to visit the API reference > Runs > Run deployment page and click Play above the curl sample code.

API playground Play button, within a request sample

If your organization uses a custom AI Hub domain, you must edit the root API URL whenever using the playground. Double-click the request URL at the top of any playground page and set the custom URL, ending with /api.

To see the playground in action, use it to make an API call to create a batch. This particular call is a free operation that doesn’t use any consumption units.

  1. Navigate to the create batch endpoint documentation page.

  2. In the sample code frame, click Play to open the playground.

  3. If you haven’t already entered an API key, click Login to send a real request and enter your API token.

  4. In the Body Parameters section, enter test as the value of the name parameter.

  5. Click Send Request.

The RESPONSE box shows a JSON object with an id key and an integer value.

The playground shows sample code for making direct API calls with curl, Typescript, or Python, based on the selector in the top right. The copy icon above the sample code lets you paste sample code into your own scripts.

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.

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

Parameter reference

ParameterTypeValueDescription
api_rootstrNoThe 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_keystrYesYour API token.
ib_contextstrNo, but recommendedThe 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.

1batch = client.batches.create(name='test-batch')
2print(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.

Was this page helpful?