Product response envelope

Current product endpoints return a resource envelope: data.object, data.brand_id, data.page, and nested data.data containing the dashboard data. Pagination fields for these endpoints are inside data.data. Unknown measurements remain null; verified zeros remain 0. Sensitive values are redacted.

Write scopes require beta enrollment. Draft and calendar edits do not publish content. External effects require the confirmation rules described below.

All Local endpoints require the local_geo plan feature.

GET …/local (local:read), operation get_local

Query: run_id (optional UUID in the brand), limit (default 50), offset cursor. data: runs, locations, recommendations and — with run_id — that run's observations, scorecards, trends. Empty measurements are not proof of success.

POST …/local/runs (local:write), operation run_local

Body: { "confirm": true }. Costs 5 credits. Uses enqueue_local_geo_run, which reuses an active run and enforces the plan, confirmed locations and the 24-hour manual-run limit (429 rate_limited). Returns { run_id, poll_with: "rankad_get_local", job_system: "local_geo_runs" }. Poll GET …/local?run_id=…, not /jobs.

PATCH …/local/recommendations/{recommendation_id}, operation set_local_recommendation_status

Body: { "status": "open" | "done" | "dismissed" }. Records the customer decision; it does not claim the issue was measured as resolved.

POST …/local/locations / PATCH …/local/locations/{location_id}, operations create_local_location / update_local_location

The same schema is used for PATCH, so send the full required set. The database enforces the active-location plan cap (429 quota_exceeded). Saving a location does not run a scan.