Developer quickstart

With the AI Hub API, you can integrate AI Hub functionality into your own workflows and tooling. The AI Hub API is a RESTful API that can be used with any language. AI Hub also offers a Python software development kit (SDK) and Postman collection to help interface with the API. The API documentation also features an API playground, letting you build and send requests within the reference documentation.

Account setup

To get started using the AI Hub API:

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

  • You need your user ID or organization ID, to use in the IB-Context header. 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, passing your organization ID in the IB-Context header is the only way to identify a request as coming from your organization account. Your API token is tied to both your community account and your organization account. If the header is undefined, the default behavior is to use your community account. This means if the header is undefined, your community account is the cost center for any requests that require consumption units to complete.

Using the Python SDK

The AI Hub SDK requires Python 3.7 or higher.
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.

The AI Hub SDK is published to the Python Package Index (PyPI). To install the AI Hub SDK, run the following command:

1pip install instabase-aihub

Initializing the API client

When using the AI Hub SDK, you must initialize the API client with your own api_key, api_root, and ib_context values. The client can then handle authorization and context identification when interacting with the AI Hub API through the SDK.

To initialize the API client, run the following command:

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

Fill in the api_root, api_key, and ib_context values as follows:

VariableValue
api_rootYour AI Hub root URL.

- Community accounts: Enter the default AI Hub root API URL, https://aihub.instabase.com/api, or omit api_root.
- Organization accounts: If your organization has a custom AI Hub domain, enter your organization’s root API URL, such as https://my-organization.instabase.com/api.
api_keyYour API token.
ib_contextThe value to use for the IB-Context header.

- To use your community account, enter your user ID or omit ib_context.
- To use your organization account, enter your organization ID.

With the SDK installed and client initialized, you can follow any Python SDK example provided in the AI Hub API reference. SDK examples are marked with # AI Hub Python SDK example.

Selecting Python from the API code sample language dropdown

Using Postman

An AI Hub API collection is available in Postman, an API platform for building and using APIs. The AI Hub collection includes automation so that responses from one API call are automatically populated in subsequent calls. 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, you can set up your authorization and context identification variables on the Variables tab.

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

Update the Current value column for the following commonly used variables, then click Save.

VariableValue
API_ROOTYour AI Hub root URL.

- Community accounts: Accept the default.
- Organization accounts: If your organization has a custom AI Hub domain, enter your organization’s root API URL, such as https://my-organization.instabase.com/api. Accept the default if not.
API_KEYYour API token.
USER_IDYour user ID.
ORGANIZATION_IDYour organization ID.

- Community accounts: Accept the default.
- Organization accounts: Enter your organization ID.
CONTEXTThe value to use for the IB-Context header.

- To use your community account, enter {{USER_ID}}.
- To use your organization account, enter {{ORGANIZATION_ID}}.

Using curl

curl is a common but minimalist command line tool that can be used to make HTTP requests. While you can interact with the AI Hub API in any language, all endpoint references include a curl example.

The API playground view lets you generate sample requests in Python and TypeScript as well.

All curl examples reference the API root, API token, and IB-Context header values as variables. For example:

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

If you don’t set up these variables, define them as follows:

VariableValue
${API_ROOT}Your AI Hub root URL.

- Community accounts: Enter the default AI Hub root API URL, https://aihub.instabase.com/api.
- Organization accounts: If your organization has a custom AI Hub domain, enter your organization’s root API URL, such as https://my-organization.instabase.com/api. Use the default AI Hub root API URL if not.
${API_TOKEN}Your API token.
${IB_CONTEXT}The value to use for the IB-Context header.

- To use your community account, enter your user ID or omit the IB-Context header.
- To use your organization account, enter your organization ID.

Using the API playground

The AI Hub API reference documentation includes an API playground feature, an interactive tool that lets you build and send requests. You can:

  1. Edit the root API URL used in the request URL, to support custom AI Hub domains. Double-click to edit the field.

  2. Add your API token, letting you send real requests using your AI Hub account.

  3. Customize your request, adding and defining supported headers and parameters. The request URL updates when you define path or query parameters.

  4. Select from cURL, TypeScript, and Python for the generated request language.

  5. Send the request and see the response.

  6. Copy the request you’ve built.

API playground view, highlighting action locations

To open the API playground view, open any endpoint in the API reference section, then click the Play button found above the request sample.

API playground Play button, within a request sample

Testing

To test your setup, you can make a basic request that requires no consumption units to complete, such as calling the Create batch endpoint. This endpoint creates an empty resource called a batch.

A successful response returns a 201 status code and a JSON object containing a batch ID, such as {"id":231}.

Python SDK

Run the following command:

1from aihub import AIHub
2
3client = AIHub(api_key="<API-TOKEN>",
4 api_root="<API-ROOT>",
5 ib_context="<IB-CONTEXT>")
6
7batch = client.batches.create(name='test')

Postman

Navigate to the Batches > Create batch endpoint and click Run.

curl

Run the following command:

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

API playground

Navigate to the Create batch endpoint reference. In the request sample frame, click Play to open the API playground view, enter test in the name parameter, then click Send Request.

What's next

With your setup complete and tested, you can start interacting with the AI Hub API. Your next steps might include:

Was this page helpful?