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.

Generate an API key in the Bobsled AI dashboard under Settings > API Keys
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"
  }
}

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:

Check the expiresAt field in the token response to know when your token expires
Re-exchange your API key for a new token before expiration
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

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions for this operation
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMIT_EXCEEDED`	429	Too many requests

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 support@bobsled.co