Skip to content
API reference

Product Metrics API

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 and the MCP server’s search and execute tools. 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.

Base URL

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

Authentication

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

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:

https://prod-backend.productmetrics.io/.well-known/oauth-authorization-server
EndpointPath
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.
  • 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.

ScopeAllows
readReading the person’s Product Metrics setup and data
setupConnecting accounts, stores and tracking, and completing setup steps (removing connections too)
writeChanging 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

curl "https://prod-backend.productmetrics.io/api/public/v1/properties" \
  -H "Authorization: Bearer $PM_TOKEN"
{
  "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

85 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.

Response envelope

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

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

An error answers with error instead of data:

{
  "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).

The CLI’s --json output wraps the same answer with ok and exit_code. See 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.
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:

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

StatuscodeMeaning
400invalid_requestThe input does not match the operation; details.issues lists what
400idempotency_key_requiredSend an Idempotency-Key UUID
401unauthorized, invalid_tokenNo token, or a refused one: sign in again
402subscription_requiredThe property needs Pro
403insufficient_scopeThe token lacks details.required_scope
403forbiddenYour role or access does not allow it
404not_found, route_not_foundNo such resource, or no operation answers this method and path
409conflict, settings_conflictThe state changed or a precondition is missing; the message says which
413payload_too_largeThe body is over 1 MB
428precondition_requiredSend If-Match
429rate_limitedWait for Retry-After
500internal_errorProduct Metrics could not complete the request; details.trace_id when there is one
503unavailableTry 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):

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:

FieldMeaning
x-scopeThe scope it needs: read, setup or write
x-accessread, write, or destructive (cannot be undone)
x-secret-fieldsResponse fields that hold a secret, such as a store setup token
x-browser-stepThe 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: the same API as commands
  • MCP: the same API as two assistant tools
  • CLI commands: every operation