{
    "openapi": "3.1.0",
    "info": {
        "title": "RankGenius API",
        "version": "1.0.0",
        "description": "Real-time Amazon marketplace data (keyword rank, Buy Box, product pages, reviews) across 21 marketplaces. Agents can self-register for a free trial at POST /register, then call the tools with the returned key as a Bearer token. See https://rankgeniusapp.com/docs/agents and https://rankgeniusapp.com/llms.txt."
    },
    "servers": [
        {
            "url": "https://rankgeniusapp.com/api/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/register": {
            "post": {
                "operationId": "registerTrial",
                "summary": "Create a machine trial account and get an API key (no auth, no email).",
                "description": "Self-serve signup for AI agents. Returns an API key with 100 free requests, usable over this REST API only (not MCP, no watches). When the trial is spent the tool endpoints return 402 with an upgrade_url a human visits to unlock full access \u2014 the same key keeps working. Rate-limited per IP/subnet.",
                "security": [],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/TrialRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Trial key issued.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TrialResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Trial signup is not currently enabled."
                    },
                    "405": {
                        "description": "Method not allowed \u2014 use POST."
                    },
                    "429": {
                        "description": "Trial key limit reached for your IP/subnet."
                    }
                }
            }
        },
        "/keyword_rank": {
            "get": {
                "operationId": "keyword_rank",
                "summary": "Live Amazon organic search results (page rank) for a keyword.",
                "description": "Returns each organic result with its rank (on-page position), price (incl. list price, discount %, coupon, and per-item price when present), review count, rating, monthly-sales estimate, Prime/stock, delivery estimates, and badges, plus related_keywords. Results are organic only \u2014 sponsored/ad placements are excluded. One call returns a single page (~48 results); pass page = 2, 3, \u2026 to go deeper. has_more and last_page tell you whether more pages exist, and page echoes the page returned. Pass an optional asin to get a target block with that product's exact position on the requested page (if it flags \"not ranked\", the ASIN simply isn't on that page \u2014 request a higher page to find its true position). Pass an optional zip to localize the SERP \u2014 Amazon's ranking and which products appear vary by zip, and pinning one makes results stable and comparable across calls. delivery_to reflects the zip used.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "keyword",
                        "in": "query",
                        "required": true,
                        "description": "The search keyword/phrase.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "marketplace",
                        "in": "query",
                        "required": false,
                        "description": "Amazon marketplace/country code. Default us. 21 supported (us, uk, ca, de, fr, es, it, nl, se, pl, be, tr, sa, ae, eg, in, jp, au, sg, mx, br).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "asin",
                        "in": "query",
                        "required": false,
                        "description": "Optional ASIN to locate within the results.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "zip",
                        "in": "query",
                        "required": false,
                        "description": "Optional delivery postal code to localize results (supported in the US, UK, Germany, France & Canada; same set as buybox). Call supported_zips for the list per marketplace, e.g. 30303 (US) or B1 1BB (UK). Unsupported codes return an error.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Results page number (default 1, ~48 results/page). Use has_more/last_page to page deeper \u2014 each page is one metered request.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Freshness window in seconds (default 3600, max 86400). If your account already ran this exact request within since seconds, the cached result is returned for free \u2014 cached: true, no credits charged. Pass 0 to force a live, freshly-charged lookup.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid parameter or upstream lookup failed."
                    },
                    "401": {
                        "description": "Invalid or missing API key."
                    },
                    "402": {
                        "description": "Out of credits \u2014 see error for the upgrade path."
                    },
                    "429": {
                        "description": "Trial topic throttle: this query hit its free-trial limit on your network."
                    }
                }
            }
        },
        "/buybox": {
            "get": {
                "operationId": "buybox",
                "summary": "Who owns the Buy Box for an ASIN, plus price, stock, and delivery.",
                "description": "Returns the owning seller id and name, winning price/currency, in-stock flag and stock \"only N left\" counter, FBA vs. merchant + ships_from, Prime status, and any used/used_price offer. seller_id, ships_from, fba, stock, and the used-offer fields are null when Amazon itself holds the Buy Box and populate for third-party listings. Pass an optional zip to add a location-specific delivery estimate \u2014 the response then also includes delivery_to, fastest_delivery, free_delivery, and free_shipping (only a fixed set of US postal codes is supported; others return an error).",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "asin",
                        "in": "query",
                        "required": true,
                        "description": "The product ASIN.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "marketplace",
                        "in": "query",
                        "required": false,
                        "description": "Amazon marketplace/country code. Default us. 21 supported (us, uk, ca, de, fr, es, it, nl, se, pl, be, tr, sa, ae, eg, in, jp, au, sg, mx, br).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "zip",
                        "in": "query",
                        "required": false,
                        "description": "Optional destination postal code for a delivery estimate (supported in the US, UK, Germany, France & Canada; call supported_zips for the list per marketplace, e.g. 30303 (US) or B1 1BB (UK)).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Freshness window in seconds (default 3600, max 86400). If your account already ran this exact request within since seconds, the cached result is returned for free \u2014 cached: true, no credits charged. Pass 0 to force a live, freshly-charged lookup.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid parameter or upstream lookup failed."
                    },
                    "401": {
                        "description": "Invalid or missing API key."
                    },
                    "402": {
                        "description": "Out of credits \u2014 see error for the upgrade path."
                    },
                    "429": {
                        "description": "Trial topic throttle: this query hit its free-trial limit on your network."
                    }
                }
            }
        },
        "/product_page": {
            "get": {
                "operationId": "product_page",
                "summary": "Structured product details parsed from the listing \u2014 title, rating, bullets, BSR, images, variations, and more.",
                "description": "Parses the major elements out of the live product page into a product object \u2014 title, brand, star rating and ratings count, \"about this item\" bullets, category breadcrumbs, Best Sellers Rank, image URLs, availability, variations (colour/size/style and the sibling ASINs), badges (e.g. frequently_returned, amazons_choice, climate_pledge_friendly), whether it has A+ content, and the buy-box seller/fulfillment. Also returns a full details attribute table (material, dimensions, weight, UPC/GTIN, model, care instructions, \u2026), the AI-generated customer_say review summary, monthly_sales (recent purchase volume), A+ image/video URLs, and review_insights (per-aspect sentiment). (For a reliable price/currency, use buybox.)",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "asin",
                        "in": "query",
                        "required": true,
                        "description": "The product ASIN.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "marketplace",
                        "in": "query",
                        "required": false,
                        "description": "Amazon marketplace/country code. Default us. 21 supported (us, uk, ca, de, fr, es, it, nl, se, pl, be, tr, sa, ae, eg, in, jp, au, sg, mx, br).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Freshness window in seconds (default 3600, max 86400). If your account already ran this exact request within since seconds, the cached result is returned for free \u2014 cached: true, no credits charged. Pass 0 to force a live, freshly-charged lookup.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid parameter or upstream lookup failed."
                    },
                    "401": {
                        "description": "Invalid or missing API key."
                    },
                    "402": {
                        "description": "Out of credits \u2014 see error for the upgrade path."
                    },
                    "429": {
                        "description": "Trial topic throttle: this query hit its free-trial limit on your network."
                    }
                }
            }
        },
        "/product_reviews": {
            "get": {
                "operationId": "product_reviews",
                "summary": "Customer reviews for an ASIN \u2014 paginated, with the star breakdown.",
                "description": "Returns customer reviews for a product, one page at a time (~10 per page). Each review carries rating, title, author, verified/vine flags, helpful_votes, body text, and any review images/videos. Aggregates: product_rating (e.g. 4.6); rating_count = all star ratings (with or without written text); review_count = written reviews only, so it is normally much smaller than rating_count (they are not meant to match). star_breakdown is the percentage at each 1\u20135 stars (Amazon publishes no per-star counts; multiply by rating_count for an estimate). Walk pages with page (has_more/last_page); sort with sort: recent (chronological, newest first) or helpful (Amazon's \"Top reviews\" order \u2014 Amazon's own relevance ranking, which factors in recency and verified purchases, so it is not a strict most-helpful-votes sort and low-vote reviews can appear first). Amazon exposes only ~100 reviews per sort: last_page reflects those accessible pages and can be far below review_count \u2014 you cannot page to every review.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "asin",
                        "in": "query",
                        "required": true,
                        "description": "The product ASIN.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "marketplace",
                        "in": "query",
                        "required": false,
                        "description": "Amazon marketplace/country code. Default us. 21 supported (us, uk, ca, de, fr, es, it, nl, se, pl, be, tr, sa, ae, eg, in, jp, au, sg, mx, br).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Review page number (~10/page). Default 1.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "description": "Sort order: recent (default, newest first) or helpful (Amazon's \"Top reviews\" relevance order, not a strict helpful-vote sort).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Freshness window in seconds (default 3600, max 86400). If your account already ran this exact request within since seconds, the cached result is returned for free \u2014 cached: true, no credits charged. Pass 0 to force a live, freshly-charged lookup.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid parameter or upstream lookup failed."
                    },
                    "401": {
                        "description": "Invalid or missing API key."
                    },
                    "402": {
                        "description": "Out of credits \u2014 see error for the upgrade path."
                    },
                    "429": {
                        "description": "Trial topic throttle: this query hit its free-trial limit on your network."
                    }
                }
            }
        },
        "/supported_zips": {
            "get": {
                "operationId": "supported_zips",
                "summary": "The delivery zip / postal codes accepted by the optional zip parameter.",
                "description": "Lists the delivery codes that keyword_rank and buybox accept as an optional zip (unsupported codes are rejected). Returns { zip, delivery } rows for the marketplace. Not metered \u2014 it doesn't spend credits. The full list is also browsable at /docs/zip-codes.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "marketplace",
                        "in": "query",
                        "required": false,
                        "description": "Amazon marketplace/country code. Default us. 21 supported (us, uk, ca, de, fr, es, it, nl, se, pl, be, tr, sa, ae, eg, in, jp, au, sg, mx, br).",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid parameter or upstream lookup failed."
                    },
                    "401": {
                        "description": "Invalid or missing API key."
                    },
                    "402": {
                        "description": "Out of credits \u2014 see error for the upgrade path."
                    },
                    "429": {
                        "description": "Trial topic throttle: this query hit its free-trial limit on your network."
                    }
                }
            }
        },
        "/whoami": {
            "get": {
                "operationId": "whoami",
                "summary": "Return the authenticated account, plan, and remaining credit balance.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Account info.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Account API key."
            }
        },
        "schemas": {
            "Envelope": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "ok",
                            "error"
                        ]
                    },
                    "error": {
                        "type": "string",
                        "description": "Message when status=error, else empty."
                    },
                    "data": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "description": "Tool payload on success; null on error."
                    }
                },
                "required": [
                    "status",
                    "error",
                    "data"
                ]
            },
            "TrialRequest": {
                "type": "object",
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email",
                        "description": "Optional owner/agent contact. Not required, never verified until upgrade."
                    },
                    "label": {
                        "type": "string",
                        "description": "Optional label for the trial (e.g. your agent/app name)."
                    }
                }
            },
            "TrialResponse": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string"
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "api_key": {
                                "type": "string"
                            },
                            "account_id": {
                                "type": "string"
                            },
                            "plan": {
                                "type": "string",
                                "example": "trial"
                            },
                            "credits": {
                                "type": "integer"
                            },
                            "requests_remaining": {
                                "type": "integer",
                                "example": 100
                            },
                            "tools": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "watches_allowed": {
                                "type": "boolean",
                                "example": false
                            },
                            "mcp_allowed": {
                                "type": "boolean",
                                "example": false
                            },
                            "upgrade_url": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            }
        }
    }
}