Outrank REST API

Base URL

All requests are made against:

https://www.outrank.so/api/agent/v1

Endpoints below are written relative to this base URL — for example, GET /products means GET https://www.outrank.so/api/agent/v1/products.

Authentication

Every request must include an Authorization header with your API key as a bearer token. Keys are scoped to a single organization and use the prefix outr_live_.

Authorization: Bearer outr_live_your_api_key_here

Requests without a valid, non-revoked, non-expired key return 401 Unauthorized.

Quickstart

Once you have a key, the fastest way to confirm it works is to call the /auth/whoami endpoint:

curl https://www.outrank.so/api/agent/v1/auth/whoami \
  -H "Authorization: Bearer outr_live_your_api_key_here"

A successful response returns the user, organization, remaining article credits, and the entitlements associated with the key.

Entitlements

/auth/whoami computes which command groups the organization can use right now, from the same subscription and service data the endpoints read. Each toolset is listed with a mode: full allows reads and writes, read means the subscription behind the toolset is no longer active (for example after an Articles subscription ended): use it to inspect existing data, and expect writes that need the subscription to be rejected. unverified_toolsets lists, in the same shape, toolsets whose access could not be checked for this response; they are left out of toolsets but may still work, so keep offering them. A toolset that is absent from both is not active for this organization yet; the endpoints that start it (the marketplace seller and buyer status endpoints, backlink subscription quotes and the billing portal link) still answer. The flows block says which product areas the organization has started, so an agent can offer the right onboarding step. disabled_products_with_services counts disabled products whose services or started seller setup do not contribute; a disabled product can only be reactivated in the dashboard.

{
  "ok": true,
  "data": {
    "user": { "email": "owner@example.com", "role": "admin" },
    "organization": {
      "id": "8f1c2f7e-1c34-4e63-9a3d-2b7f6d4a9e10",
      "onboarded": true,
      "subscribed": true,
      "article_credits_used": 12,
      "article_credits_limit": 30,
      "article_credits_remaining": 18,
      "product_count": 2
    },
    "api_key": { "name": "ci-agent" },
    "entitlements": {
      "toolsets": {
        "core": "full",
        "keywords": "full",
        "articles": "full",
        "integrations": "full",
        "gsc": "full",
        "linking": "full",
        "backlinks": "full",
        "billing": "full",
        "improvements": "full",
        "marketplace-buyer": "full"
      },
      "unverified_toolsets": {},
      "flows": {
        "articles": true,
        "marketplace_buyer": true,
        "marketplace_seller": false
      },
      "disabled_products_with_services": 0
    }
  },
  "agent_guidance": "..."
}

Toolset names: core, integrations, gsc, linking, backlinks, keywords, articles, improvements, marketplace-seller, marketplace-buyer, billing. When entitlements cannot be computed the field is null; treat every toolset as available and rely on per-request errors. Entitlements are a hint for choosing which commands to offer, not an access boundary: they are merged across the organization's active products, and the endpoints that need a subscription check it per product on their own.

Rate limits

Each API key is rate-limited per minute and per day:

• 120 requests per minute per API key.
• 10,000 requests per day per API key.

Every response includes X-RateLimit-* headers so you can track remaining quota. Once a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how long to wait.

Endpoints

The API is organised into the groups below. Each endpoint accepts and returns JSON, and all writes are scoped to the organization that owns the API key.

Errors

Errors are returned as JSON with an error object describing the failure. Common status codes:

• 400 — invalid request body or query parameters.
• 401 — missing, malformed, expired, or revoked API key.
• 403 — the key's organization is not on a supported plan or lacks access to the resource.
• 404 — the requested resource does not exist or belongs to another organization.
• 429 — rate limit exceeded; honor the Retry-After header.
• 5xx — transient server error; safe to retry idempotent calls with backoff.

Using the API from an AI agent

If you want a coding agent (Claude Code, Cursor, etc.) to drive Outrank for you, install the official CLI and point it at your API key:

npm install -g outrank-cli
export OUTRANK_API_KEY=outr_live_your_api_key_here
outrank-cli --help

The CLI wraps every endpoint listed above and is published on npm as outrank-cli.

The same package includes an MCP server, so Claude Code, Cursor and other MCP clients can call Outrank as tools without a terminal. See the MCP server documentation for the setup.