# Commerce API (https://prood.com/docs/apps/api)

`apps/api` is the **central Commerce API server**. It is the only application that directly invokes `@prood/commerce` and `@prood/platform`. All other apps consume it via HTTP.

**Port:** 3005 · **Framework:** Next.js 16 · **OpenAPI:** `/v1/openapi.json`

## Responsibilities [#responsibilities]

| Surface | Path | Purpose |
| --- | --- | --- |
| REST API | `/v1/*` | Catalog, cart, orders, admin CRUD |
| OpenAPI | `/v1/openapi.json` | Machine-readable API contract |
| MCP server | `/mcp` | Model Context Protocol tools |
| Agent Auth | `/api/auth/*` | AI agent registration and capabilities |
| Discovery | `/.well-known/agent-configuration` | Agent Auth Protocol config |
| Webhooks | `/v1/webhooks/payments/{provider}` | Payment event ingress |

## Architecture [#architecture]

```mermaid
flowchart TB
  REQ[HTTP Request]
  RESOLVE[resolve-caller.ts]
  JWT[Bearer JWT]
  KEY[x-api-key]
  SESS[Session cookie]
  HOST[x-storefront-host]
  AUTH[requireCaller scope]
  SVC[commerce-service.ts]
  COM["@prood/commerce.withTenant(orgId)"]

  REQ --> RESOLVE
  RESOLVE --> JWT
  RESOLVE --> KEY
  RESOLVE --> SESS
  RESOLVE --> HOST
  RESOLVE --> AUTH --> SVC --> COM
```

## Service layer [#service-layer]

`lib/commerce-service.ts` wraps every `@prood/commerce` function with tenant scoping:

```ts
export async function listProducts(orgId: string, params: SearchParams) {
  return withTenant(orgId, () => getProducts(params))
}

export async function adminCreateProduct(orgId: string, input: CreateProductInput) {
  return withTenant(orgId, () => getAdmin().createProduct(input))
}
```

Route handlers are thin — they resolve the caller, validate input with Zod, call the service layer, and return JSON.

## Root endpoint [#root-endpoint]

```
GET /
```

Returns API metadata:

```json
{
  "name": "Prood Commerce API",
  "version": "v1",
  "adapter": "platform",
  "openapi": "/v1/openapi.json",
  "docs": "https://prood.com/docs/api",
  "agentConfiguration": "/.well-known/agent-configuration",
  "auth": "/api/auth",
  "mcp": "/mcp"
}
```

## Configuration [#configuration]

| Variable | Purpose |
| --- | --- |
| `DATABASE_URL` | Commerce + auth database |
| `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` | Auth. `BETTER_AUTH_URL` is the public origin, `https://prood.com` (locally the gateway, `http://localhost:3001`) |
| `API_PUBLIC_URL` | Public origin for Agent Auth proxy and discovery: `https://prood.com` |
| `CHECKOUT_API_SECRET` | Webhook route protection |
| Payment/storage env vars | Provider instantiation |

## Related pages [#related-pages]

<Cards>
  <Card title="Authentication" href="/docs/apps/api/authentication" description="Caller resolution and scope enforcement." />
  <Card title="Endpoints" href="/docs/apps/api/endpoints" description="Complete REST endpoint reference." />
  <Card title="MCP server" href="/docs/apps/api/mcp" description="Model Context Protocol tools." />
  <Card title="Agent Auth" href="/docs/apps/api/agent-auth" description="AI agent registration and capabilities." />
  <Card title="OpenAPI reference" href="/docs/api" description="Interactive API documentation." />
</Cards>