Run your POD shop from code, or from your AI.

Create an API key in Settings → Developers, pick its scopes, then:

curl https://api.pod-os.com/v1/me \
  -H "Authorization: Bearer $POD_API_KEY"

# 1. This week's opportunities
curl "https://api.pod-os.com/v1/radar/cards?limit=3" -H "Authorization: Bearer $POD_API_KEY"

# 2. Template from a starter (free) or a prompt (AI credits)
curl -X POST https://api.pod-os.com/v1/templates \
  -H "Authorization: Bearer $POD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"prompt","prompt":"watercolor pet memorial ornament","variations":4}}'

# 3. Freeze a version, then put it on blanks from several suppliers
curl -X POST https://api.pod-os.com/v1/templates/tpl_123/versions -H "Idempotency-Key: $(uuidgen)" ...
curl -X POST https://api.pod-os.com/v1/products -H "Idempotency-Key: $(uuidgen)" ... \
  -d '{"template_id":"tpl_123","targets":[{"product_type":"ornament-round"},{"product_type":"mug-11oz","supplier":"gelato"}]}'

The MCP server lives at https://mcp.pod-os.com/mcp. It speaks Streamable HTTP and OAuth 2.1 (PKCE, dynamic client registration), so clients that support remote MCP connect with just the URL. Clients without OAuth send an API key as a bearer token. Tools that publish, approve orders, refund, message buyers or spend AI credits take a confirm argument. Without confirm: true they return a preview and change nothing, so the agent has to ask you first.

Claude

Settings → Connectors → Add custom connector → paste the URL → Connect. Approve the scopes on the POD OS consent screen. Works in Claude.ai, Claude Desktop and Claude Code:

claude mcp add --transport http pod-os https://mcp.pod-os.com/mcp

ChatGPT

Settings → Apps & Connectors → Advanced → Developer mode, then Create → MCP server URL https://mcp.pod-os.com/mcp, authentication OAuth. The search and fetch tools make the workspace usable in deep research too.

Gemini CLI

{
  "mcpServers": {
    "pod-os": {
      "httpUrl": "https://mcp.pod-os.com/mcp",
      "headers": { "Authorization": "Bearer $POD_API_KEY" }
    }
  }
}

Grok (xAI API)

{
  "type": "mcp",
  "server_url": "https://mcp.pod-os.com/mcp",
  "server_label": "pod-os",
  "authorization": "Bearer $POD_API_KEY"
}

Prompts included: Launch a product from an idea and Review today's orders. Resources: pod://templates/…, pod://products/…, pod://orders/…, the catalog and the agent guide.

Keys belong to one workspace and carry scopes. Send Authorization: Bearer pod_live_…. Keys are stored hashed; you see the secret once. OAuth connectors get at most the scopes you tick, and publishing and order approval are separate scopes so you can hand an agent “draft everything, publish nothing”.

Idempotency

Every POST, PATCH and DELETE needs an Idempotency-Key header (8–255 chars, a UUID works). Retrying with the same key and body returns the first response with Idempotent-Replayed: true. The same key with a different body returns 422 idempotency_key_reused. Keys last 24 hours, per workspace.

Pagination

Lists return { data, has_more, next_cursor }, newest first. Pass next_cursor as cursor. limit is 1–100, default 20. Cursors are keyset-based, so pages stay stable while new rows arrive.

Rate limits

Per key (120 requests a minute by default, set per key). Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After.

Errors

{ "error": { "code": "insufficient_scope", "message": "This key is missing scope(s): orders:write",
             "details": { "missing": ["orders:write"] }, "request_id": "req_…" } }

Codes: unauthorized, insufficient_scope, not_found, validation_error, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, conflict, internal_error.

Async jobs

Print renders, mockups and publishing return 202 with a job. Poll it or subscribe to the webhook. Print files are content-addressed: the same template version and inputs never render twice.

Events: template.created, template.version_created, render.succeeded, render.failed, product.created, mockups.succeeded, listing.published, listing.failed, order.created, order.approved, order.rejected, order.proof_sent.

Each delivery is signed: Pod-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>. Return a 2xx within 10 seconds; failures retry after 30 s, 2 min, 10 min and 1 h. De-duplicate by Pod-Event-Id.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret: string, rawBody: string, header: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // replay window
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1 ?? "", "hex");
  return got.length === expected.length && timingSafeEqual(got, expected);
}