Worked example: AI agent journaling a trade

An AI agent reading user voice notes wants to create a fully-journaled trade with a screenshot and tags. Four chained calls. The numeric IDs in this snippet (account 192, tags 19/109, protocol 80, items 640/641) are illustrative — always discover real IDs for your user first.

# 0. Discover real IDs (every account/tag/protocol ID below is yours, not ours)
curl -s "https://app.tradavity.com/api/v1/accounts"           -H "Authorization: Bearer $KEY"
curl -s "https://app.tradavity.com/api/v1/tags"               -H "Authorization: Bearer $KEY"
curl -s "https://app.tradavity.com/api/v1/protocols"          -H "Authorization: Bearer $KEY"
# For protocol item_ids, fetch the single protocol:
curl -s "https://app.tradavity.com/api/v1/protocols/80"       -H "Authorization: Bearer $KEY"

# 1. Create the trade
TRADE=$(curl -s -X POST https://app.tradavity.com/api/v1/trades \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: agent-$(date +%s)-trade" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 192,
    "trade_date": "2026-05-10T14:32:00Z",
    "symbol": "MNQ",
    "direction": "long",
    "quantity": 1,
    "multiplier": 2,
    "net_pnl": 50.0,
    "fees": 1.24,
    "trade_quality_grade": "A",
    "general_notes": "Strong breakout, executed plan."
  }')
TRADE_NUMBER=$(echo "$TRADE" | jq -r .data.trade.trade_number)

# 2. Tag it
curl -s -X PUT "https://app.tradavity.com/api/v1/trades/$TRADE_NUMBER/tags" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": [19, 109]}'

# 3. Attach a chart screenshot
curl -s -X POST "https://app.tradavity.com/api/v1/trades/$TRADE_NUMBER/screenshots" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: agent-$(date +%s)-screenshot" \
  -F "file=@/tmp/chart.png" \
  -F "label=Entry breakout"

# 4. Record a pre-trade protocol response linked to it
curl -s -X POST "https://app.tradavity.com/api/v1/protocols/80/responses" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: agent-$(date +%s)-protocol" \
  -H "Content-Type: application/json" \
  -d "{\"trade_number\": $TRADE_NUMBER, \"item_values\": {\"640\":\"1\",\"641\":\"yes\"}}"

Note the Idempotency-Key on every write — if the agent retries any step after a network blip, it returns the cached response without double-creating.