Admin - Podium

Overview

Admin endpoints manage platform-level configuration including API keys, organizations, subscription tiers, and the enrichment pipeline. Most require ADMIN role access.

Most developers interact with API keys and organization settings through the Podium Developer Portal. The admin API is for programmatic management and platform-level automation.

API Key Management

Create a Key

curl -X POST https://api.podium.build/api/v1/admin/api-keys \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "organizationId": "clorg_abc" }'

{
  "id": "clkey_xyz",
  "key": "podium_live_sk_abc123...",
  "organizationId": "clorg_abc",
  "isActive": true,
  "createdAt": "2026-03-07T12:00:00.000Z"
}

The full API key is only returned once at creation time. Store it securely — subsequent queries return a masked version.

List Organization Keys

curl "https://api.podium.build/api/v1/admin/api-keys?organizationId=clorg_abc" \
  -H "Authorization: Bearer $PODIUM_API_KEY"

[
  {
    "id": "clkey_xyz",
    "keyPrefix": "podium_live_sk_abc1...",
    "isActive": true,
    "lastUsedAt": "2026-03-07T11:45:00.000Z",
    "createdAt": "2026-01-15T10:00:00.000Z"
  }
]

Get Key Details

curl https://api.podium.build/api/v1/admin/api-keys/clkey_xyz \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Deactivate a Key

curl -X PATCH https://api.podium.build/api/v1/admin/api-keys/clkey_xyz \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Setting isActive: false immediately blocks all requests using this key.

Rotate a Key

curl -X POST https://api.podium.build/api/v1/admin/api-keys/clkey_xyz/rotate \
  -H "Authorization: Bearer $PODIUM_API_KEY"

{
  "id": "clkey_xyz",
  "key": "podium_live_sk_newkey456...",
  "previousKeyId": "clkey_xyz_old",
  "rotatedAt": "2026-03-07T12:00:00.000Z"
}

Key rotation:

Generates a new key value for the same key ID
Invalidates the old key value
Publishes an api-key-changed event to flush caches across all API instances
Returns the new full key (one-time display)

Delete a Key

curl -X DELETE https://api.podium.build/api/v1/admin/api-keys/clkey_xyz \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Permanently removes the key. This cannot be undone.

Organizations

List Organizations

curl https://api.podium.build/api/v1/admin/organizations \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Create an Organization

curl -X POST https://api.podium.build/api/v1/admin/organizations \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Beauty",
    "domain": "acmebeauty.com",
    "subscriptionTierId": "tier_growth"
  }'

Field	Type	Required	Description
`name`	string	Yes	Organization display name
`domain`	string	No	Organization domain
`subscriptionTierId`	string	No	Subscription tier to assign

Get Organization Details

curl https://api.podium.build/api/v1/admin/organizations/clorg_abc \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Organization Settings

Settings control organization-specific behavior like blockchain preferences, x402 configuration, and reward modes.

curl https://api.podium.build/api/v1/admin/organizations/clorg_abc/settings \
  -H "Authorization: Bearer $PODIUM_API_KEY"

{
  "organizationId": "clorg_abc",
  "x402Enabled": true,
  "x402WalletAddress": "0x...",
  "defaultChainId": 8453,
  "rewardMode": "QUEUE",
  "enrichmentEnabled": true,
  "autoPublishProducts": false
}

Update Settings

curl -X PATCH https://api.podium.build/api/v1/admin/organizations/clorg_abc/settings \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "x402Enabled": true,
    "x402WalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "defaultChainId": 8453
  }'

App Configuration

Global application configuration:

curl https://api.podium.build/api/v1/admin/app-config \
  -H "Authorization: Bearer $PODIUM_API_KEY"

curl -X PATCH https://api.podium.build/api/v1/admin/app-config \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "base-mainnet",
    "rewardMode": "QUEUE"
  }'

Subscription Tiers

List Tiers

curl https://api.podium.build/api/v1/admin/subscription-tiers \
  -H "Authorization: Bearer $PODIUM_API_KEY"

[
  {
    "id": "tier_builder",
    "name": "BUILDER",
    "price": 0,
    "monthlyApiCalls": 10000,
    "maxApiKeys": 5,
    "maxCreators": 2,
    "features": ["Core commerce endpoints"]
  },
  {
    "id": "tier_growth",
    "name": "GROWTH",
    "price": 9900,
    "monthlyApiCalls": 100000,
    "maxApiKeys": 20,
    "maxCreators": 10,
    "features": ["All endpoints", "Enrichment pipeline", "Priority support"]
  },
  {
    "id": "tier_pro",
    "name": "PRO",
    "price": 49900,
    "monthlyApiCalls": 1000000,
    "maxApiKeys": 100,
    "maxCreators": 50,
    "features": ["All endpoints", "Enrichment pipeline", "Dedicated support", "Custom integrations"]
  }
]

Get Tier Details

curl https://api.podium.build/api/v1/admin/subscription-tiers/tier_growth \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Campaign Administration

Admin-level campaign management across the organization:

List All Campaigns

curl https://api.podium.build/api/v1/admin/campaigns \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Approve or Reject a Campaign

curl -X PATCH https://api.podium.build/api/v1/admin/campaigns/clcamp_xyz/status \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "APPROVED" }'

Valid transitions: SUBMITTED → APPROVED or SUBMITTED → DRAFT (rejection).

Enrichment Pipeline

Admin endpoints for managing the enrichment pipeline.

Trigger Source Ingestion

curl -X POST https://api.podium.build/api/v1/admin/enrichment/run \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceId": "clsource_sephora" }'

Dispatches an enrichment-crawl event for the specified source. The system fetches and processes data, then queues it for AI-powered extraction.

Ingest Products from a Domain

curl -X POST https://api.podium.build/api/v1/admin/enrichment/crawl-domain \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "sephora.com",
    "limit": 50,
    "crawlMode": false
  }'

Field	Type	Description
`domain`	string	Domain to discover product pages from
`limit`	number	Max pages to process (optional)
`crawlMode`	boolean	`true` for deep crawl, `false` (default) for map-and-scrape

Discover Product URLs on a Domain

Dry-run endpoint to preview which product URLs Podium would find on a domain, without ingesting anything:

curl -X POST https://api.podium.build/api/v1/admin/enrichment/map-domain \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "sephora.com", "search": "moisturizer", "limit": 20 }'

Trigger Product Discovery

Discover and ingest products from shopping search results. Provide specific queries, filter by category, or omit both to run the full discovery catalog:

curl -X POST https://api.podium.build/api/v1/admin/enrichment/serp-search \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "skincare",
    "maxPages": 3
  }'

Field	Type	Description
`queries`	string[]	Specific search queries (optional)
`category`	string	Filter by product category (optional)
`maxPages`	number	Max result pages per query (optional)

Discovery Catalog Stats

View the discovery query catalog — how many queries are available per category:

curl https://api.podium.build/api/v1/admin/enrichment/serp-catalog \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Recompute Baselines

curl -X POST https://api.podium.build/api/v1/admin/enrichment/baseline/recompute \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "clprod_abc123" }'

Omit productId to recompute all stale baselines. For immediate (synchronous) recomputation:

curl -X POST https://api.podium.build/api/v1/admin/enrichment/baseline/recompute-now \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Baseline Statistics

View detailed statistics across all three baseline levels (product, category, market):

curl https://api.podium.build/api/v1/admin/enrichment/baseline/stats \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Pipeline Status

curl https://api.podium.build/api/v1/admin/enrichment/status \
  -H "Authorization: Bearer $PODIUM_API_KEY"

{
  "sources": [
    { "id": "...", "name": "Sephora Pages", "sourceType": "WEB_PAGE", "lastRunAt": "...", "lastRunStatus": "SUCCESS" }
  ],
  "signalCount": 45230,
  "rawRecordCount": 12400,
  "baselines": {
    "product": 3200,
    "category": 45,
    "market": 13,
    "total": 3258
  }
}

Catalog Sync

Sync enrichment data into the companion product catalog. Creates ProductCatalogItem records from enrichment raw records:

curl -X POST https://api.podium.build/api/v1/admin/enrichment/catalog-sync \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Reprocess Unprocessed Records

Re-queue all unprocessed raw records for AI-powered attribute extraction:

curl -X POST https://api.podium.build/api/v1/admin/enrichment/reprocess \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Manage Enrichment Sources

Create a Source

curl -X POST https://api.podium.build/api/v1/admin/enrichment/sources \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sephora Product Pages",
    "sourceType": "WEB_PAGE",
    "config": {
      "domain": "sephora.com",
      "categories": ["skincare", "makeup"]
    }
  }'

List Sources

curl https://api.podium.build/api/v1/admin/enrichment/sources \
  -H "Authorization: Bearer $PODIUM_API_KEY"

Enrichment Endpoint Summary

Method	Path	Description
`POST`	`/admin/enrichment/run`	Trigger ingestion for a specific source
`POST`	`/admin/enrichment/crawl-domain`	Ingest products from a domain
`POST`	`/admin/enrichment/map-domain`	Discover product URLs on a domain (dry run)
`POST`	`/admin/enrichment/serp-search`	Trigger product discovery
`GET`	`/admin/enrichment/serp-catalog`	View discovery query catalog stats
`POST`	`/admin/enrichment/baseline/recompute`	Queue baseline recomputation
`POST`	`/admin/enrichment/baseline/recompute-now`	Synchronous baseline recomputation
`GET`	`/admin/enrichment/baseline/stats`	Detailed baseline statistics
`POST`	`/admin/enrichment/catalog-sync`	Sync enrichment data to companion catalog
`POST`	`/admin/enrichment/reprocess`	Re-queue unprocessed records for extraction
`GET`	`/admin/enrichment/status`	Pipeline dashboard
`POST`	`/admin/enrichment/sources`	Create a new enrichment source
`GET`	`/admin/enrichment/sources`	List all enrichment sources

Task Administration

Endpoint	Description
`GET /admin/tasks/pending-review`	Tasks flagged for manual review
`POST /admin/tasks/{taskId}/resolve`	Manual approval/rejection
`POST /admin/tasks/{taskId}/retry-verification`	Retry failed oracle verification

curl https://api.podium.build/api/v1/admin/tasks/pending-review \
  -H "Authorization: Bearer $PODIUM_API_KEY"

curl -X POST https://api.podium.build/api/v1/admin/tasks/0xabc123.../resolve \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true }'

See Task Pool API for details.

Endpoint Summary

Method	Path	Description
`POST`	`/admin/api-keys`	Create API key
`GET`	`/admin/api-keys`	List keys
`GET`	`/admin/api-keys/{id}`	Get key (masked)
`PATCH`	`/admin/api-keys/{id}`	Activate/deactivate
`DELETE`	`/admin/api-keys/{id}`	Delete key
`POST`	`/admin/api-keys/{id}/rotate`	Rotate key
`GET`	`/admin/organizations`	List organizations
`POST`	`/admin/organizations`	Create organization
`GET`	`/admin/organizations/{id}`	Get organization
`GET`	`/admin/organizations/{id}/settings`	Get settings
`PATCH`	`/admin/organizations/{id}/settings`	Update settings
`GET`	`/admin/app-config`	Get app config
`PATCH`	`/admin/app-config`	Update app config
`GET`	`/admin/subscription-tiers`	List tiers
`GET`	`/admin/subscription-tiers/{id}`	Get tier
`GET`	`/admin/campaigns`	List campaigns
`PATCH`	`/admin/campaigns/{id}/status`	Approve/reject campaign
`POST`	`/admin/enrichment/run`	Trigger crawl
`POST`	`/admin/enrichment/baseline/recompute`	Recompute baselines
`GET`	`/admin/enrichment/status`	Pipeline status
`POST`	`/admin/enrichment/sources`	Create source
`GET`	`/admin/enrichment/sources`	List sources
`GET`	`/admin/tasks/pending-review`	Tasks for review
`POST`	`/admin/tasks/{taskId}/resolve`	Resolve task
`POST`	`/admin/tasks/{taskId}/retry-verification`	Retry verification

Overview

Intelligence & Agents

Commerce

Users & Engagement

Platform

​Overview

​API Key Management

​Create a Key

​List Organization Keys

​Get Key Details

​Deactivate a Key

​Rotate a Key

​Delete a Key

​Organizations

​List Organizations

​Create an Organization

​Get Organization Details

​Organization Settings

​Update Settings

​App Configuration

​Subscription Tiers

​List Tiers

​Get Tier Details

​Campaign Administration

​List All Campaigns

​Approve or Reject a Campaign

​Enrichment Pipeline

​Trigger Source Ingestion

​Ingest Products from a Domain

​Discover Product URLs on a Domain

​Trigger Product Discovery

​Discovery Catalog Stats

​Recompute Baselines

​Baseline Statistics

​Pipeline Status

​Catalog Sync

​Reprocess Unprocessed Records

​Manage Enrichment Sources

​Create a Source

​List Sources

​Enrichment Endpoint Summary

​Task Administration

​Endpoint Summary

Overview

API Key Management

Create a Key

List Organization Keys

Get Key Details

Deactivate a Key

Rotate a Key

Delete a Key

Organizations

List Organizations

Create an Organization

Get Organization Details

Organization Settings

Update Settings

App Configuration

Subscription Tiers

List Tiers

Get Tier Details

Campaign Administration

List All Campaigns

Approve or Reject a Campaign

Enrichment Pipeline

Trigger Source Ingestion

Ingest Products from a Domain

Discover Product URLs on a Domain

Trigger Product Discovery

Discovery Catalog Stats

Recompute Baselines

Baseline Statistics

Pipeline Status

Catalog Sync

Reprocess Unprocessed Records

Manage Enrichment Sources

Create a Source

List Sources

Enrichment Endpoint Summary

Task Administration

Endpoint Summary