Developer quickstart

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

You can interact with the AI Hub API in several ways:

• Use the AI Hub software development kit (SDK), which wraps API calls in Python classes and methods. The SDK is the easiest way to get started.

• Call RESTful API endpoints with curl or any programming language.

• Use the AI Hub Postman collection to make API calls.

• Use the playground feature in the API reference documentation. This can help you learn the API by sending requests directly from the documentation pages.

Account setup

Before using the AI Hub API, 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. 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 IB-Context header is undefined, AI Hub will use consumption units from your community account.

Using the AI Hub SDK

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

$
pip install instabase-aihub

Initializing the SDK with an 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, 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>)

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

Using curl

curl is a command line tool for making HTTP requests, including calls to API endpoints The playground feature in the reference documentation for each API endpoint includes examples that use curl.

Here’s an example of using curl to call the batches endpoint:

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

All curl calls use the environment variables API-ROOT, API-TOKEN, and IB-Context.

You’re not limited to curl. You can access API endpoints with any language that makes HTTP requests. For example, the API reference documentation’s playground feature shows Python and Typescript code for making direct API calls to each endpoint.

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

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, you can set up your authorization and context identification variables. In Postman, click Instabase AI Hub in the left navigation panel and click the Variables tab.

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

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.

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

Testing

To test your setup, 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. If there are no errors, your setup works.

SDK

Run the following command:

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

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-batch"}'

Postman

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

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.

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

Next steps

With your setup complete and tested, you’re ready to interact with the AI Hub API. Your next steps might include:

• Run an AI Hub app using the AI Hub SDK.

• Create a Converse conversation using the AI Hub SDK.

• Learn about all AI Hub API endpoints with the AI Hub 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 that use consumption units.

• Review AI Hub release notes, which include API and SDK changes.