Getting Started with Bobsled AI API v1

Welcome to the Bobsled AI API! This guide covers authentication, making requests, and core concepts.

Base URL

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

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

Authentication

The Bobsled AI API uses Clerk for authentication. All API requests require a valid session token.

Obtaining a Token

1. Web Application: Tokens are automatically managed when using the Bobsled AI web interface
2. Programmatic Access: Use Clerk's authentication methods to obtain a session token

Making Authenticated Requests

Include the session token in the Authorization header:

curl -X GET "https://{tenant}.bobsled.ai/api/v1/accounts" \
  -H "Authorization: Bearer {session_token}" \
  -H "Content-Type: application/json"

Response Format

All responses follow a consistent format:

Success Response

{
  "ok": true,
  "data": { ... }
}

Error Response

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

Core Resources

Hierarchy

Account
└── Workspace
    ├── Semantic Models      (data schema definitions)
    ├── Verified Queries     (question → SQL mappings)
    ├── System Prompts       (AI behavior configuration)
    ├── Data Assets          (connected data sources)
    ├── Front Page Configs   (chat UI customization)
    └── Users                (workspace access)

Key Endpoints

Authorization

Access is controlled by account-scoped roles:

• Account Admin: Full access to all workspaces within an account
• Global Admin: Full access to all accounts and workspaces

Users can only access resources within accounts where they have an assigned role.

Quick Start Example

1. List Your Accounts

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

2. List Workspaces in an Account

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

3. Get Semantic Model for a Workspace

curl -X GET "https://{tenant}.bobsled.ai/api/v1/accounts/{accountId}/workspaces/{workspaceId}/semantic-models" \
  -H "Authorization: Bearer {token}"

Error Codes

Pagination

List endpoints support pagination via query parameters:

curl "https://{tenant}.bobsled.ai/api/v1/accounts/{accountId}/workspaces?limit=10&offset=20"

Next Steps

• Explore the API Reference for detailed endpoint documentation