> ## Documentation Index
> Fetch the complete documentation index at: https://996f455-productmetrics.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://996f455-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://996f455-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://996f455-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# Product Metrics API (/docs/api/overview)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 2655 · updated: 2026-11-16 -->
Related: [Account and onboarding API](/docs/api/account.md), [Meta and ChatGPT Ads destinations API](/docs/api/destinations.md), [Google Ads API](/docs/api/google-ads.md), [Merchant Center API](/docs/api/merchant-center.md), [Settings, product rules and feed API](/docs/api/settings.md), [Store data and insights API](/docs/api/store-data.md)

> The Product Metrics public API: base URL, OAuth bearer tokens and scopes, the response envelope, idempotency keys, If-Match versions, errors and the OpenAPI document.

The public API is the one surface behind the [CLI](/docs/cli/overview) and the MCP server's [`search` and `execute` tools](/docs/mcp/overview#api-tools-search-and-execute). Every CLI command is one API operation.

Every operation acts as the signed-in person, with their role in each workspace. For how the app, CLI, MCP server and API relate, see [Set up from the app, CLI, MCP or API](/docs/using/overview).

## Base URL

```text
https://prod-backend.productmetrics.io/api/public/v1
```

## Authentication

Every operation takes an OAuth access token as a bearer token:

```bash
Authorization: Bearer $PM_TOKEN
```

There are no API keys. Tokens come from the Product Metrics OAuth 2.1 server, the same one MCP clients use. Its metadata is at:

```text
https://prod-backend.productmetrics.io/.well-known/oauth-authorization-server
```

| Endpoint            | Path                                                      |
| ------------------- | --------------------------------------------------------- |
| Authorization       | `/oauth/authorize` (authorization code with PKCE S256)    |
| Token               | `/oauth/token` (code exchange and refresh-token rotation) |
| Client registration | `/oauth/register` (dynamic client registration)           |

* **Access tokens** last one hour; **refresh tokens** last 30 days.
* The easiest way to get a token is `productmetrics login`: the CLI registers itself, opens the consent page and stores the tokens. See [CLI authentication](/docs/cli/authentication).
* A request without a token answers `401 unauthorized`; with a refused one, `401 invalid_token`. Both carry a `WWW-Authenticate` challenge that names the scope the operation needs.

### Scopes

Each operation needs exactly one scope. The OpenAPI document lists it per operation as `x-scope`.

| Scope   | Allows                                                                                          |
| ------- | ----------------------------------------------------------------------------------------------- |
| `read`  | Reading the person's Product Metrics setup and data                                             |
| `setup` | Connecting accounts, stores and tracking, and completing setup steps (removing connections too) |
| `write` | Changing settings, product rules and feeds, and inviting people                                 |

A token without the scope answers `403 insufficient_scope` with `details.required_scope`. Scopes never widen the person's role: an operation that needs a workspace admin still refuses an editor.

## Try it

```bash
curl "https://prod-backend.productmetrics.io/api/public/v1/properties" \
  -H "Authorization: Bearer $PM_TOKEN"
```

```json
{
  "data": {
    "properties": [
      {
        "property_id": "…",
        "company_id": "…",
        "name": "…",
        "company": "…",
        "google_ads_customer_id": "…",
        "currency": "EUR"
      }
    ]
  },
  "request_id": "…"
}
```

The same call from the CLI is `productmetrics properties list --json`; from an assistant, `execute` with `GET /properties`.

## Operations

84 operations in 7 areas. Each area lists its operations with their method and path; each operation has its own page with its scope, parameters, body fields, a curl and `productmetrics` example and an example response.



* [Account and onboarding](/docs/api/account) (13 operations): onboarding, workspaces, properties, setup status, the Google connect link, billing checkout, invitations and feedback.
* [Google Ads](/docs/api/google-ads) (13 operations): connect Google Ads accounts, send manager-link invites, check setup and plan results, and create conversion actions and customer lists.
* [Merchant Center](/docs/api/merchant-center) (6 operations): connect Merchant Center to a property and set up the supplemental feed sources.
* [Stores and tracking](/docs/api/stores-and-tracking) (14 operations): connect a store, install website tracking, set consent and features, route tracking to a property and check purchases arrive.
* [Meta and ChatGPT Ads](/docs/api/destinations) (8 operations): list, set, test and remove the Meta and ChatGPT Ads (OpenAI Conversions API) destinations a property sends its conversions to.
* [Settings and rules](/docs/api/settings) (18 operations): Product Segmentation settings, inventory planning settings, product rules, feed source settings and feed generation.
* [Store data and insights](/docs/api/store-data) (12 operations): read orders, inventory, business health, insights, usage and the store's data lake with SQL.

## Response envelope

Every answer is JSON, whatever shape the operation's internal route uses:

```json
{
  "data": { … },
  "request_id": "…"
}
```

An error answers with `error` instead of `data`:

```json
{
  "error": {
    "code": "…",
    "message": "…",
    "details": { … }
  },
  "request_id": "…"
}
```

`error.code` is lower_snake and stable enough to branch on. Quote `request_id` when you report a problem.

`details` appears when there is more to say, such as validation issues (`details.issues[]` with `path` and `message`) or why a checkout is not the next step (`details.status`).



> **Note:** The CLI's `--json` output wraps the same answer with `ok` and `exit_code`. See [JSON and exit codes](/docs/cli/json-and-exit-codes).

## Idempotency keys

Send `Idempotency-Key: <uuid>` on a change you may retry. Two operations use it:

* `POST /companies` (create a workspace) **requires** a key: without one it answers `400 idempotency_key_required`. Use a new UUID per workspace and the same one to retry.
* `POST /companies/{companyId}/stores` (connect a store) uses the header, or `requestKey` in the body, so a retry does not start a second connection.

```bash
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/companies" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "My Shop" }'
```

A retry with the same key returns the first call's result.

## Versions and If-Match

Settings carry a `settings_version`. Read it, then send it in `If-Match` with the change, so a change someone made in between is not overwritten:

```bash
curl -X PUT \
  "https://prod-backend.productmetrics.io/api/public/v1/properties/$PROPERTY_ID/settings" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "4"' \
  -d '{
    "labelizer_settings": { … }
  }'
```

* Leave `If-Match` out only when `settings_version` is null (nothing saved yet).
* `409 settings_conflict` means someone saved in between: read again, reapply the change and retry.
* `PUT /properties/{propertyId}/feed/source-settings` works the same way.
* An operation that requires the header answers `428 precondition_required` without it.

The API version is in the path (`/v1`).

## Rate limits

* **600 requests a minute per person**, across the API and the MCP `execute` tool. Over it: `429 rate_limited` with `Retry-After: 60`.
* `POST /properties/{propertyId}/query` (SQL over the lake) has its own limit: 30 per person and 120 per property each hour, shared with the Product Metrics assistant.
* Request bodies are capped at 1 MB (`413 payload_too_large`).

## Errors

| Status | `code`                          | Meaning                                                                              |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------ |
| 400    | `invalid_request`               | The input does not match the operation; `details.issues` lists what                  |
| 400    | `idempotency_key_required`      | Send an `Idempotency-Key` UUID                                                       |
| 401    | `unauthorized`, `invalid_token` | No token, or a refused one: sign in again                                            |
| 402    | `subscription_required`         | The property needs Pro                                                               |
| 403    | `insufficient_scope`            | The token lacks `details.required_scope`                                             |
| 403    | `forbidden`                     | Your role or access does not allow it                                                |
| 404    | `not_found`, `route_not_found`  | No such resource, or no operation answers this method and path                       |
| 409    | `conflict`, `settings_conflict` | The state changed or a precondition is missing; the message says which               |
| 413    | `payload_too_large`             | The body is over 1 MB                                                                |
| 428    | `precondition_required`         | Send `If-Match`                                                                      |
| 429    | `rate_limited`                  | Wait for `Retry-After`                                                               |
| 500    | `internal_error`                | Product Metrics could not complete the request; `details.trace_id` when there is one |
| 503    | `unavailable`                   | Try again shortly                                                                    |

An operation can answer a more specific code from the route it wraps (for example `demo_live_operation_blocked`); the status then tells you the class.

## OpenAPI

The OpenAPI document and the operation list are public (no token):

```bash
curl https://prod-backend.productmetrics.io/api/public/v1/openapi.json
curl https://prod-backend.productmetrics.io/api/public/v1/capabilities
```

Each operation's `operationId` is its capability id (`settings.get`), and each carries:

| Field             | Meaning                                                         |
| ----------------- | --------------------------------------------------------------- |
| `x-scope`         | The scope it needs: `read`, `setup` or `write`                  |
| `x-access`        | `read`, `write`, or `destructive` (cannot be undone)            |
| `x-secret-fields` | Response fields that hold a secret, such as a store setup token |
| `x-browser-step`  | The result may hold a URL a person must open                    |

The document's `oauth2` security scheme names the authorization and token URLs and the three scopes.

## Where next

* [CLI](/docs/cli/overview): the same API as commands
* [MCP](/docs/mcp/overview): the same API as two assistant tools
* [CLI commands](/docs/cli/commands): every operation
