# Scopes

> Scope catalog for the Tradavity Public API, with verb:resource semantics and the full read/write pairing.
> Source: https://help.tradavity.com/api-docs/scopes
> Category: Core Concepts

---

This page lists every scope you can grant an API key. The live catalog is also available via `GET /api/v1/scopes`, and you pick scopes interactively when you create a key in **Settings → API**.

Scopes restrict what a key can do. They follow a `verb:resource` pattern. `read` and `write` are independent — granting `write` does not imply `read` (this lets you create write-only audit loggers). Granular scope means a leaked key only exposes what you granted it.

When creating a key in the settings UI you have three presets:

- **Read everything** — all `read:*` scopes (recommended for AI agents that only consume data).
- **Read + Write everything** — all scopes (recommended for personal automation).
- **Custom** — pick exactly which read and write scopes to grant.

The full scope catalog:

| Read scope | Paired write scope | What it allows |
| --- | --- | --- |
| `read:trades` | `write:trades` | List + read trades, executions, tags, confirmations on a trade. Write: POST / PATCH / DELETE on trades, PUT on per-trade confirmations. |
| `read:accounts` | `write:accounts` | List + read trading accounts. Write: POST + PATCH on accounts. |
| `read:balance` | `write:balance` | Balance status, events, payouts, daily snapshots. Write: POST manual balance events and payout requests. |
| `read:goals` | `write:goals` | Goals + period progress history. Full CRUD on write. |
| `read:protocols` | `write:protocols` | Protocol templates + responses. Write: full protocol CRUD plus POST a recorded response. |
| `read:tags` | `write:tags` | Tags + tag categories. Write: full CRUD on both, plus PUT the tag set on a trade. |
| `read:strategies` | `write:strategies` | Strategies + setups + confirmation templates. Write: POST/PATCH/DELETE strategy with embedded setups upsert. |
| `read:screenshots` | `write:screenshots` | Download screenshot files. Write: POST multipart upload, DELETE archive. |
| `read:copy_groups` | `write:copy_groups` | Copy trading groups + members. Write: full CRUD on the group plus PUT the member set. |
| `read:autosync` | `write:autosync` | Auto-sync connection status + sync history. Write: trigger a manual sync. |
| `read:catalog` | — | Brokers, instruments, prop firm presets, emotions catalog. Granted automatically to every key. There is no `write:catalog` — catalog data is platform-managed. |

`read:settings` and `write:settings` are reserved in the scope catalog for future-use settings endpoints (general / calculation / grouping prefs). They are grantable today so existing keys can keep working when those endpoints land.

If a request needs a scope your key does not have, you get HTTP `403` with error code `forbidden_scope` and the required scope in `error.details.required_scope`.