# Quickstart

> Introduction to the Tradavity Public API, with a zero-to-first-call walkthrough.
> Source: https://help.tradavity.com/api-docs/quickstart
> Category: Getting Started

---

The Tradavity Public API gives you programmatic access to your trading journal data over HTTP. Use it to build custom dashboards, feed an AI agent with your trade history, automate journaling from a script, or sync data with external tools.

The API is REST-style, returns JSON, authenticates with a Bearer token, and is per-user only — every key is bound to one account and can only see that account’s data.

> **Read and write are both live**
> Every resource has both read (GET) and write (POST/PATCH/PUT/DELETE) endpoints. Browse them by feature in the **Resources** sidebar section, or jump straight to [Trades](https://help.tradavity.com/api-docs/trades), [Accounts](https://help.tradavity.com/api-docs/accounts), [Goals](https://help.tradavity.com/api-docs/goals), [Protocols](https://help.tradavity.com/api-docs/protocols), and more.

## What you can do

**Read:**

- List and read trades with full filters (date range, symbol, account, strategy, grade, tag, P&L bounds, copy-trade flag), with cursor pagination across the full history.
- Fetch a single trade in full detail — executions, tags, confirmations, screenshot metadata, copy-trade source.
- Download screenshot files (JPG, PNG, PDF) attached to trades.
- Read accounts, balance status, daily snapshots, balance events, payouts.
- Read goals and their period-by-period progress snapshots.
- Read protocols (pre-market checklists, EOD reviews) and recorded responses.
- Read journal entries, strategies, setups, tags, copy groups, emotions, confirmation templates.
- Read calendar P&L, aggregate stats summary, stats by strategy, stats by symbol.
- Read catalog data: brokers, instruments, prop firm presets.
- Read auto-sync connection status and sync history (no token material is ever exposed).

**Write:**

- Create / update / archive trades; chain tags, confirmations, and screenshot uploads onto them.
- Create / update / delete journal entries, tags, tag categories, strategies + setups, goals, protocols + responses, accounts, copy groups + members.
- Record manual balance events; request payouts.
- Trigger a manual broker auto-sync.

## Base URL

All v1 endpoints live under:

```
https://app.tradavity.com/api/v1
```

The version (`/v1/`) is locked — we will never break this contract within v1. Future incompatible changes ship under a new version prefix.

---

## Quickstart

Three steps from zero to a working API call.

### 1. Generate an API key

In Tradavity, open **Settings → API** and click **+ New Key**. Give the key a name (e.g. *My AI Agent*), pick scopes, and optionally set an expiry. After clicking **Create**, your full key is shown **once** — copy it and store it somewhere safe (a password manager or secrets store). After you close the modal, only the prefix is visible.

API keys start with `tvty_` followed by 48 hex characters.

> **Treat keys like passwords**
> Anyone with your key can read your journal data within its scopes. Never embed it in client-side code, mobile apps, or public repositories. Always store keys in environment variables or a secrets manager. Revoke a key from the settings page the moment you suspect it has been exposed.

### 2. Test the connection

Hit `/me` — this returns the calling user, the key’s scopes, and the current rate-limit window. It works with any key and is the easiest smoke test.

```bash
curl https://app.tradavity.com/api/v1/me \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE"
```

You should get back a JSON object with `"ok": true` and your user, plan, preferences, and key info.

### 3. Make a real request

Pull your last 50 trades:

```bash
curl https://app.tradavity.com/api/v1/trades \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE"
```

Or filter to a date range and account:

```bash
curl "https://app.tradavity.com/api/v1/trades?from=2026-04-01&to=2026-04-30&account=My%20Account" \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE"
```

See the [Resources reference](https://help.tradavity.com/api-docs/category/resources) for the full list of endpoints per feature.

---

Next reads: [Authentication](https://help.tradavity.com/api-docs/authentication) · [Idempotency](https://help.tradavity.com/api-docs/idempotency) · [Conventions](https://help.tradavity.com/api-docs/conventions).