> ## 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 Overview

> Overview of the Better Data SCM tenant-facing API

# API Overview

The Better Data SCM API provides programmatic access to forecasting, inventory, transfers, alerts, and catalog management. All APIs are tenant-scoped and require authentication.

<Warning>
  **Scope**: This documentation covers tenant-facing APIs only. SuperAdmin endpoints (tenant provisioning, entitlements, billing overrides) are excluded. Internal cron endpoints are also excluded unless they're tenant-configurable.
</Warning>

## Base URL

All API requests should be made to:

```
https://app.betterdata.co/api
```

## API Groups

The API is organized into logical groups:

<CardGroup cols={2}>
  <Card title="Forecasting API" icon="chart-line" href="/api-reference/forecasting">
    Forecast scenarios, events, accuracy metrics, and channel projections
  </Card>

  <Card title="Inventory API" icon="package" href="/api-reference/inventory">
    Inventory levels, analytics, channel-location ATP, and cycle counts
  </Card>

  <Card title="Transfers API" icon="arrow-right-left" href="/api-reference/transfers">
    Transfer recommendations, approval, and execution
  </Card>

  <Card title="Alerts API" icon="bell" href="/api-reference/alerts">
    Alert configuration, history, and triggering
  </Card>

  <Card title="Catalog API" icon="box" href="/api-reference/catalog">
    Products, categories, attributes, and taxonomies
  </Card>
</CardGroup>

## Authentication

All API requests require authentication. See [Authentication](/api-reference/authentication) for details.

**Quick Start:**

1. Obtain an API key from **Admin** → **Integrations** → **API Keys**
2. Include the API key in the `Authorization` header:
   ```
   Authorization: Bearer YOUR_API_KEY
   ```
3. Ensure your API key has the required permissions for the endpoints you're using

## Request Format

### Headers

All requests must include:

```
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

### Request Body

POST and PUT requests should include a JSON body:

```json theme={null}
{
  "field1": "value1",
  "field2": "value2"
}
```

## Response Format

### Success Response

Successful responses return a JSON body with the requested data:

```json theme={null}
{
  "data": { ... },
  "pagination": { ... }
}
```

### Error Response

Error responses include an error message and details:

```json theme={null}
{
  "error": "Error message",
  "details": { ... }
}
```

### HTTP Status Codes

* `200 OK`: Request successful
* `201 Created`: Resource created successfully
* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Authentication required or invalid
* `403 Forbidden`: Insufficient permissions
* `404 Not Found`: Resource not found
* `409 Conflict`: Resource conflict (e.g., duplicate)
* `500 Internal Server Error`: Server error

## Rate Limits

API requests are rate-limited to prevent abuse. See [Rate Limits](/api-reference/rate-limits) for details.

**Default Limits:**

* **100 requests per minute** per API key
* **1000 requests per hour** per API key

Rate limit headers are included in all responses:

* `X-RateLimit-Limit`: Maximum requests allowed
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Time when rate limit resets

## Pagination

List endpoints support pagination:

**Query Parameters:**

* `page`: Page number (default: 1)
* `limit`: Items per page (default: 20, max: 100)

**Response:**

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

## Filtering and Sorting

Many list endpoints support filtering and sorting:

**Filtering:**

* Use query parameters to filter results
* Example: `?status=ACTIVE&locationId=loc_123`

**Sorting:**

* Use `sortBy` and `sortOrder` query parameters
* Example: `?sortBy=createdAt&sortOrder=desc`

## Common Errors

See [Common Errors](/api-reference/errors) for detailed error handling guidance.

**Common Error Codes:**

* `UNAUTHORIZED`: Authentication required
* `FORBIDDEN`: Insufficient permissions
* `VALIDATION_ERROR`: Invalid request parameters
* `NOT_FOUND`: Resource not found
* `CONFLICT`: Resource conflict

## Beta Endpoints

Some endpoints are marked as **Beta** and may change without notice. Beta endpoints are indicated with a warning callout in their documentation.

<Warning>
  **Beta**: This endpoint is in beta and may change. Use with caution.
</Warning>

## Getting Started

1. **Get an API Key**: Create an API key in **Admin** → **Integrations** → **API Keys**
2. **Read Authentication Guide**: See [Authentication](/api-reference/authentication)
3. **Explore API Groups**: Browse the API groups above
4. **Try Example Requests**: Each API group includes example requests

## API Versioning

The API is currently at version 1.0. Future versions will be indicated in the URL path (e.g., `/api/v2/...`).

## Support

For API support:

* **Email**: [support@betterdata.co](mailto:support@betterdata.co)
* **Documentation**: This documentation site
* **Issues**: Report issues through your organization's support channel

***

## Related Pages

* [Authentication](/api-reference/authentication)
* [Common Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)

***

## Permissions & Roles

<Tip>
  API access requires an API key with appropriate permissions. Contact your organization administrator to create an API key.
</Tip>