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

# REST API Overview

> Complete guide to the Stigg REST API including authentication, common patterns, rate limits, and error handling

The Stigg REST API provides a RESTful interface for integrating with Stigg's pricing and entitlement platform. This guide covers everything you need to get started.

<Note>
  The REST API is currently in **Public Beta**.
</Note>

## Base URL

All API requests should be made to:

```
https://api.stigg.io/api/v1
```

## Authentication

All API requests require authentication using an API key. Include your API key in the `X-API-KEY` header with every request.

### Getting your API key

1. Log in to the [Stigg app](https://app.stigg.io)
2. Navigate to **Integrations > API Keys**
3. Copy your Full Access API Key

<Warning>
  Keep your API key secure and never expose it in client-side code. Use environment variables to store your key.
</Warning>

### Authentication example

```bash theme={null}
curl -X GET "https://api.stigg.io/api/v1/customers/{id}" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json"
```

## Common Patterns

### Request format

All requests should include the `Content-Type: application/json` header when sending a request body.

```bash theme={null}
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }'
```

### Response format

All responses are returned in JSON format with consistent structure:

**Successful response:**

```json theme={null}
{
  "id": "customer-123",
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

### Pagination

List endpoints support cursor-based pagination using the following query parameters:

| Parameter        | Type    | Description                                               |
| ---------------- | ------- | --------------------------------------------------------- |
| `limit`          | integer | Maximum number of items to return (default: 20, max: 100) |
| `starting_after` | string  | Cursor for forward pagination (item ID to start after)    |
| `ending_before`  | string  | Cursor for backward pagination (item ID to end before)    |

**Paginated response structure:**

```json theme={null}
{
  "data": [...],
  "has_more": true,
  "next_cursor": "cus_abc123"
}
```

**Example: Fetching paginated results**

```bash theme={null}
# First page
curl -X GET "https://api.stigg.io/api/v1/customers?limit=10" \
  -H "X-API-KEY: your-api-key"

# Next page
curl -X GET "https://api.stigg.io/api/v1/customers?limit=10&starting_after=cus_abc123" \
  -H "X-API-KEY: your-api-key"
```

### Filtering

List endpoints support filtering using query parameters specific to each resource:

```bash theme={null}
# Filter customers by email
curl -X GET "https://api.stigg.io/api/v1/customers?email=user@example.com" \
  -H "X-API-KEY: your-api-key"

# Filter subscriptions by status
curl -X GET "https://api.stigg.io/api/v1/subscriptions?status=active" \
  -H "X-API-KEY: your-api-key"
```

### Idempotency

For POST requests, you can include an `Idempotency-Key` header to ensure the operation is only performed once, even if the request is retried:

```bash theme={null}
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "id": "customer-123",
    "name": "Acme Corp"
  }'
```

Idempotency keys are stored for 24 hours. Repeated requests with the same key will return the cached response.

## Error Handling

The API uses standard HTTP status codes and returns detailed error information in a consistent format.

| Status | Meaning                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------ |
| `200`  | Success — request completed, body contains the resource                                                |
| `201`  | Created — resource was successfully provisioned                                                        |
| `400`  | Bad request — invalid parameters or request body                                                       |
| `401`  | Unauthenticated — missing or invalid `X-API-KEY`                                                       |
| `403`  | Forbidden — authenticated but not authorized for this resource                                         |
| `404`  | Not found — the specified resource does not exist                                                      |
| `409`  | Conflict — e.g. a subscription already exists for this customer                                        |
| `429`  | Too many requests — rate limit exceeded; see [Rate Limits](/api-and-sdks/integration/rest/rate-limits) |

## Known Limitations

### Subscription list endpoint does not return entitlements

`GET /api/v1/subscriptions` does not include `subscriptionEntitlements` in its response. Returning full entitlement data for every subscription in a paginated list would be prohibitively expensive at scale. To retrieve entitlements for a specific subscription, use `GET /api/v1/subscriptions/{id}`. To retrieve the full entitlements defined on a plan, use `GET /api/v1/plans/{id}`.

### Subscription entitlements are overrides only

The `subscriptionEntitlements` field on `GET /api/v1/subscriptions/{id}` contains only **subscription-level overrides** (type and ID), not the full set of entitlements inherited from the plan. To retrieve all entitlements for a plan, use `GET /api/v1/plans/{planId}/entitlements`.