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

# API Reference

> Complete reference documentation for Firmly APIs

## Base URL

All API requests are made to:

```
https://api.firmly.work
```

## Authentication

All endpoints require authentication via the `x-firmly-authorization` header:

```bash theme={null}
curl -X GET https://api.firmly.work/api/v2/domains/staging.luma.gift/cart \
  -H "x-firmly-authorization: YOUR_ACCESS_TOKEN"
```

See [Authentication](/api-reference/authentication/browser-session) for obtaining access tokens.

## Request Format

* **Content-Type**: `application/json` for all POST/PUT requests
* **Accept**: `application/json`
* **Domain Parameter**: Most endpoints require a merchant domain (e.g., `staging.luma.gift`)

## Response Format

All responses return JSON with consistent structure:

### Success Response

```json theme={null}
{
  "cart_id": "cart_123",
  "line_items": [...],
  "total": { "value": 99.99, "currency": "USD" }
}
```

### Error Response

```json theme={null}
{
  "code": 400,
  "error": "ErrorCode",
  "description": "Human-readable error message"
}
```

## HTTP Status Codes

| Status | Description                              |
| ------ | ---------------------------------------- |
| 200    | Success                                  |
| 400    | Bad Request - Invalid parameters         |
| 401    | Unauthorized - Invalid or missing token  |
| 404    | Not Found - Resource doesn't exist       |
| 409    | Conflict - Business logic error          |
| 422    | Unprocessable Entity - Validation failed |
| 500    | Internal Server Error                    |

## API Versioning

Firmly provides two API versions:

* **v1** - Simple Cart API endpoints
* **v2** - Full Cart API endpoints

Version is specified in the URL path: `/api/v1/` or `/api/v2/`

## Available APIs

<CardGroup cols={2}>
  <Card title="Authentication" href="/api-reference/authentication/browser-session" icon="key">
    Token generation and session management
  </Card>

  <Card title="Catalog" href="/api-reference/catalog/overview" icon="box">
    Browse products and retrieve variant information
  </Card>

  <Card title="Session" href="/api-reference/session/overview" icon="user">
    Manage device sessions and preferences
  </Card>

  <Card title="Cart Management" href="/api-reference/cart-management/overview" icon="shopping-cart">
    Core cart operations for Full Cart API
  </Card>

  <Card title="Simple Cart" href="/api-reference/simple-cart-api/cart/get-cart" icon="shopping-bag">
    Streamlined cart operations for standard shipping
  </Card>

  <Card title="Promotions" href="/api-reference/promotions/overview" icon="tag">
    Apply and manage promotional codes
  </Card>

  <Card title="Shipment Configuration" href="/api-reference/shipment-configuration/overview" icon="truck">
    Configure fulfillment and shipping methods
  </Card>

  <Card title="Addon Management" href="/api-reference/addon-management/overview" icon="plus">
    Manage warranties and protection plans
  </Card>

  <Card title="Checkout" href="/api-reference/checkout/overview" icon="credit-card">
    Complete the purchase flow
  </Card>

  <Card title="Payment" href="/api-reference/payment/get-public-key" icon="lock">
    Secure payment processing
  </Card>
</CardGroup>

## Common Headers

### Required Headers

| Header                   | Description                      | Example             |
| ------------------------ | -------------------------------- | ------------------- |
| `x-firmly-authorization` | Access token from authentication | `Bearer eyJhbGc...` |

### Optional Headers

| Header                | Description                            | Example      |
| --------------------- | -------------------------------------- | ------------ |
| `x-firmly-request-id` | Unique request identifier for tracking | `req_123abc` |

## Rate Limits

Contact support for current rate limit information.

## Support

* **API Status**: [status.firmly.work](https://status.firmly.work)
* **Support**: [support@firmly.work](mailto:support@firmly.work)

## Need Implementation Help?

<Card title="Implementation Guides" icon="rocket" href="/guides/choosing-your-api">
  Step-by-step guides for building with Firmly APIs
</Card>