openapi: 3.0.3
info:
  title: Secure Code Warrior Portal Assessments Tournaments API
  description: The Secure Code Warrior Portal API provides programmatic access to the developer security training platform. Manage users, teams, training progress, assessments, tournaments, courses, programs, metrics, and audit logs. Supports multiple API key types for granular access control across US and EU regions.
  version: 2.0.0
  contact:
    url: https://portal-api.securecodewarrior.com/api/docs/v2/
servers:
- url: https://portal-api.securecodewarrior.com/api/v2
  description: Secure Code Warrior Portal API - US
- url: https://portal-api.eu.securecodewarrior.com/api/v2
  description: Secure Code Warrior Portal API - EU
security:
- apiKey: []
tags:
- name: Tournaments
paths:
  /tournaments:
    get:
      operationId: listTournaments
      summary: List Tournaments
      description: Returns a list of tournaments in the company.
      tags:
      - Tournaments
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: name
        in: query
        schema:
          type: string
      - name: startdate
        in: query
        schema:
          type: string
          format: date
      - name: enddate
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of tournaments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TournamentsResponse'
  /tournaments/{tournament_id}/leaderboard:
    get:
      operationId: getTournamentLeaderboard
      summary: Get Tournament Leaderboard
      description: Returns the leaderboard for a single tournament.
      tags:
      - Tournaments
      parameters:
      - name: tournament_id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Tournament leaderboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardResponse'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        role:
          type: string
        teams:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastActiveAt:
          type: string
          format: date-time
    LeaderboardResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            type: object
            properties:
              rank:
                type: integer
              user:
                $ref: '#/components/schemas/User'
              points:
                type: integer
              completions:
                type: integer
              change:
                type: integer
                description: Rank change over report period
        total:
          type: integer
        page:
          type: integer
    TournamentsResponse:
      type: object
      properties:
        tournaments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              status:
                type: string
              startDate:
                type: string
                format: date-time
              endDate:
                type: string
                format: date-time
        total:
          type: integer
        page:
          type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Report API key, Admin API key, or Team API Key