---
name: keysso-api
description: Query the GroupBuySEO Keys.so API gateway (wire-compatible with official Keys.so REST) for Russian-market organic/context keywords, competitors, backlinks and similar phrases. Use when the user asks for Keys.so metrics, wildberries-style domain reports, or wants to script against api.keys.so without a Keys.so Corporate token.
metadata:
  vendor: GroupBuySEO
  homepage: https://my.groupbuyseo.org/dashboard/api/products
  api_base_url: https://keysso-api.groupbuyseo.org
---

# Keys.so API (GroupBuySEO gateway)

Wire-compatible drop-in for **official Keys.so REST** — same paths and query
names, only the host changes.

```
GET https://keysso-api.groupbuyseo.org/<path>?<params>
X-Keyso-TOKEN: $KEYSSO_API_KEY
```

Auth: header **`X-Keyso-TOKEN`** (query `auth-token` also works). Read the key
from `$KEYSSO_API_KEY`; never hardcode it. Key lives at
<https://my.groupbuyseo.org/dashboard/api/keys>.

This is the **JSON API product**, not the website proxy (`keys-so.groupbuyseo.org`)
and not the SPA companion (`api-keys-so.groupbuyseo.org`).

## Use the script, not raw curl

List endpoints return paginated `{ data, total, current_page }`. A fat organic
report can be millions of rows. `scripts/keysso.mjs` retries `429`/`502`/`503`,
defaults `per_page=5`, and prints compact tables.

```bash
node scripts/keysso.mjs list
node scripts/keysso.mjs get domain_dashboard --domain wildberries.ru --base msk
node scripts/keysso.mjs get organic_keywords --domain wildberries.ru --page 1 --per_page 5 --table
node scripts/keysso.mjs get similarkeys --keyword "пластиковые окна" --base msk
node scripts/keysso.mjs limits
```

Add `--json` only if you must post-process, `--dry-run` to print the URL.

## The five rules that cause most failures

1. **Keep official spellings:** `concurents`, `sitepages`, `similarkeys`.
2. **Default region is `msk`.** AI reports are msk-only. Links / RSYa take **no** `base`.
3. **Nested reports need extra keys:** `concurent_pages` → `page_url`;
   `keywords/byads` → `ads_id`; `owner/subdomains` → `domain` **and** `id`
   (Keys.so saved-site id, not the dashboard domain id).
4. **Query param is `page`, not `current_page`.** Envelope still uses `current_page`.
5. **Never POST/PATCH/DELETE.** Mutations write the shared workspace → `403`.
   Do not call `/users/current` (leaks the rented token).

## Cost

**1 GBS credit per 2xx**, except `GET /limits/all` (free, GBS remaining) and
HTTP **202** (accepted, retry later — not charged). 4xx/5xx are free.
`/limits/all` `apiRequest` is **our** remaining, not Keys.so Corporate remaining.

## Errors

`{ "message": "Unauthenticated" }` 401 bad/missing key · 400 missing param ·
402 credits exhausted · 403 method not allowed · 404 unknown path or Keys.so
“запрос не найден” · 429 back off · 503 upstream down.

## Reference files

| File | Read it when |
|---|---|
| `reference/endpoints.md` | Full path list, required params, `base` / filter notes |

Official upstream docs: <https://apidoc.keys.so/>.
