Skip to Content
Proposals

Proposals

Ask a person to approve an action, then read back whether it ran. The shared rules for every proposals endpoint.

Proposals are how an agent asks for permission. You describe an action (submit URLs to IndexNow, put outreach emails up for review), RankParse stores it as a pending item for the website owner, and nothing runs until a person approves it in the RankParse web app. The approval inbox guide explains the model; this page holds the reference details every proposals operation shares.

Approval only happens in the web app. There is no API route to approve, skip, retry or run a proposal, and no API key, MCP tool or connector can do it. A leaked key can fill the inbox, never act on it.

Operations

Authentication and scope

  • Every route takes your X-API-Key and costs 0 credits. Credits are spent only when an approved action runs: an IndexNow submission costs 1 credit at that moment (refunded if it fails), outreach costs nothing.
  • All three routes share the limit of 60 requests per minute per key (429 rate_limited).
  • The workspace is always the one your key belongs to. A workspace id is never read from the request, and a site_id or proposal id of another workspace returns 404, never data.
  • If the approval inbox is not switched on for your account, creating a proposal returns 403 approval_inbox_not_enabled. Do not retry.

Kinds

KindWhat it does once approvedCredits when it runsCan run without a person
indexnow_submitSubmits up to 1000 URLs on one of your websites to IndexNow.1, refunded on failureOnly when the website's policy for IndexNow is Automatic, within its daily URL limit
outreach_sendQueues the reviewed outreach emails for sending from the website's Gmail mailbox.0Never

An agent can create only these two kinds. Lists also show kinds RankParse creates itself: investigate_drop (a rank-drop investigation that, once approved, becomes an agent task) and outreach_sending_change (an agent's request to raise a mailbox's daily cap or turn sending on, see Update sending settings).

Statuses

StatusMeaning
pendingWaiting for a person.
approvedApproved by a person (or an Automatic policy) and about to run, or waiting for a retry.
executingRunning now.
succeededFinished. result has the details.
partially_succeededOutreach only: fewer emails were queued than the proposal held (some changed after review, or were suppressed).
failedDid not run to completion. error_code says why. A person can retry it in the app.
skippedA person declined it.
expiredNobody decided before it expired.
supersededReplaced by a newer proposal before anyone decided (a newer outreach proposal for the same campaign, or a newer sending change for the same mailbox).
cancelledA reviewer removed every email from an outreach proposal, leaving nothing to send.

A pending proposal expires after 14 days (outreach), 7 days (IndexNow and rank-drop investigations) or 3 days (sending changes). Finished proposals are kept for 400 days.

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 emails that would be sent.

Proposing the same content while an earlier proposal is still open (pending, approved or executing) returns that proposal with dedupe_hit: true and does not count against your limits, so retrying after a network error is safe. If it was already approved, the answer is status: "approved": do not propose it again. A new outreach proposal for a campaign with a different set of emails supersedes the campaign's pending one.

client_request_id is accepted and validated on create, and otherwise ignored.

Limits

LimitValueError
Pending proposals per website25 (expired ones do not count)429 too_many_pending_proposals
New proposals per account per UTC day100429 daily_proposal_limit_reached
URLs per IndexNow proposal1000, about 1.9 MB in total400 invalid_proposal_input
Emails per agent outreach proposal100400 invalid_proposal_input
Requests per minute60429 rate_limited

Failure codes

When a proposal ends failed (or partially_succeeded), error_code explains why. The common ones:

CodeMeaning
payload_changed_since_approvalThe stored proposal no longer matches what was approved, so it did not run. Propose again.
approver_lost_permissionThe person who approved it no longer has permission to run it. Tell the user.
nothing_to_sendOutreach: every email was already queued, sent, changed or suppressed by the time it ran.
gmail_not_connected, plan_limit_reachedOutreach: the website's mailbox was not connected, or the plan does not cover this website or mailbox, when it ran.
indexnow_host_not_a_websiteThe website was removed before the run.
indexnow_key_not_verifiedThe IndexNow key file is not reachable at its key_location.
insufficient_credits, spend_cap_reachedIndexNow could not be charged.
indexnow_unavailable, indexnow_rate_limited, indexnow_key_rejected, indexnow_url_mismatch, indexnow_invalid_requestIndexNow refused or could not take the submission. The credit is refunded.
execution_attempts_exhaustedThe run kept failing and was stopped after 5 attempts. Any charge is refunded.

A failed IndexNow run never keeps its credit.

MCP tools on the API-key MCP endpoint: propose_indexnow_submit, propose_outreach_send and list_proposals (there is no tool for reading one proposal). The OAuth connector exposes list_proposals, and its propose tools only where the actions:propose permission has been switched on. See MCP server.

On this page