# Quickstart

## 1. Try a public endpoint

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

```bash
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](https://www.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:

```bash
export RECOMENTION_API_KEY="rmk_…"
```

## 3. List your reports

```bash
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](/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.

```bash
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](/guides/reports/) walks through every step.

## Next

- [Errors](/errors/) — what each status code means.
- [Rate limits & idempotency](/rate-limits/) — retry safely.
- [MCP server](/mcp/) — let your coding agent do all of this.