Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

API keys are scoped. Every key carries read plus any of the explicit write scopes you grant. Endpoints that require a scope you don’t have return 403 insufficient_scope with a clear message.

​
The scopes

ScopeTier requiredRequired for
readAnyAll read endpoints (search, entities, mentions, appearances). Granted automatically on every key.
watchlists:writeAny paidPOST /v1/watchlists, PATCH /v1/watchlists/{id}, DELETE /v1/watchlists/{id}, and watchlist tracker mutations.
trackers:writeAny paidPOST /v1/trackers, PATCH /v1/trackers/{id}, DELETE /v1/trackers/{id}.
recommendations:readPro+GET /v1/recommendations, GET /v1/entities/{id}/recommendations, GET /v1/channels/{id}/sponsors, GET /v1/mentions?details=full, and the recommendations_summary blocks on entity/channel reads.
recommendations:writePro+POST /v1/feedback.
read cannot be removed. The dashboard hides the toggle to make that explicit.
The two recommendations:* scopes are only visible in the dashboard on Pro+ plans (pro_plus, ultra, teams, enterprise). On hobby and base pro, the toggles are hidden and the commercial routes return 403 recommendations_not_enabled regardless of scope.

​
Choosing scopes

  • Read-only integrations (analytics, dashboards, BI exports) should mint a key with read only. That key cannot create or delete anything.
  • Automation that creates trackers (CRM enrichment, watchlist sync, GTM signals) needs trackers:write and probably watchlists:write if it also creates lists.
  • Commercial intelligence integrations (advertiser dashboards, sponsor research, ad-spend modeling) need recommendations:read. Add recommendations:write if you’ll be submitting corrections through POST /v1/feedback.
  • Per-environment keys. Mint one key per environment and per process. Don’t reuse production keys in CI.

​
Inspecting a key’s scopes

curl https://api.arcmira.com/v1/me \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "user_id": "usr_...",
  "tier": "pro_plus",
  "scopes": ["read", "watchlists:write", "recommendations:read"],
  "rate_limit": 240,
  "recommendations_api_enabled": true,
  "usage": {
    "rows_used": 1234,
    "rows_remaining": 98766,
    "monthly_rows": 100000,
    "current_spend_cents": 0
  }
}
recommendations_api_enabled is the tier-level gate. It’s true on Pro+ tiers and false everywhere else, independent of the scopes granted to the key. If it’s false, the commercial routes will 403 even if you’ve somehow attached the scope.

​
Error shape on insufficient scope

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "API key requires watchlists:write.",
    "doc_url": "https://docs.arcmira.com/errors#insufficient_scope",
    "request_id": "req_..."
  }
}
The fix is to mint a new key with the right scopes (or grant them via Settings → API Keys). For commercial scopes specifically, you also need to be on a Pro+ plan — see Commercial intelligence.