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

# HTTP API design

> The design principles behind the Pocketsflow HTTP API and how it complements webhooks.

<Note>
  **The HTTP API is live.** For the real, current endpoints see the
  [API reference](/api-reference/introduction) and the interactive docs at
  [api.pocketsflow.com/docs](https://api.pocketsflow.com/docs) (OpenAPI JSON at
  [`/docs.json`](https://api.pocketsflow.com/docs.json)). This page explains the
  design principles so you know what to expect as you build.
</Note>

Pocketsflow exposes both webhooks and a REST HTTP API. The API is REST-style
with predictable, resource-based URLs, standard HTTP methods (`GET`, `POST`,
`PUT`, `DELETE`), and JSON request/response bodies.

## Conventions

* **Base URL:** `https://api.pocketsflow.com` — no version prefix in the path
  today.
* **Authentication:** `Authorization: Bearer <token>` over HTTPS, using an API
  key (`pk_live_…` / `pk_test_…`) or an Auth0 JWT.
* **Test vs live:** the key prefix (and your account mode) selects sandbox vs
  real data; the same endpoints serve both.
* **Content type:** JSON everywhere except image upload (`multipart/form-data`).
* **Pagination:** page-based (`page`/`pageSize` → a `pagination` envelope) or
  offset-based (`limit`/`offset`), depending on the resource.
* **Errors:** standard HTTP status codes with a JSON `error` message.

See [API reference → Making requests](/api-reference/introduction#making-requests)
for the full details on pagination, errors, and rate limits.

## Resource areas

The API covers, among others:

* **Products** and **Checkout** — create products and hosted checkout sessions.
* **Orders** and **Payments** — the sales ledger, including the unified
  [payments](/api-reference/introduction#payments) resource that spans one-time
  purchases and subscription renewals.
* **Subscriptions & Subscribers** — subscription offers plus the
  [subscribers](/api-reference/introduction#subscriptions-and-subscribers) who buy
  them, with live status and payment history.
* **Customers**, **Discounts**, **Upsells**, **Refunds**, **Reviews**.
* **Webhooks** — register and manage event endpoints.
* **Newsletters**, **Link in Bio**, **Images**, **Partners**, **Account**.

## Backwards compatibility

The API evolves additively:

* New fields may be added to responses at any time — treat unknown fields as
  optional and don't hard-code assumptions about field order.
* New endpoints and event types are introduced without breaking existing ones.
* Avoid depending on undocumented fields.

## Relationship to webhooks

Webhooks and the HTTP API are complementary:

* **Webhooks** push events to you when something happens (for example
  `order.completed`).
* The **HTTP API** lets you query and mutate data on demand.

The typical pattern: receive a webhook, then call the API to fetch additional
detail or take a follow-up action — and reconcile via the API so a missed
delivery self-heals.

## Related topics

* [API reference](/api-reference/introduction)
* [Webhooks & API overview](/api-webhooks/overview)
* [Webhook events](/api-webhooks/events)