Skip to main content

Making Your First API Request

This guide is a step-by-step walkthrough of generating your first embedding using an InertialAI model by making an API request.

It covers how to:

  • Set up authentication (API key)
  • Send an HTTPS request to the embeddings endpoint
  • Interpret the response
  • Troubleshoot common errors (401/403/422)

Before you start​

You should already have:

The basics​

API base: https://inertialai.com/api/v1

Authentication: Send your API key in the Authorization header (details in Authentication):

Authorization: Bearer <YOUR_API_KEY>

Step 1: Set your API key as an environment variable​

If you haven't already, set your API key as an environment variable.

export INERTIALAI_API_KEY="your_api_key_here"

Step 2: Choose an endpoint to call​

For this example, we’ll create an embedding using the embeddings endpoint.

Endpoint: POST /api/v1/embeddings

The request body requires:

  • model: the embedding model ID (for example inertial-embed-alpha)
  • input: either a text string or time-series numeric arrays

See the full schema in the API reference: Create a new embedding.

Step 3: Generate an embedding with cURL​

This example sends a text input.

curl -sS \
  -X POST "https://inertialai.com/api/v1/embeddings" \
  -H "Authorization: Bearer ${INERTIALAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inertial-embed-alpha",
    "input": [
      {
        "text": "The accelerometer measured 9.81 m/s² downward acceleration."
      }
    ]
  }'

What to expect on success:

  • HTTP 201
  • JSON containing:
    • data: list of embeddings
    • data[0].embedding: the embedding vector
    • usage: token usage info

Step 4: Generate an embedding with Python​

Install dependencies:

python -m pip install requests

Run the request:

import os
import requests

api_key = os.environ["INERTIALAI_API_KEY"]

resp = requests.post(
    "https://inertialai.com/api/v1/embeddings",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "inertial-embed-alpha",
        "input": [
            {
                "text": "The accelerometer measured 9.81 m/s² downward acceleration."
            }
        ],
    },
    timeout=30,
)

resp.raise_for_status()
payload = resp.json()

print("model:", payload.get("model"))
print("num_embeddings:", len(payload["data"]))
print("embedding_length:", len(payload["data"][0]["embedding"]))

Tip: If you prefer using the OpenAI Python SDK, see Using the OpenAI Python SDK for a streamlined approach with built-in retries, error handling, and type hints.

Step 5: Common errors and how to fix them​

401 Unauthorized​

Usually means the API key header is missing or malformed.

Things to check:

  • Header is exactly Authorization: Bearer <key>
  • Your environment variable is set: echo $INERTIALAI_API_KEY

403 Forbidden​

Usually means the key is invalid, revoked, expired, or doesn’t have access.

Things to try:

  • Create a new API key in the API Keys section of the InertialAI dashboard.
  • Ensure you’re using the latest copied API key value.

422 Validation Error​

The request body didn’t match the schema.

Common causes:

  • Missing required fields like model or input
  • Malformed input data

Fix:

429 Too Many Requests (rate limiting)​

If you receive 429, you’re sending requests too quickly.

Things to try:

  • Retry with exponential backoff
  • Reduce concurrency

Support​

If you encounter any issues making your first API request, please contact our support team at support@inertialai.com.

Next steps​