# RankRight
> SEO tracking + client management platform (Innersite Solutions). This API
> is built for AI agents: bearer keys, structured errors with hints,
> idempotent retries, self-describing capabilities.

Start here (no auth needed):
- https://app.rankright.dev/api/v1/openapi.json : OpenAPI 3.1 spec of the whole surface
- https://app.rankright.dev/developers.md : full API guide as markdown (https://app.rankright.dev/llms-full.txt is the same text)

With an API key (Authorization: Bearer rrk_...):
- GET https://app.rankright.dev/api/v1/capabilities : machine-readable inventory of every RPC,
  its params, and the calling conventions
- POST https://app.rankright.dev/api/v1/rpc/<method> : JSON body = method kwargs
- POST https://app.rankright.dev/api/v1/jobs : queue audits/crawls/reports; poll GET /api/v1/jobs/<id>
- MCP: https://app.rankright.dev/api/v1/mcp (Streamable HTTP) — tools for clients and AI
  Visibility, plus call_rpc for every other method; the docs are its
  resources and the workflows its prompts. Add it as a connector with NO key:
  it advertises OAuth 2.0 (code + PKCE, dynamic registration) and opens a
  consent page; or use a bearer key.
- OAuth 2.0: https://app.rankright.dev/.well-known/oauth-authorization-server — scoped, revocable
  rro_ access tokens (1 h) + rotating refresh tokens for third-party apps.
- Python SDK: pip install rankright (or https://app.rankright.dev/sdk/rankright-python.zip); any RPC
  as a method, jobs, exports, OAuth login, webhook verification.
- Stability: path-versioned (/api/v1); additive changes any time (see
  https://app.rankright.dev/changelog.md); breaking changes only in /api/v2 with 12 months overlap;
  method removals get 60 days' notice + Deprecation/Sunset headers.
- Export everything: POST /api/v1/jobs {"kind": "export_org"} → poll → download
  result.download_url (every table as JSON + CSV, report files, manifest).
- Webhooks: register_webhook(url, events) → signed POSTs for job.completed /
  job.failed / aeo.capture.ingested / aeo.report.saved / *.status_changed
  instead of polling ("webhooks" in /api/v1/capabilities has the contract).
- Edit a client's site in plain English: POST /api/v1/jobs with
  {"kind": "prompted_edit", "client_id": N, "payload": {"instruction": "..."}}
  → the job stages proposed edits (result.pages[].edit_id); approve with
  POST /api/v1/rpc/apply_site_edit {"edit_id"}, undo with rollback_site_edit.
  Nothing is written to the live site until apply_site_edit is called.
- AI Visibility (AEO) for a client — does ChatGPT / Claude / Gemini name and
  cite them? generate_aeo_questions(client_id) → set_aeo_cadence(client_id,
  engines=[...]) → get_aeo_summary(client_id) → get_aeo_items(client_id) →
  update_aeo_item_status(...) → aeo_report_html(client_id, month). The full
  step list is under "workflows" in /api/v1/capabilities.

Conventions:
- Errors: JSON {"error", "code", "detail", "hint"} — branch on "code".
- Retries: send an Idempotency-Key header on POSTs; replay-safe.
- Rate limits: per key; watch X-RateLimit-Remaining, honor Retry-After on 429.
- Org-scoped keys are confined + metered; partner keys are cross-org.
- Keys without the "write" scope are read-only (403 on mutating endpoints).

Keys: an org owner mints keys in the UI (API keys page), or platform admins
at /platform/api-keys. The plaintext rrk_ token is shown exactly once.

Security posture (encryption, isolation, retention, US residency, disclosure):
https://rankright.dev/security.html · privacy: https://rankright.dev/privacy.html
· terms: https://rankright.dev/terms.html

Try it now (no signup) — public READ-ONLY sandbox key, shared and rate-limited,
fictional data (Harbor Light Home Services, client_id 108):
  Authorization: Bearer rrk_u154NZ009Kk_dbtPPuXeCpYbEZQgX6gziL-i7uZIN8k
  curl -X POST https://app.rankright.dev/api/v1/rpc/get_aeo_summary -H 'Authorization: Bearer rrk_u154NZ009Kk_dbtPPuXeCpYbEZQgX6gziL-i7uZIN8k' -H 'Content-Type: application/json' -d '{"client_id": 108}'
Works for every read RPC, the MCP server and these docs; writes answer 403.

Single sign-on: OpenID Connect (code + PKCE) and SAML 2.0 for interactive
login — platform providers: Google; an organization owner adds their own
OIDC or SAML identity provider self-serve (Account → Single sign-on) and staff
sign in at https://app.rankright.dev/login/sso with their work email (https://app.rankright.dev/developers.md
"Single sign-on"). API/MCP access uses rrk_ keys or OAuth tokens, never SSO.