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/v1Authentication
Every operation takes an OAuth access token as a bearer token:
Authorization: Bearer $PM_TOKENThere 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| 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. - A request without a token answers
401 unauthorized; with a refused one,401 invalid_token. Both carry aWWW-Authenticatechallenge 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
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
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.
13 operations: onboarding, workspaces, properties, setup status, the Google connect link, billing checkout, invitations and feedback.
13 operations: connect Google Ads accounts, send manager-link invites, check setup and plan results, and create conversion actions and customer lists.
6 operations: connect Merchant Center to a property and set up the supplemental feed sources.
14 operations: connect a store, install website tracking, set consent and features, route tracking to a property and check purchases arrive.
8 operations: list, set, test and remove the Meta and ChatGPT Ads (OpenAI Conversions API) destinations a property sends its conversions to.
18 operations: Product Segmentation settings, inventory planning settings, product rules, feed source settings and feed generation.
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:
{
"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 answers400 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, orrequestKeyin 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-Matchout only whensettings_versionis null (nothing saved yet). 409 settings_conflictmeans someone saved in between: read again, reapply the change and retry.PUT /properties/{propertyId}/feed/source-settingsworks the same way.- An operation that requires the header answers
428 precondition_requiredwithout it.
The API version is in the path (/v1).
Rate limits
- 600 requests a minute per person, across the API and the MCP
executetool. Over it:429 rate_limitedwithRetry-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):
curl https://prod-backend.productmetrics.io/api/public/v1/openapi.json
curl https://prod-backend.productmetrics.io/api/public/v1/capabilitiesEach 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: the same API as commands
- MCP: the same API as two assistant tools
- CLI commands: every operation