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

The **Commerce API** exposes a RESTful interface at `/v1/*` with a machine-readable **OpenAPI 3.1** specification. This section documents every endpoint, generated from the same specification.

<Callout title="Sending an API key">
Examples use `x-api-key: pk...`. Agent tokens use `Authorization: Bearer`, from code rather than this console.
</Callout>

## Base URL [#base-url]

| Environment | URL |
| --- | --- |
| Local development | `http://localhost:3001/v1` (through the gateway; the API app itself is on `:3005`) |
| Production | `https://prood.com/v1` |

## OpenAPI spec [#openapi-spec]

Download the raw specification:

```
GET /v1/openapi.json
```

Each operation below has its own page, built from this spec.

## Authentication [#authentication]

All endpoints require authentication except `/v1/health` and `/v1/openapi.json`. See [Authentication](/docs/apps/api/authentication) for details on:

- Session cookies (dashboard)
- `x-storefront-host` header (storefront)
- API keys (`x-api-key`)
- Agent JWT (`Authorization: Bearer`)

## Endpoint groups [#endpoint-groups]

The pages below are organized by OpenAPI tags:

| Tag | Scope | Description |
| --- | --- | --- |
| **Storefront** | storefront | Products, categories, store info, carts, shipping, placing an order, order history. Coupon routes exist, but no merchant can create coupons yet |
| **Admin** | admin | Reads and changes catalog, inventory, orders and store settings, and reads customers. Payment accounts, domains, team and keys stay in the dashboard. Starts on Grow. |
| **Webhooks** | checkout-secret | Payment webhook ingress |

## Using the reference [#using-the-reference]

Each operation page includes:

- **Description** — what the endpoint does
- **Parameters** — path, query, and header parameters with types
- **Request body** — JSON schema for POST/PATCH requests
- **Responses** — status codes and response schemas

## Client libraries [#client-libraries]

| Client | Package | Description |
| --- | --- | --- |
| TypeScript | `@prood/api-client` | Typed fetch client generated from this spec |
| MCP | Built-in | `/mcp` endpoint exposes tools mirroring these operations |
| Agent Auth | Built-in | Each `operationId` becomes an agent capability |

## Related documentation [#related-documentation]

<Cards>
  <Card title="Commerce API overview" href="/docs/apps/api" description="Architecture and service layer." />
  <Card title="Endpoint summary" href="/docs/apps/api/endpoints" description="Human-readable endpoint table." />
  <Card title="@prood/api-client" href="/docs/packages/api-client" description="Typed HTTP client usage." />
  <Card title="MCP server" href="/docs/apps/api/mcp" description="AI agent tool interface." />
</Cards>