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

# ABConvert API Reference Overview

> A complete guide to the ABConvert API — two endpoint categories, standard response shapes, rate limits, and links to authentication details.

<Note>
  **Preview — this page is an early draft.** We're still verifying the API reference against the current endpoints. Fields, response shapes, and examples may change before this section is marked stable. Follow [PRO-1459](https://linear.app/abconvert/issue/PRO-1459) or ask in `#abconvert-dev` if you're integrating against this today.
</Note>

The ABConvert API gives you programmatic access to experiment management, analytics reporting, and storefront event tracking. All endpoints are served from a single base URL and are organized into two categories depending on who is calling them and why.

## Base URL

```
https://app.abconvert.io
```

All paths below are relative to this base URL.

## Endpoint categories

### Session endpoints

Session endpoints handle everything inside the ABConvert admin panel: creating and managing experiments, pulling analytics, managing billing, and configuring app settings. Every session endpoint requires a valid Shopify session established when your store installs ABConvert. The app handles this automatically — you do not need to manage tokens yourself.

Path prefix: `/api/` (no `/public/` segment, accessible only from authenticated app context)

Examples:

* `GET /api/experiments` — list all experiments
* `POST /api/price-experiments/v1/create` — create a price experiment
* `POST /api/analytics/:experimentId` — fetch experiment analytics

### Public endpoints

Public endpoints are designed for storefront integration. They require no authentication and are called directly from your store's browser context — either automatically by the ABConvert tracking script and Web Pixel extension, or by custom integrations you build.

Path prefix: `/api/public/*` or direct `/api/*` tracking paths

Examples:

* `GET /api/observe` — track a product page view
* `POST /api/track/event` — record a behavioral event
* `GET /api/get-session` — generate a visitor session ID

<Note>
  If you are using ABConvert through the standard Shopify app installation, the tracking script and Web Pixel handle all public endpoint calls for you. You only need to call public endpoints directly when building a custom integration.
</Note>

## Standard response formats

Most session endpoints follow a consistent envelope:

```json theme={null}
// Success
{
  "status": "success",
  "data": { }
}

// Error
{
  "status": "error",
  "message": "Error description"
}
```

Some endpoints (particularly experiment actions) return a plain string on success:

```json theme={null}
"success"
```

The unified tracking endpoints (`/api/track/*`) return a minimal acknowledgement:

```json theme={null}
// 202 Accepted
{ "accepted": true }
```

## HTTP status codes

| Code  | Meaning                                                         |
| ----- | --------------------------------------------------------------- |
| `200` | Request succeeded                                               |
| `202` | Accepted (tracking endpoints)                                   |
| `400` | Bad request — invalid or missing parameters                     |
| `401` | Unauthorized — session authentication failed                    |
| `404` | Not found — resource does not exist or feature flag is disabled |
| `500` | Internal server error                                           |

## Rate limiting

ABConvert applies rate limiting primarily at the Shopify API layer rather than at the ABConvert API layer itself:

* **Product queries**: throttled to 1 request per second to respect Shopify API limits
* **Bulk operations**: queued and throttled to prevent Shopify API exhaustion
* **Webhook processing**: queued and processed asynchronously
* **Analytics endpoints**: no explicit rate limit — responses are cached
* **Public tracking endpoints**: optimized for high throughput; designed to handle Web Pixel call volume without throttling

## Authentication

See the [Authentication](/api-reference/authentication) page for details on session headers and how the `x-api-key` header is used for internal admin tools.