Quickstart

1. Try a public endpoint

Rankings are public, so this works before you have a key:

curl https://api.recomention.com/v1/rankings

You get every category’s latest ranking: the questions asked, the engines, and the five brands named most, with counts.

2. Create an API key

1. Sign in at recomention.com/account with Google, Apple or a one-time email link.
2. Open Developers and create a key. Give it a name that says where it will live, such as “laptop” or “CI”.
3. Copy it now. The key is shown once. It starts with rmk_.

Put it in your shell’s environment, not in a file you might commit:

export RECOMENTION_API_KEY="rmk_…"

3. List your reports

curl https://api.recomention.com/v1/reports \
  -H "Authorization: Bearer $RECOMENTION_API_KEY"

A new account returns {"reports": []}. A 401 means the key is missing, mistyped or revoked; see Authentication.

4. Start a report

Starting a report spends money: an agency credit, or calls on your own provider keys. The body says which, and nothing runs without it.

curl -X POST https://api.recomention.com/v1/reports \
  -H "Authorization: Bearer $RECOMENTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "domain": "example.com",
    "category": "meeting scheduling",
    "description": "Booking links for sales teams",
    "plan": "FULL",
    "funding": "credits"
  }'

The answer is 202 with the report’s slug and a statusUrl. A report takes several minutes; poll the status about once a minute, then read it. The Reports guide walks through every step.

Next

• Errors — what each status code means.
• Rate limits & idempotency — retry safely.
• MCP server — let your coding agent do all of this.