Proposals

Proposals are how an agent asks for permission. You describe an action (submit URLs to IndexNow, send outreach emails), RankParse stores it as a pending item in the website owner's approval inbox, and nothing runs until a person approves it in the RankParse web app.

All four routes on this page cost 0 credits. Credits are spent only when an approved action runs: an IndexNow submission costs 1 credit at that moment, outreach costs 0.

Authentication and limits

• Auth: X-API-Key header, the same key as every other endpoint. See Authentication.
• Rate limit: 60 requests per minute per key. A 61st call in the window returns 429 with code: "rate_limited".
• The workspace is always the one your key belongs to. A site_id or proposal id from another workspace returns 404, never data.
• The routes on this page are not part of the secure OAuth connector's tool catalog today. See the MCP server page.

Create a proposal

POST /v1/proposals takes a JSON body with a kind plus that kind's fields.

Common fields

Unknown fields are rejected with 400 invalid_proposal_input. A workspace id can never be passed in the body.

Kind: indexnow_submit

Asks to notify Bing, Yandex, Seznam, Naver and other IndexNow engines about changed URLs.

The host must already have an IndexNow key (see POST /v1/indexnow/key); otherwise the call returns 400 indexnow_key_not_found. Whether the key file is actually hosted is checked when the proposal runs, not when it is created.

Kind: outreach_send

Asks to send link-building emails from the workspace's connected Gmail account. Two shapes:

Inline contacts. RankParse creates (or reuses) a draft campaign and adds the contacts, then proposes sending them.

Existing campaign. Propose the contacts a campaign already holds.

Contact fields: email (required, max 320), domain (required, the prospect domain, max 253), subject (required, max 500), body (required, plain text, max 10,000), name (optional, max 200), domain_authority (optional number; out-of-range values are stored as unknown).

An agent proposal snapshots at most 100 copy-ready contacts. Contacts that were already emailed in an earlier campaign are skipped, and a campaign holds at most 500 contacts.

Example

curl -X POST "https://api.rankparse.com/v1/proposals" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "indexnow_submit",
    "site_id": "site_abc123",
    "urls": ["https://example.com/blog/new-post", "https://example.com/pricing"],
    "note": "Published a new post and changed the pricing page."
  }'

import requests

res = requests.post(
    "https://api.rankparse.com/v1/proposals",
    headers={"X-API-Key": "rp_your_key"},
    json={
        "kind": "indexnow_submit",
        "site_id": "site_abc123",
        "urls": [
            "https://example.com/blog/new-post",
            "https://example.com/pricing",
        ],
        "note": "Published a new post and changed the pricing page.",
    },
)
print(res.status_code, res.json())

const res = await fetch("https://api.rankparse.com/v1/proposals", {
  method: "POST",
  headers: {
    "X-API-Key": "rp_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "indexnow_submit",
    site_id: "site_abc123",
    urls: ["https://example.com/blog/new-post", "https://example.com/pricing"],
    note: "Published a new post and changed the pricing page.",
  }),
});
console.log(res.status, await res.json());

Response

Most calls return 202 with a pending proposal:

{
  "status": "awaiting_approval",
  "proposal_id": "prp_V1StGXR8_Z5jdHi6B-myT",
  "review_url": "https://rankparse.com/dashboard/sites/site_abc123/today?proposal=prp_V1StGXR8_Z5jdHi6B-myT",
  "title": "Submit 2 URLs on example.com to IndexNow",
  "dedupe_hit": false,
  "message": "Waiting for the user's approval in RankParse: Submit 2 URLs on example.com to IndexNow. Nothing happens until they approve it. Tell the user to review it at the review_url, and check list_proposals later for the outcome."
}

Possible outcomes

Outreach is never automatic. Whatever the website's settings say, an outreach_send proposal always waits for a person.

List proposals

Returns the workspace's proposals, newest first, including ones created by RankParse itself (for example "pages not indexed" suggestions).

curl "https://api.rankparse.com/v1/proposals?status=pending&site_id=site_abc123" \
  -H "X-API-Key: rp_your_key"

{
  "proposals": [
    {
      "id": "prp_V1StGXR8_Z5jdHi6B-myT",
      "kind": "indexnow_submit",
      "status": "pending",
      "title": "Submit 2 URLs on example.com to IndexNow",
      "site_id": "site_abc123",
      "source": "agent",
      "estimated_credits": 1,
      "created_at": 1790000000000,
      "expires_at": 1790604800000,
      "decided_at": null,
      "decided_via": null,
      "result": null,
      "error_code": null
    }
  ]
}

There is no pagination cursor. To see older items, filter by status or site_id.

Get one proposal

Returns { "proposal": { ... } } with the same fields as a list item. An unknown id, a malformed id, and another workspace's id all return the same 404 proposal_not_found.

curl "https://api.rankparse.com/v1/proposals/prp_V1StGXR8_Z5jdHi6B-myT" \
  -H "X-API-Key: rp_your_key"

Proposal fields

The summary never contains the URLs, email addresses, subjects or bodies. Those stay in the proposal and are shown only to reviewers in the app.

Statuses

Terminal statuses are retained for 400 days. See Approval inbox for retention details.

Idempotency

There is no idempotency key to manage. RankParse derives a dedupe key from the content:

• IndexNow: the host plus the sorted, de-duplicated URL list.
• Outreach: the campaign plus the exact set of contacts that would be sent.

Proposing the same content again while the first is still open (pending, approved or executing) returns the same proposal_id with dedupe_hit: true and does not count against your limits. Retrying after a network error is therefore always safe. If a pending outreach proposal for a campaign is re-proposed with different contacts, the old one becomes superseded and the new one replaces it.

Limits

Expired pending proposals do not count toward the pending limit.

Errors

Errors use the standard shape, with error set to the same value as code:

{
  "error": "indexnow_host_not_a_website",
  "code": "indexnow_host_not_a_website",
  "message": "shop.example.org is not one of your RankParse websites"
}

See also Error codes.

Failure codes

When a proposal ends failed (or partially_succeeded), error_code explains why:

A failed IndexNow run never keeps its credit.

Related

MCP tools: propose_indexnow_submit, propose_outreach_send and list_proposals on the API-key MCP endpoint. See MCP server.