Data models

Core entities

My Prop Journal's API exposes several core entities that represent your trading data:

1. Trade Groups

A trade group represents a complete trade from entry to exit. Each trade contains:

Entry and exit prices, dates, and times
Overall P&L calculations (gross and net)
Position size and direction (long/short)
Status (win/loss/not_counted/open)
Associated executions (fills)

2. Executions

Executions are individual buy/sell orders that make up a trade. Each execution includes:

Side (buy/sell)
Price and quantity
Timestamp
Commission/fees
Execution type (scale_in, scale_out, full)

A single trade can have multiple executions (e.g., scaling in/out of positions).

3. Accounts

Trading accounts represent your prop firm or retail broker accounts. Fields include:

Account type (prop or retail)
Firm/broker name
Account number
Balance or current value
Status (for prop accounts)

4. Playbooks

Playbooks are collections of trading strategies and rules. Each playbook contains:

Name and description
Entry criteria (conditions to enter trades)
Exit criteria (conditions to exit trades)
Associated strategies

5. Strategies

Strategies are specific trading approaches within playbooks. Each strategy has:

Name and description
Parent playbook reference
Creation timestamp

6. Trading Plans

Trading plans are high-level business plans for your trading operation. Each plan includes:

Plan name and description
Multi-format content (JSON/HTML/Markdown)
Creation and update timestamps

7. Trade Writeups

Trade writeups provide post-trade analysis and reflections. Each writeup has:

Associated trade reference
Multi-format content for detailed notes
Lessons learned and improvement areas

8. Report Cards

Report cards are performance reviews for specific time periods. They include:

Date range for the review period
Multi-format content with performance analysis
Self-assessment and goals

9. Chart Books

Chart books organize trading charts and screenshots. Each chart book contains:

Name and description
Collection of chart images
Organization for different setups or strategies

10. Session Notes

Session notes capture daily trading journal entries. Each session note includes:

Session date
Multi-format content (JSON/HTML/Markdown)
Tags and optional quick notes (ticker-specific observations)

11. Quick Notes

Quick notes are short ticker-specific observations attached to a session note:

Symbol (optional)
Body text
Parent session note reference

12. Trader Notes

Trader notes are personal notes in the Trader's Notebook:

Rich text content (TipTap JSON)
Optional folder assignment
Tags for organization

13. Trader Folders

Trader folders organize trader notes hierarchically:

Name and color
Optional parent folder (nested folders)
Custom sort order

14. Rules

Rules define strategy-specific trading rules with parameters:

Description and category
Rule type and scope (account or trade)
Linked strategy reference
Sort order for display

15. Trade Rule Evaluations

Trade rule evaluations record how a trade performed against linked rules at review time:

Rule snapshot (name, type, parameters)
Result (passed or violated)
Violation details and severity
Evaluation timestamp

16. Embed References

Embed references identify embedded content within rich text fields:

Entity type (e.g., session_note, trade_writeup, playbook, trade)
Entity ID (UUID)

Used when parsing TipTap content for linked journal entries.

Entity relationships

Understanding how entities relate helps you build effective integrations:

Trade hierarchy

Account
  └─ Trade Group
       ├─ Execution 1 (entry)
       ├─ Execution 2 (scale in)
       ├─ Execution 3 (scale out)
       └─ Execution 4 (exit)

Example query pattern:

// Get all trades for a specific account
const trades = await fetch(
  `${BASE_URL}/trades?account_id=${accountId}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

// Each trade includes its executions
trades.data.forEach(trade => {
  console.log(`Trade ${trade.symbol}: ${trade.executions.length} fills`);
});

Playbook hierarchy

Playbook
  ├─ Entry Criteria
  │    ├─ Criterion 1
  │    └─ Criterion 2
  ├─ Exit Criteria
  │    ├─ Criterion 1
  │    └─ Criterion 2
  └─ Strategies
       ├─ Strategy 1
       └─ Strategy 2

Example query pattern:

# Get playbooks with all nested data
playbooks = get_playbooks()

for playbook in playbooks['data']:
    print(f"\n{playbook['name']}")
    print(f"  Entry rules: {len(playbook['entry_criteria'])}")
    print(f"  Exit rules: {len(playbook['exit_criteria'])}")
    print(f"  Strategies: {len(playbook['strategies'])}")

Data ownership and isolation

User-scoped data

All API operations are automatically scoped to the authenticated user:

Users can only access their own data
Cross-user queries return empty results or 404 errors
Data isolation is strictly enforced

Example:

// User A's API key
const userA_key = "mpj_user_a_key";

// User B's API key  
const userB_key = "mpj_user_b_key";

// User A creates a trade
const trade = await createTrade(tradeData, userA_key);
console.log(`Created trade: ${trade.data.id}`);

// User B tries to access User A's trade
const response = await fetch(
  `${BASE_URL}/trades/${trade.data.id}`,
  { headers: { Authorization: `Bearer ${userB_key}` } }
);

// Returns 404 - trade doesn't "exist" for User B
console.log(response.status); // 404

ID formats

All entity IDs are UUIDs (version 4):

Format: a1b2c3d4-e5f6-7890-1234-567890abcdef
Globally unique
Safe to use in URLs and JSON

Field types and formats

Dates and times

Dates: ISO 8601 date format (YYYY-MM-DD)
Times: 24-hour format (HH:MM:SS)
Timestamps: ISO 8601 with timezone (2024-01-15T10:30:00Z)

Examples:

{
  "entry_date": "2024-01-15",
  "entry_time": "10:30:00",
  "created_at": "2024-01-15T10:30:00Z"
}

Monetary values

Type: Number (float)
Precision: Up to 2 decimal places for currencies
Format: No currency symbols, just numeric values