API Reference

Complete API documentation for the Better Data LLM Gateway

Base URL

Production

https://gateway.betterdata.io/v1

---

Authentication

All API requests require authentication using an API key:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Better Data Dashboard

---

SDKs

TypeScript/Node.js

npm install @commercegateway/commerce-gateway

Python

pip install betterdata-gateway

Coming soon!

Go

go get github.com/betterdata/gateway-go

Coming soon!

---

Quick Example

import { GatewayClient } from '@commercegateway/commerce-gateway';

const client = new GatewayClient({
  apiKey: process.env.BETTERDATA_API_KEY!,
  baseUrl: 'https://gateway.betterdata.io/v1',
});

// Search products
const products = await client.products.search({
  query: 'wireless headphones',
  limit: 10,
});

// Get product details
const product = await client.products.get('prod_123');

// Add to cart
const cart = await client.cart.add({
  productId: 'prod_123',
  quantity: 2,
  sessionId: 'session_abc',
});

---

Response Format

All API responses follow this structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

Success Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_123",
        "name": "Wireless Headphones",
        "price": 99.99,
        "inStock": true
      }
    ]
  },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameter",
    "details": {
      "field": "limit",
      "constraint": "Must be between 1 and 100"
    }
  },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

---

Error Codes

Code	Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

---

Rate Limiting

API requests are rate-limited per API key:

Plan	Rate Limit
Free	100 requests/minute
Starter	1,000 requests/minute
Growth	10,000 requests/minute
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1702281600

---

Pagination

List endpoints support cursor-based pagination:

GET /v1/products?limit=20&cursor=eyJpZCI6InByb2RfMTIzIn0

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6InByb2RfMTQ1In0",
    "total": 1247
  }
}

---

Filtering

Use query parameters to filter results:

# Filter by price range
GET /v1/products?minPrice=50&maxPrice=200

# Filter by category
GET /v1/products?category=electronics

# Filter by availability
GET /v1/products?inStock=true

# Combine filters
GET /v1/products?category=electronics&inStock=true&maxPrice=500

---

Sorting

Sort results using the sort parameter:

# Sort by price (ascending)
GET /v1/products?sort=price

# Sort by price (descending)
GET /v1/products?sort=-price

# Sort by multiple fields
GET /v1/products?sort=category,-price

---

Webhooks

Subscribe to real-time events:

POST /v1/webhooks
{
  "url": "https://your-app.com/webhooks",
  "events": ["product.created", "order.completed"]
}

Webhook Events

View all available webhook events

---

API Endpoints

Gateway Endpoints

List tools, execute tools, chat completions

Session Endpoints

Create, get, update, delete sessions

Integration Endpoints

Connect Shopify, Square, sync products

Analytics Endpoints

Get metrics, attribution, conversion data