> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for the Better Data LLM Gateway

## Base URL

<CodeGroup>
  ```bash Production theme={null}
  https://gateway.betterdata.io/v1
  ```

  ```bash Self-Hosted theme={null}
  http://localhost:3000
  ```
</CodeGroup>

***

## Authentication

All API requests require authentication using an API key:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  Get your API key from the [Better Data Dashboard](https://app.betterdata.io/settings/api-keys)
</Note>

***

## SDKs

<CardGroup cols={3}>
  <Card title="TypeScript/Node.js" icon="node-js">
    ```bash theme={null}
    npm install @commercegateway/commerce-gateway
    ```
  </Card>

  <Card title="Python" icon="python">
    ```bash theme={null}
    pip install betterdata-gateway
    ```

    Coming soon!
  </Card>

  <Card title="Go" icon="golang">
    ```bash theme={null}
    go get github.com/betterdata/gateway-go
    ```

    Coming soon!
  </Card>
</CardGroup>

***

## Quick Example

```typescript theme={null}
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:

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

### Success Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```bash theme={null}
GET /v1/products?limit=20&cursor=eyJpZCI6InByb2RfMTIzIn0
```

Response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6InByb2RfMTQ1In0",
    "total": 1247
  }
}
```

***

## Filtering

Use query parameters to filter results:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

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

<Card title="Webhook Events" icon="webhook" href="/api-reference/webhooks">
  View all available webhook events
</Card>

***

## API Endpoints

<CardGroup cols={2}>
  <Card title="Gateway Endpoints" icon="gateway" href="/api-reference/gateway/list-tools">
    List tools, execute tools, chat completions
  </Card>

  <Card title="Session Endpoints" icon="clock" href="/api-reference/sessions/create">
    Create, get, update, delete sessions
  </Card>

  <Card title="Integration Endpoints" icon="plug" href="/api-reference/integrations/shopify-authorize">
    Connect Shopify, Square, sync products
  </Card>

  <Card title="Analytics Endpoints" icon="chart-line" href="/api-reference/analytics/overview">
    Get metrics, attribution, conversion data
  </Card>
</CardGroup>