Catalog API

Public Catalog Endpoints

These endpoints support three auth modes: API key (org visibility), JWT (admin sees all), or no auth (public only).

List Templates

GET /api/v1/catalog/templates

Query parameters:

Parameter	Type	Description
`category`	string	Filter by category slug
`search`	string	Search by name or description (case-insensitive)
`featured`	boolean	Only featured templates (`true`)
`tags`	string	Comma-separated tag filter (e.g. `ai,gpu`) — matches any tag
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 50, max: 100)

Response:

{
  "templates": [
    {
      "id": "uuid",
      "name": "Ollama",
      "slug": "ollama",
      "description": "Run large language models locally",
      "version": "1.0.0",
      "kind": "deployment",
      "category_id": "uuid",
      "category_name": "AI & Machine Learning",
      "category_slug": "ai-ml",
      "category_icon": "brain",
      "image_name": "ollama/ollama",
      "image_tag": "latest",
      "cpu_request": "2",
      "memory_request": "8Gi",
      "gpu_count": 1,
      "vram_request": "8Gi",
      "concurrent_jobs": 1,
      "env": [{"name": "OLLAMA_HOST", "value": "0.0.0.0"}],
      "env_schema": [
        {"name": "OLLAMA_MODELS", "required": false, "default_value": "/models", "description": "Model storage path"}
      ],
      "ports": [{"containerPort": 11434, "protocol": "TCP"}],
      "volume_mounts": [{"name": "models", "mountPath": "/models"}],
      "node_selector": {},
      "required_network_types": [],
      "tags": ["ai", "llm", "gpu"],
      "is_public": true,
      "is_featured": true,
      "min_tier": "free",
      "download_count": 1234,
      "documentation": "## Usage\n\nPull a model after deployment...",
      "updated_at": "2026-02-28T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 42,
    "totalPages": 1
  }
}

Visibility rules:

Auth	Sees
Admin JWT	All templates (public + private + all orgs)
API key (org)	Public templates + org-owned + private categories with access grant
No auth	Public templates in non-private categories only

Get Template by Slug

GET /api/v1/catalog/templates/:slug

Returns a single template with the same fields as the list response. Returns 404 if the template doesn't exist or isn't visible to the caller.

When accessed via API key, increments the template's download_count.

Check for Updates

GET /api/v1/catalog/templates/updates?since=2026-02-01T00:00:00Z

Parameter	Type	Required	Description
`since`	string	Yes	ISO 8601 timestamp — returns templates updated after this time

Response:

{
  "templates": [...],
  "checked_at": "2026-02-28T12:00:00Z"
}

Use checked_at as the since value for the next request to implement incremental sync.

List Categories

GET /api/v1/catalog/categories

Response:

{
  "categories": [
    {
      "id": "uuid",
      "name": "AI & Machine Learning",
      "slug": "ai-ml",
      "description": "GPU-accelerated inference, training, and ML pipelines",
      "icon": "brain",
      "sort_order": 1,
      "is_private": false,
      "template_count": 15
    }
  ]
}

Visibility rules:

Admin JWT: all categories with full template counts
API key (org): non-private categories + private categories with access grant
No auth: non-private categories only

Account Endpoints

These require JWT authentication.

API Keys

GET    /api/v1/account/api-keys     # List your org's API keys
POST   /api/v1/account/api-keys     # Create a new API key
PUT    /api/v1/account/api-keys     # Re-issue key (new secret, same ID)
DELETE /api/v1/account/api-keys     # Revoke an API key

Create request:

{
  "name": "Production PodWarden"
}

Create response (key shown only once):

{
  "apiKey": {
    "id": "uuid",
    "name": "Production PodWarden",
    "key": "pwc_a1b2c3d4e5f6g7h8i9j0...",
    "key_prefix": "pwc_a1b2c3d4",
    "status": "active"
  }
}

Organizations

GET  /api/v1/account/organizations   # Get your organization
POST /api/v1/account/organizations   # Create an organization

Create request:

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Creating an organization sets the user as org admin and creates a free subscription.

Profile

GET /api/v1/account/profile          # Get your profile (includes org info)
PUT /api/v1/account/profile          # Update your profile (name)

Admin Endpoints

These require the admin or superadmin role.

Template Management

GET    /api/v1/admin/templates       # List all templates (includes private)
POST   /api/v1/admin/templates       # Create a template
PUT    /api/v1/admin/templates       # Update a template (id in body)
DELETE /api/v1/admin/templates       # Delete a template (id in body)

All template fields are available in POST and PUT, including:

Basic: name, description, category_id, version, kind
Image: image_name, image_tag, registry_url, registry_credentials
Resources: cpu_request, memory_request, gpu_count, vram_request, concurrent_jobs
Config: env (JSON array), env_schema (JSON array), secret_refs, command, ports
Scheduling: node_selector, tolerations, volume_mounts
Network: required_network_types (text array: ["public"], ["mesh"], etc.)
Catalog: is_public, is_featured, min_tier, tags, icon_url, documentation

Category Management

GET    /api/v1/admin/categories      # List all categories (with template_count, access_count)
POST   /api/v1/admin/categories      # Create a category
PUT    /api/v1/admin/categories      # Update a category (id in body)
DELETE /api/v1/admin/categories      # Delete a category (fails if templates reference it)

Category fields: name, slug, description, icon, sort_order, is_private.

Catalog Access (Private Categories)

GET    /api/v1/admin/catalog-access  # List all access grants
POST   /api/v1/admin/catalog-access  # Grant org access to private category
DELETE /api/v1/admin/catalog-access  # Revoke access (by id or org_id+category_id)

Grant request:

{
  "org_id": "uuid",
  "category_id": "uuid"
}

User Management

GET /api/v1/admin/users              # List all users (with org info)
PUT /api/v1/admin/users              # Update user role (id + role in body)

Organization Management

GET /api/v1/admin/organizations      # List all orgs (with member_count, api_key_count)
PUT /api/v1/admin/organizations      # Update org status/tier (id in body)

API Key Management

GET    /api/v1/admin/api-keys        # List all API keys (cross-org)
DELETE /api/v1/admin/api-keys        # Revoke any API key (id in body)

Admin Stats

GET /api/v1/admin/stats              # System-wide counts (users, orgs, keys, templates, categories)