openapi: 3.0.3
info:
  title: 'TradeJournal Lab API Documentation'
  description: 'TradeJournal Lab API — Programmatic access to your trade journal data, stats, and leaderboard.'
  version: 1.0.0
servers:
  -
    url: 'https://tradejournallab.com'
tags:
  -
    name: 'Public API'
    description: "\nEndpoints for external integrations via API keys.\nAll endpoints require a valid API key in the `Authorization: Bearer {key}` header."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.'
security:
  -
    default: []
paths:
  /api/v1/trades:
    get:
      summary: 'List trades'
      operationId: listTrades
      description: 'Get a paginated list of your trades with optional filters.'
      parameters:
        -
          in: query
          name: from
          description: 'Filter trades from this date (YYYY-MM-DD).'
          example: '2025-01-01'
          required: false
          schema:
            type: string
            description: 'Filter trades from this date (YYYY-MM-DD).'
            example: '2025-01-01'
        -
          in: query
          name: to
          description: 'Filter trades up to this date (YYYY-MM-DD).'
          example: '2025-12-31'
          required: false
          schema:
            type: string
            description: 'Filter trades up to this date (YYYY-MM-DD).'
            example: '2025-12-31'
        -
          in: query
          name: instrument
          description: 'Filter by instrument/symbol.'
          example: BTCUSDT
          required: false
          schema:
            type: string
            description: 'Filter by instrument/symbol.'
            example: BTCUSDT
        -
          in: query
          name: side
          description: 'Filter by trade side.'
          example: long
          required: false
          schema:
            type: string
            description: 'Filter by trade side.'
            example: long
        -
          in: query
          name: per_page
          description: 'Number of results per page (1-100).'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Number of results per page (1-100).'
            example: 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      instrument: BTCUSDT
                      side: long
                      quantity: 0.5
                      entry_time: '2025-03-15T10:30:00.000000Z'
                      entry_price: 65000.0
                      exit_time: '2025-03-15T14:00:00.000000Z'
                      exit_price: 66500.0
                      pnl: 750.0
                      net_pnl: 748.5
                      commission: 1.5
                      setup_type: breakout
                      notes: 'Strong momentum breakout'
                  current_page: 1
                  last_page: 3
                  per_page: 25
                  total: 72
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        instrument: BTCUSDT
                        side: long
                        quantity: 0.5
                        entry_time: '2025-03-15T10:30:00.000000Z'
                        entry_price: 65000
                        exit_time: '2025-03-15T14:00:00.000000Z'
                        exit_price: 66500
                        pnl: 750
                        net_pnl: 748.5
                        commission: 1.5
                        setup_type: breakout
                        notes: 'Strong momentum breakout'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        instrument:
                          type: string
                          example: BTCUSDT
                        side:
                          type: string
                          example: long
                        quantity:
                          type: number
                          example: 0.5
                        entry_time:
                          type: string
                          example: '2025-03-15T10:30:00.000000Z'
                        entry_price:
                          type: number
                          example: 65000.0
                        exit_time:
                          type: string
                          example: '2025-03-15T14:00:00.000000Z'
                        exit_price:
                          type: number
                          example: 66500.0
                        pnl:
                          type: number
                          example: 750.0
                        net_pnl:
                          type: number
                          example: 748.5
                        commission:
                          type: number
                          example: 1.5
                        setup_type:
                          type: string
                          example: breakout
                        notes:
                          type: string
                          example: 'Strong momentum breakout'
                  current_page:
                    type: integer
                    example: 1
                  last_page:
                    type: integer
                    example: 3
                  per_page:
                    type: integer
                    example: 25
                  total:
                    type: integer
                    example: 72
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Insufficient scope: trades:read required'
                properties:
                  error:
                    type: string
                    example: 'Insufficient scope: trades:read required'
      tags:
        - 'Public API'
    post:
      summary: 'Create a trade'
      operationId: createATrade
      description: 'Create a new trade in your journal.'
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  id: 99
                  instrument: BTCUSDT
                  side: long
                  entry_price: 65000.0
                  message: 'Trade created'
                properties:
                  id:
                    type: integer
                    example: 99
                  instrument:
                    type: string
                    example: BTCUSDT
                  side:
                    type: string
                    example: long
                  entry_price:
                    type: number
                    example: 65000.0
                  message:
                    type: string
                    example: 'Trade created'
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Insufficient scope: trades:write required'
                properties:
                  error:
                    type: string
                    example: 'Insufficient scope: trades:write required'
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Validation failed'
                  details:
                    instrument:
                      - 'The instrument field is required.'
                properties:
                  error:
                    type: string
                    example: 'Validation failed'
                  details:
                    type: object
                    properties:
                      instrument:
                        type: array
                        example:
                          - 'The instrument field is required.'
                        items:
                          type: string
      tags:
        - 'Public API'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                instrument:
                  type: string
                  description: 'The trading instrument.'
                  example: BTCUSDT
                side:
                  type: string
                  description: 'Trade direction: long or short.'
                  example: long
                quantity:
                  type: number
                  description: 'Trade size/volume.'
                  example: 0.5
                entry_time:
                  type: string
                  description: 'Entry timestamp (ISO 8601).'
                  example: '2025-03-15T10:30:00Z'
                entry_price:
                  type: number
                  description: 'Entry price.'
                  example: 65000.0
                exit_time:
                  type: string
                  description: 'Exit timestamp (ISO 8601).'
                  example: '2025-03-15T14:00:00Z'
                exit_price:
                  type: number
                  description: 'Exit price.'
                  example: 66500.0
                stop_loss:
                  type: number
                  description: 'Stop loss price.'
                  example: 64000.0
                take_profit:
                  type: number
                  description: 'Take profit price.'
                  example: 68000.0
                commission:
                  type: number
                  description: Commission/fees.
                  example: 1.5
                notes:
                  type: string
                  description: 'Trade notes.'
                  example: 'Strong momentum breakout'
                setup_type:
                  type: string
                  description: 'Setup type tag.'
                  example: breakout
              required:
                - instrument
                - side
                - quantity
                - entry_time
                - entry_price
  /api/v1/stats:
    get:
      summary: 'Get account stats'
      operationId: getAccountStats
      description: 'Get aggregated performance statistics for your account.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  total_trades: 150
                  win_rate: 62.5
                  net_pnl: 12450.75
                  profit_factor: 2.35
                  gross_profit: 25000.5
                  gross_loss: 10638.3
                  avg_win: 312.5
                  avg_loss: -189.25
                  best_trade: 1500.0
                  worst_trade: -650.0
                properties:
                  total_trades:
                    type: integer
                    example: 150
                  win_rate:
                    type: number
                    example: 62.5
                  net_pnl:
                    type: number
                    example: 12450.75
                  profit_factor:
                    type: number
                    example: 2.35
                  gross_profit:
                    type: number
                    example: 25000.5
                  gross_loss:
                    type: number
                    example: 10638.3
                  avg_win:
                    type: number
                    example: 312.5
                  avg_loss:
                    type: number
                    example: -189.25
                  best_trade:
                    type: number
                    example: 1500.0
                  worst_trade:
                    type: number
                    example: -650.0
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Insufficient scope: stats:read required'
                properties:
                  error:
                    type: string
                    example: 'Insufficient scope: stats:read required'
      tags:
        - 'Public API'
  /api/v1/leaderboard:
    get:
      summary: 'Get leaderboard'
      operationId: getLeaderboard
      description: 'Get the top 25 traders ranked by net P&L over the last 30 days (minimum 5 trades).'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    rank:
                      type: integer
                      example: 1
                    user:
                      type: string
                      example: TraderAce
                    trades:
                      type: integer
                      example: 45
                    pnl:
                      type: number
                      example: 8500.0
                example:
                  -
                    rank: 1
                    user: TraderAce
                    trades: 45
                    pnl: 8500.0
                  -
                    rank: 2
                    user: SwingKing
                    trades: 32
                    pnl: 6200.5
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'Insufficient scope: leaderboard:read required'
                properties:
                  error:
                    type: string
                    example: 'Insufficient scope: leaderboard:read required'
      tags:
        - 'Public API'
