AI Agent Quickstart

RankGenius is built for autonomous agents. Get a free trial key in a single unauthenticated request — no signup form, no email, no human — and start pulling live Amazon data in seconds. When you've proven the value, a human unlocks the full account and your key keeps working.

Machine-readable companions: /llms.txt (agent-oriented summary) and /openapi.json (OpenAPI 3.1 spec, generated from the live tool definitions).

1. Get a trial key

POST to the registration endpoint. No authentication. Both fields are optional — label names the trial (e.g. your agent/app), email is a contact for later (never required, never verified until you upgrade).

You get back an API key with 100 free requests.

curl -X POST https://rankgeniusapp.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"label": "my-agent"}'

{
    "status": "ok",
    "data": {
        "api_key": "<your-api-key>",
        "account_id": "q8ggtvf0",
        "plan": "trial",
        "credits": 1000,
        "requests_remaining": 100,
        "tools": ["keyword_rank", "buybox", "product_page", "product_reviews"],
        "watches_allowed": false,
        "mcp_allowed": false,
        "upgrade_url": "https://rankgeniusapp.com/claim/…"
    }
}

2. Call the tools

Send the key as a Bearer token on every request. Every response is the same envelope — { "status", "error", "data" }.

curl "https://rankgeniusapp.com/api/v1/keyword_rank?keyword=insulated+water+bottle&marketplace=us" \
  -H "Authorization: Bearer <your-api-key>"

The trial covers all read tools:

Tool	What it returns
`keyword_rank`	Live Amazon organic search results (page rank) for a keyword. params →
`buybox`	Who owns the Buy Box for an ASIN, plus price, stock, and delivery. params →
`product_page`	Structured product details parsed from the listing — title, rating, bullets, BSR, images, variations, and more. params →
`product_reviews`	Customer reviews for an ASIN — paginated, with the star breakdown. params →
`supported_zips`	The delivery zip / postal codes accepted by the optional zip parameter. params →

Full parameters and example responses are in the REST API reference. A repeat of the same request within the free-repeat window returns a cached result at no cost (cached: true).

3. What a trial key can and can't do

Capability	Trial	Full account
REST read tools (`keyword_rank`, `buybox`, `product_page`, `product_reviews`)	100 requests	Yes
MCP server	—	Yes
Watches (scheduled tracking)	—	Yes
Buy more credits	upgrade first	Yes

Trials are rate-limited and intended for evaluating the API, not running a production workload. Upgrade for unlimited use.

4. Errors & the upgrade handoff

HTTP status	Meaning
`200`	Success — `data` holds the payload.
`400`	Missing/invalid parameter or the lookup failed. See `error`.
`401`	Invalid or missing API key.
`402`	Trial spent (all 100 requests used). `error` includes the `upgrade_url`.
`403`	Feature not available on a trial key (MCP or watches) — includes the `upgrade_url`.
`429`	Rate/topic limit reached — includes the `upgrade_url`.

When you hit a 402/403/429, the error message carries an upgrade_url. Surface that link to your human operator: they open it, verify an email, and set a password. That claims the trial — the account becomes a full account and your existing API key keeps working, along with all the usage history from the trial. From then on it can buy credits, connect over MCP, and create watches.

Agent tip: the registration response is self-describing — read requests_remaining, watches_allowed, mcp_allowed, and upgrade_url to drive your flow without hard-coding limits. When a call returns a non-200 with an upgrade_url in error, hand that URL to your operator.