Getting Started with the Bobsled AI API

This guide will help you get up and running with the Bobsled AI API in minutes.

Overview

The Bobsled AI API allows you to programmatically interact with your Bobsled AI workspaces, including:

• Managing workspaces and their configurations
• Configuring semantic models for natural language to SQL translation
• Sending chat messages and receiving AI-powered responses
• Managing users and access permissions

Authentication

The Bobsled AI API supports two authentication methods:

1. API Keys (Recommended for programmatic access)

API keys provide long-lived credentials for server-to-server integrations.

1. Generate an API key in the Bobsled AI dashboard under Settings > API Keys
2. Exchange your API key for a short-lived JWT token:

curl -X POST https://{tenant}.bobsled.ai/api/v1/auth/token \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "expiresAt": "2024-01-01T13:00:00.000Z"
  }
}

3. Use the JWT token for subsequent API calls:

curl https://{tenant}.bobsled.ai/api/v1/accounts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

2. Session Tokens (Browser-based applications)

If you're building a web application that authenticates users via Clerk, session tokens are automatically included in requests from the browser.

Token Refresh

JWT tokens expire after 1 hour. To maintain uninterrupted API access:

1. Check the expiresAt field in the token response to know when your token expires
2. Re-exchange your API key for a new token before expiration
3. Consider implementing automatic refresh 5 minutes before expiry

// Example: Check if token needs refresh
const tokenExpiresAt = new Date(tokenResponse.data.expiresAt);
const fiveMinutesFromNow = new Date(Date.now() + 5 * 60 * 1000);

if (tokenExpiresAt < fiveMinutesFromNow) {
  // Token expires soon, refresh it
  const newToken = await refreshToken(apiKey);
}

Base URL

All API requests should be made to your tenant-specific URL:

https://{tenant}.bobsled.ai/api/v1

Replace {tenant} with your organization's subdomain (e.g., acme for acme.bobsled.ai).

Response Format

All API responses follow a consistent format:

Success Response

{
  "ok": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found.",
    "statusCode": 404,
    "workspaceId": "..."
  }
}

Quick Start Example

Here's a complete example to get you started:

1. List your accounts

curl https://{tenant}.bobsled.ai/api/v1/accounts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

2. List workspaces in an account

curl https://{tenant}.bobsled.ai/api/v1/accounts/{accountId}/workspaces \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. Send a chat message

curl -X POST https://{tenant}.bobsled.ai/api/v1/accounts/{accountId}/workspaces/{workspaceId}/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were total sales last month?"
  }'

Response:

{
  "ok": true,
  "data": {
    "threadId": "thread_abc123",
    "answer": "Total sales last month were $1,234,567..."
  }
}

Common Error Codes

Rate Limits

API requests are rate limited to ensure fair usage:

• Token generation: 10 requests per minute
• Read operations: 1,000 requests per minute
• Write operations: 100 requests per minute

When you exceed the rate limit, you'll receive a 429 response with a Retry-After header.

Next Steps

• Explore the API Reference for detailed endpoint documentation
• Learn about Workspaces and how to configure them
• Set up Semantic Models for your data
• Configure Verified Queries for common questions

Support

If you need help or have questions:

• Check our API Reference for detailed documentation
• Contact support at [email protected]