Skip to main content

​
Base URLs

EnvironmentBase URL
Productionhttps://api.podium.build/api/v1
Staginghttps://podium-staging.up.railway.app/api/v1
Localhttp://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

StatusMeaning
200Success — resource returned
201Created — new resource
204No content — successful deletion

​
Error Responses

Errors return a consistent shape: 
{
  "status": 422,
  "error": "Validation failed",
  "details": [
    {
      "field": "price",
      "message": "Expected number, received string"
    }
  ]
}
StatusMeaning
400Bad request — malformed input
401Unauthorized — missing or invalid API key
402Payment required — x402 crypto payment needed
403Forbidden — insufficient subscription tier or role
404Not found
409Conflict — duplicate resource
422Validation error — request body failed schema validation
429Rate limited — retry after the indicated delay
500Internal server error

​
Pagination

Collection endpoints support offset-based pagination:
ParameterTypeDefaultDescription
limitinteger20Items per page (1–100)
offsetinteger0Number 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:
MethodEndpointDescription
GET/companion/agent/chat/history/:userIdRetrieve full chat history for a user’s agent conversation
GET/companion/creator/:handle/productsList products curated by a specific creator persona
POST/companion/profile/:userId/seed-from-creatorSeed a user’s preference profile from a creator’s taste graph
POST/companion/subscription/checkoutCreate a Stripe Checkout session for a subscription plan
POST/companion/subscription/portalGenerate a Stripe Customer Portal link for subscription management
GET/companion/subscription/status/:userIdCheck 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:
EventDescription
memory_queuedA preference has been extracted and queued for memory storage
confirmation_requiredThe agent is asking the user to confirm before proceeding (e.g., high-value purchase)
spend_limit_exceededThe 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