Account endpoints

These endpoints cover the account side of the API: who you are, how many credits you have, which API keys exist, what you have spent, and how to buy more. They cost no credits and are the same endpoints the RankParse dashboard uses.

Every endpoint here, except /v1/pricing, authenticates with your normal X-API-Key header. None of them needs a dashboard session. See Authentication.

An API key acts as the person who created it, inside the workspace it belongs to. A role that is not allowed an action gets 403 capability_missing. See Team workspaces for how credits are shared.

All errors share the format in Errors. Authentication failures return 401 invalid_api_key.

GET /v1/me

Returns the profile of the person the API key acts as, and the workspace credit balance.

curl "https://api.rankparse.com/v1/me" -H "X-API-Key: rp_your_key"

import requests

me = requests.get(
    "https://api.rankparse.com/v1/me",
    headers={"X-API-Key": "rp_your_key"},
).json()
print(me["email"], me["credits"])

const res = await fetch("https://api.rankparse.com/v1/me", {
  headers: { "X-API-Key": process.env.RANKPARSE_API_KEY },
});
const me = await res.json();
console.log(me.email, me.credits);

{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "email": "you@example.com",
  "credits": 842,
  "created_at": 1760000000000
}

Errors: 404 user_not_found if the user no longer exists.

GET /v1/credits

Returns the workspace credit balance. This is the cheapest way to check before an expensive call. MCP tool: check_credits.

curl "https://api.rankparse.com/v1/credits" -H "X-API-Key: rp_your_key"

{ "credits": 842 }

Errors: 403 capability_missing for roles that may not view credits.

GET /v1/keys

Lists active (not revoked) API keys, newest first. Raw keys are never returned; only a masked form.

curl "https://api.rankparse.com/v1/keys" -H "X-API-Key: rp_your_key"

{
  "keys": [
    {
      "id": "9f2c1e5a7b...c4d8",
      "name": "Production",
      "last_four": "a1b2",
      "created_at": 1760000000000
    }
  ]
}

Owners and admins see every key in the workspace. Members see only the keys they created.

POST /v1/keys

Creates a new API key. The raw key is returned once and cannot be retrieved again. Store it immediately.

curl -X POST "https://api.rankparse.com/v1/keys" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline"}'

import requests

created = requests.post(
    "https://api.rankparse.com/v1/keys",
    headers={"X-API-Key": "rp_your_key"},
    json={"name": "CI pipeline"},
).json()
new_key = created["key"]  # shown only now

const res = await fetch("https://api.rankparse.com/v1/keys", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RANKPARSE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "CI pipeline" }),
});
const { key } = await res.json(); // shown only now

Responds 201:

{
  "id": "9f2c1e5a7b...c4d8",
  "key": "rp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "CI pipeline",
  "created_at": 1760000000000
}

Keys have the form rp_ followed by 32 random characters. RankParse stores only a hash. A notification email goes to the account email whenever a key is created or revoked.

DELETE /v1/keys/:id

Revokes a key. Revocation is immediate and cannot be undone.

curl -X DELETE "https://api.rankparse.com/v1/keys/9f2c1e5a7b...c4d8" \
  -H "X-API-Key: rp_your_key"

{ "success": true }

Errors: 404 key_not_found when the ID does not exist, is already revoked, or (for members) belongs to another person's key.

GET /v1/usage

Returns the workspace's request log, newest first, with offset pagination.

curl "https://api.rankparse.com/v1/usage?limit=50&offset=50" \
  -H "X-API-Key: rp_your_key"

import requests

offset, rows = 0, []
while True:
    page = requests.get(
        "https://api.rankparse.com/v1/usage",
        params={"limit": 200, "offset": offset},
        headers={"X-API-Key": "rp_your_key"},
    ).json()
    rows += page["usage"]
    offset += len(page["usage"])
    if not page["usage"] or offset >= page["total"]:
        break

let offset = 0;
const rows = [];
while (true) {
  const res = await fetch(
    `https://api.rankparse.com/v1/usage?limit=200&offset=${offset}`,
    { headers: { "X-API-Key": process.env.RANKPARSE_API_KEY } }
  );
  const page = await res.json();
  rows.push(...page.usage);
  offset += page.usage.length;
  if (page.usage.length === 0 || offset >= page.total) break;
}

{
  "usage": [
    {
      "endpoint": "backlinks",
      "credits_used": 2,
      "domain": "stripe.com",
      "created_at": 1760000000000
    },
    {
      "endpoint": "page-seo",
      "credits_used": 3,
      "domain": "https://stripe.com/about",
      "created_at": 1759999900000
    }
  ],
  "total": 1284
}

The log covers everyone in the workspace, not just your key. It is meant for display and rough reconciliation; not every endpoint writes a row, so use your credit balance as the source of truth for billing.

GET /v1/pricing

Public, no key needed. Returns the credit price tiers. A purchase of credits is priced at the price_per_credit of the highest tier whose min is at or below credits.

curl "https://api.rankparse.com/v1/pricing"

{
  "tiers": [
    { "min": 0, "price_per_credit": 0.01 },
    { "min": 10000, "price_per_credit": 0.008 },
    { "min": 100000, "price_per_credit": 0.006 }
  ]
}

Prices are in US dollars. Read the tiers from this endpoint rather than hard-coding them, since they can change. See Credits for what each endpoint costs.

POST /v1/checkout

Creates a Stripe Checkout session for a one-time credit purchase and returns its URL. Open the URL in a browser to pay; credits are added to the workspace after payment succeeds. Only workspace owners and admins can start a purchase.

curl -X POST "https://api.rankparse.com/v1/checkout" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10000}'

{ "url": "https://checkout.stripe.com/c/pay/cs_live_..." }

Errors:

For hands-off top-ups, use auto recharge in the dashboard. See Credits.

Related