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

# Admin

> API key management, organization settings, subscription tiers, and enrichment pipeline administration

## Overview

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

<Note>
  Most developers interact with API keys and organization settings through the [Podium Developer Portal](https://app.podium.build/onboarding). The admin API is for programmatic management and platform-level automation.
</Note>

## API Key Management

### Create a Key

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```typescript SDK theme={null}
  import { createPodiumClient } from '@podium-sdk/node-sdk';
  const client = createPodiumClient({ apiKey: process.env.PODIUM_API_KEY });
  const key = await client.apiKeys.create({
    requestBody: { organizationId: 'clorg_abc' }
  });
  ```
</CodeGroup>

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

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

### List Organization Keys

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.podium.build/api/v1/admin/api-keys?organizationId=clorg_abc" \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const keys = await client.apiKeys.list({ organizationId: 'clorg_abc' });
  ```
</CodeGroup>

```json theme={null}
[
  {
    "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

```bash theme={null}
curl https://api.podium.build/api/v1/admin/api-keys/clkey_xyz \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

### Deactivate a Key

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript SDK theme={null}
  await client.apiKeys.update({
    id: 'clkey_xyz',
    requestBody: { isActive: false }
  });
  ```
</CodeGroup>

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

### Rotate a Key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.podium.build/api/v1/admin/api-keys/clkey_xyz/rotate \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const rotated = await client.apiKeys.createRotate({ id: 'clkey_xyz' });
  ```
</CodeGroup>

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

Key rotation:

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

### Delete a Key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.podium.build/api/v1/admin/api-keys/clkey_xyz \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  await client.apiKeys.delete({ id: 'clkey_xyz' });
  ```
</CodeGroup>

Permanently removes the key. This cannot be undone.

## Organizations

### List Organizations

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/organizations \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const orgs = await client.organizations.list();
  ```
</CodeGroup>

### Create an Organization

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript SDK theme={null}
  const org = await client.organizations.create({
    requestBody: {
      name: 'Acme Beauty',
      domain: 'acmebeauty.com',
      subscriptionTierId: 'tier_growth'
    }
  });
  ```
</CodeGroup>

| 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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/organizations/clorg_abc \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const org = await client.organizations.get({ id: 'clorg_abc' });
  ```
</CodeGroup>

### Organization Settings

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/organizations/clorg_abc/settings \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const org = await client.organizations.get({ id: 'clorg_abc' });
  ```
</CodeGroup>

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

### Update Settings

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```typescript SDK theme={null}
  await client.organizations.updateSettings({
    id: 'clorg_abc',
    requestBody: {
      x402Enabled: true,
      x402PayToAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18'
    }
  });
  ```
</CodeGroup>

## App Configuration

Global application configuration:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/app-config \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const config = await client.admin.listAppConfig();
  ```
</CodeGroup>

```bash theme={null}
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

```bash theme={null}
curl https://api.podium.build/api/v1/admin/subscription-tiers \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

```json theme={null}
[
  {
    "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

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/campaigns \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const campaigns = await client.admin.listCampaigns({
    status: 'SUBMITTED',
    page: 1,
    limit: 20
  });
  ```
</CodeGroup>

### Approve or Reject a Campaign

```bash theme={null}
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](/docs/agentic/enrichment-pipeline).

### Trigger Source Ingestion

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
curl https://api.podium.build/api/v1/admin/enrichment/serp-catalog \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

### Recompute Baselines

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
curl https://api.podium.build/api/v1/admin/enrichment/baseline/stats \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

### Pipeline Status

```bash theme={null}
curl https://api.podium.build/api/v1/admin/enrichment/status \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://api.podium.build/api/v1/admin/enrichment/reprocess \
  -H "Authorization: Bearer $PODIUM_API_KEY"
```

### Manage Enrichment Sources

#### Create a Source

```bash theme={null}
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

```bash theme={null}
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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.podium.build/api/v1/admin/tasks/pending-review \
    -H "Authorization: Bearer $PODIUM_API_KEY"
  ```

  ```typescript SDK theme={null}
  const tasks = await client.admin.getTasksPendingReview();
  ```
</CodeGroup>

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript SDK theme={null}
  await client.admin.resolveTaskManually({
    taskId: '0xabc123...',
    requestBody: { approved: true }
  });
  ```
</CodeGroup>

See [Task Pool API](/docs/api-reference/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      |