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

# API Reference

> Base URLs, authentication, error handling, pagination, and conventions for the Podium REST API

## Base URLs

| Environment    | Base URL                                       |
| -------------- | ---------------------------------------------- |
| **Production** | `https://api.podium.build/api/v1`              |
| **Staging**    | `https://podium-staging.up.railway.app/api/v1` |
| **Local**      | `http://localhost:3030/api/v1`                 |

All endpoints are prefixed with `/api/v1`. The interactive API playground is available at [api.podium.build/docs](https://api.podium.build/docs).

## Authentication

Most endpoints require a Bearer token:

```bash theme={null}
curl -X GET https://api.podium.build/api/v1/products \
  -H "Authorization: Bearer podium_live_your_key_here"
```

Keys prefixed with `podium_test_` route to staging; `podium_live_` routes to production. See [Authentication](/docs/platform/authentication) for details on key management, subscription tiers, and rate limiting.

### Public Endpoints

Some endpoints require no authentication:

* `/agentic/*` — AI agent product discovery and checkout
* `/webhooks/*` — Inbound webhook handlers
* `/solver/*` — Solver discovery for Task Pool

## Request Format

All request bodies use JSON with `Content-Type: application/json`. Every endpoint validates its input with Zod schemas — invalid requests return a 422 with field-level error details.

```bash theme={null}
curl -X POST https://api.podium.build/api/v1/product \
  -H "Authorization: Bearer podium_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Organic Face Serum",
    "price": 2500,
    "currency": "USD",
    "description": "Lightweight hydrating serum"
  }'
```

## Response Format

Successful responses return JSON. Single resources return the object directly; collections return arrays. All responses include standard HTTP status codes.

### Success Responses

| Status | Meaning                          |
| ------ | -------------------------------- |
| `200`  | Success — resource returned      |
| `201`  | Created — new resource           |
| `204`  | No content — successful deletion |

### Error Responses

Errors return a consistent shape:

```json theme={null}
{
  "status": 422,
  "error": "Validation failed",
  "details": [
    {
      "field": "price",
      "message": "Expected number, received string"
    }
  ]
}
```

| Status | Meaning                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | Bad request — malformed input                            |
| `401`  | Unauthorized — missing or invalid API key                |
| `402`  | Payment required — x402 crypto payment needed            |
| `403`  | Forbidden — insufficient subscription tier or role       |
| `404`  | Not found                                                |
| `409`  | Conflict — duplicate resource                            |
| `422`  | Validation error — request body failed schema validation |
| `429`  | Rate limited — retry after the indicated delay           |
| `500`  | Internal server error                                    |

## Pagination

Collection endpoints support offset-based pagination:

| Parameter | Type    | Default | Description             |
| --------- | ------- | ------- | ----------------------- |
| `limit`   | integer | 20      | Items per page (1–100)  |
| `offset`  | integer | 0       | Number of items to skip |

```bash theme={null}
GET /api/v1/products?limit=10&offset=20
```

## IDs

Podium uses [CUID2](https://github.com/paralleldrive/cuid2) for all entity IDs. These are collision-resistant, URL-safe, and sortable by creation time.

```
clxyz1234567890abcdef  # Example CUID2
```

## Companion & Intelligence Endpoints

Recent additions to the Companion API surface:

| Method | Endpoint                                       | Description                                                        |
| ------ | ---------------------------------------------- | ------------------------------------------------------------------ |
| `GET`  | `/companion/agent/chat/history/:userId`        | Retrieve full chat history for a user's agent conversation         |
| `GET`  | `/companion/creator/:handle/products`          | List products curated by a specific creator persona                |
| `POST` | `/companion/profile/:userId/seed-from-creator` | Seed a user's preference profile from a creator's taste graph      |
| `POST` | `/companion/subscription/checkout`             | Create a Stripe Checkout session for a subscription plan           |
| `POST` | `/companion/subscription/portal`               | Generate a Stripe Customer Portal link for subscription management |
| `GET`  | `/companion/subscription/status/:userId`       | Check a user's current subscription tier and usage limits          |

### SSE Events

The conversational agent endpoint (`POST /companion/agent/chat`) streams Server-Sent Events. In addition to `message` and `done`, the following event types may appear:

| Event                   | Description                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `memory_queued`         | A preference has been extracted and queued for memory storage                         |
| `confirmation_required` | The agent is asking the user to confirm before proceeding (e.g., high-value purchase) |
| `spend_limit_exceeded`  | The requested action exceeds the user's configured spend limit                        |

## Endpoint Groups

The API is organized into these groups:

<CardGroup cols={2}>
  <Card title="Products" icon="box" href="/docs/api-reference/products">
    Product CRUD, attributes, media, categories
  </Card>

  <Card title="Creators" icon="store" href="/docs/api-reference/creators">
    Creator profiles, storefronts, orders, payouts
  </Card>

  <Card title="Users" icon="user" href="/docs/api-reference/users">
    User profiles, wallets, following, notifications
  </Card>

  <Card title="Orders" icon="receipt" href="/docs/api-reference/orders">
    Order lifecycle, checkout, shipping
  </Card>

  <Card title="Payments" icon="credit-card" href="/docs/api-reference/payments">
    Stripe, x402, Coinbase, embedded wallet
  </Card>

  <Card title="Points" icon="coins" href="/docs/api-reference/points">
    Points ledger, earning, spending, history
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/docs/api-reference/campaigns">
    Swipe, vote, survey, UGC campaigns
  </Card>

  <Card title="Rewards & Airdrops" icon="gem" href="/docs/api-reference/nfts">
    On-chain rewards, minting, airdrops, redemption
  </Card>

  <Card title="Companion" icon="robot" href="/docs/api-reference/companion">
    Intent profiles, interactions, recommendations
  </Card>

  <Card title="Task Pool" icon="list-check" href="/docs/api-reference/task-pool-api">
    Tasks, pools, solvers, verification
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/docs/api-reference/search">
    Full-text search, autocomplete, discovery
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/api-reference/webhooks">
    Stripe, Shopify, Privy, internal events
  </Card>
</CardGroup>