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
Create a proposal
POST /v1/proposals: propose an IndexNow submission or outreach emails.
List proposals
GET /v1/proposals: the workspace's proposals, newest first.
Get a proposal
GET /v1/proposals/:id: one proposal and its outcome.
Authentication and scope
- Every route takes your
X-API-Keyand 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_idor proposal id of another workspace returns404, 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
| Kind | What it does once approved | Credits when it runs | Can run without a person |
|---|---|---|---|
indexnow_submit | Submits up to 1000 URLs on one of your websites to IndexNow. | 1, refunded on failure | Only when the website's policy for IndexNow is Automatic, within its daily URL limit |
outreach_send | Queues the reviewed outreach emails for sending from the website's Gmail mailbox. | 0 | Never |
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
| Status | Meaning |
|---|---|
pending | Waiting for a person. |
approved | Approved by a person (or an Automatic policy) and about to run, or waiting for a retry. |
executing | Running now. |
succeeded | Finished. result has the details. |
partially_succeeded | Outreach only: fewer emails were queued than the proposal held (some changed after review, or were suppressed). |
failed | Did not run to completion. error_code says why. A person can retry it in the app. |
skipped | A person declined it. |
expired | Nobody decided before it expired. |
superseded | Replaced by a newer proposal before anyone decided (a newer outreach proposal for the same campaign, or a newer sending change for the same mailbox). |
cancelled | A 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
| Limit | Value | Error |
|---|---|---|
| Pending proposals per website | 25 (expired ones do not count) | 429 too_many_pending_proposals |
| New proposals per account per UTC day | 100 | 429 daily_proposal_limit_reached |
| URLs per IndexNow proposal | 1000, about 1.9 MB in total | 400 invalid_proposal_input |
| Emails per agent outreach proposal | 100 | 400 invalid_proposal_input |
| Requests per minute | 60 | 429 rate_limited |
Failure codes
When a proposal ends failed (or partially_succeeded), error_code explains why. The common ones:
| Code | Meaning |
|---|---|
payload_changed_since_approval | The stored proposal no longer matches what was approved, so it did not run. Propose again. |
approver_lost_permission | The person who approved it no longer has permission to run it. Tell the user. |
nothing_to_send | Outreach: every email was already queued, sent, changed or suppressed by the time it ran. |
gmail_not_connected, plan_limit_reached | Outreach: the website's mailbox was not connected, or the plan does not cover this website or mailbox, when it ran. |
indexnow_host_not_a_website | The website was removed before the run. |
indexnow_key_not_verified | The IndexNow key file is not reachable at its key_location. |
insufficient_credits, spend_cap_reached | IndexNow could not be charged. |
indexnow_unavailable, indexnow_rate_limited, indexnow_key_rejected, indexnow_url_mismatch, indexnow_invalid_request | IndexNow refused or could not take the submission. The credit is refunded. |
execution_attempts_exhausted | The run kept failing and was stopped after 5 attempts. Any charge is refunded. |
A failed IndexNow run never keeps its credit.
Related
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.