Skip to content
PicoRank Docs
Website Open app

API overview

Everything the app can do, over HTTP — REST and GraphQL, on one set of keys and one set of rules.

The PicoRank API exposes the same capabilities as app.picorank.com: tracking configuration, results, jobs and account state. It is not a mirror of the app — it is the same code. Both surfaces call one service layer, so permissions, plan limits and spending behave identically whichever you use.

Base URLs

EnvironmentRESTGraphQLKeys
Production https://api.picorank.com/v1 https://api.picorank.com/graphql pr_live_…
Sandbox (staging) https://api.staging.picorank.com/v1 https://api.staging.picorank.com/graphql pr_test_…

The sandbox runs the same code against a copy of production-shaped data. It is where to point your first integration: real behaviour, real guards, no production consequences.

Your first request

curl https://api.picorank.com/v1/domains \
  -H "Authorization: Bearer $PICORANK_KEY"
{
  "data": [
    { "id": "8f3c…", "host": "example.com", "path": null, "label": "Main site",
      "created_at": "2026-03-02T09:14:11Z", "last_full_crawl_at": "2026-07-28T02:11:04Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

REST or GraphQL?

Both cover the same ground and enforce the same rules. Pick by shape of question.

  • REST for straightforward jobs: list domains, add keywords, start a scan, poll a job. Predictable, cacheable, easy to call from anything.
  • GraphQL when you need a graph in one round trip: "every domain with its slot usage, its scans, its competitors, and each keyword's position history" is one query and four-plus REST calls.

Versioning

The /v1 prefix is the contract. Additive changes — new endpoints, new optional fields — ship without notice, so write clients that ignore fields they do not recognise. Anything breaking gets a /v2, with Deprecation and Sunset headers on the old surface well in advance.

What is covered today

Configuration and results are complete — domains, keyword lists and keywords, labels, competitors, scans, slot usage, jobs, ranking positions and history, account, entitlements and usage.

The analysis features are read-only for now: crawled pages, site-optimization analyses and their findings, AI visibility scores and industries, backlink summaries, and integration status. You can start any of their jobs through POST /v1/jobs and read everything they produce — what you cannot yet do over the API is the in-app curation: dismissing a finding, activating an industry, editing a scan's questions. Those are decisions best made where the surrounding context is on screen, and they are on the list.

Not yet exposed: report generation and scheduling, keyword suggestions and research lookups, and share links. Use the app for those.

What the API does not do

  • Manage API keys — see Authentication.
  • Change a subscription — billing is readable, not writable.
  • Optimistic concurrency. Updates are last-write-wins; see Conventions.
  • Push events. Webhooks are planned, not shipped. Until then, jobs are pollable: POST /v1/jobs returns a job, and GET /v1/jobs/{kind}/{id} reports progress until it is done.

Next