API Reference

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.

Authentication

Most endpoints require a Bearer token:

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 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.

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:

{
  "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

GET /api/v1/products?limit=10&offset=20

IDs

Podium uses 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:

Products

Product CRUD, attributes, media, categories

Creators

Creator profiles, storefronts, orders, payouts

Users

User profiles, wallets, following, notifications

Orders

Order lifecycle, checkout, shipping

Payments

Stripe, x402, Coinbase, embedded wallet

Points

Points ledger, earning, spending, history

Campaigns

Swipe, vote, survey, UGC campaigns

Rewards & Airdrops

On-chain rewards, minting, airdrops, redemption

Companion

Intent profiles, interactions, recommendations

Task Pool

Tasks, pools, solvers, verification

Search

Full-text search, autocomplete, discovery

Webhooks

Stripe, Shopify, Privy, internal events

Overview

Intelligence & Agents

Commerce

Users & Engagement

Platform

Base URLs

Authentication

Public Endpoints

Request Format

Response Format

Success Responses

Error Responses

IDs

Companion & Intelligence Endpoints

SSE Events

Endpoint Groups

Products

Creators

Users

Orders

Payments

Points

Campaigns

Rewards & Airdrops

Companion

Task Pool

Search

Webhooks

​Base URLs

​Authentication

​Public Endpoints

​Request Format

​Response Format

​Success Responses

​Error Responses

​Pagination

​IDs

​Companion & Intelligence Endpoints

​SSE Events

​Endpoint Groups

Products

Creators

Users

Orders

Payments

Points

Campaigns

Rewards & Airdrops

Companion

Task Pool

Search

Webhooks

Base URLs

Authentication

Public Endpoints

Request Format

Response Format

Success Responses

Error Responses

Pagination

IDs

Companion & Intelligence Endpoints

SSE Events

Endpoint Groups