openapi: 3.1.0
info:
  title: Tournament activity team:referendum API
  description: CrunchDAO Tournament Platform API Endpoints
  version: v2
servers:
- url: http://api.hub.crunchdao.com
  description: Generated server url
security: []
tags:
- name: team:referendum
paths:
  /v1/competitions/{competitionIdentifier}/teams/{teamIdentifier}/referendums:
    x-service-id: competition-service
    get:
      tags:
      - team:referendum
      summary: List referendums.
      operationId: listReferendums
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Referendum'
    post:
      tags:
      - team:referendum
      summary: Create a referendums.
      operationId: createReferendum
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferendumCreateForm'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referendum'
  /v1/competitions/{competitionIdentifier}/teams/{teamIdentifier}/referendums/{referendumNumber}/vote:
    x-service-id: competition-service
    post:
      tags:
      - team:referendum
      summary: Vote for a referendum.
      operationId: voteReferendum
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: referendumNumber
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferendumVoteCreateForm'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferendumVote'
  /v1/competitions/{competitionIdentifier}/teams/{teamIdentifier}/referendums/ask-to-join:
    x-service-id: competition-service
    post:
      tags:
      - team:referendum
      summary: Create a referendum asking to join the team.
      operationId: askToJoinTeam
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referendum'
  /v2/competitions/{competitionIdentifier}/teams/{teamIdentifier}/referendums:
    x-service-id: competition-service
    get:
      tags:
      - team:referendum
      summary: List referendums.
      operationId: listReferendumsV2
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter on type.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Filter on type.
          enum:
          - INVITE
          - KICK
          - PROMOTE
          - ACCEPT_USER
          - REQUEST_MERGE
          - ACCEPT_MERGE
          - DISBAND
      - name: consensus
        in: query
        description: Filter on consensus.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Filter on consensus.
          enum:
          - UNANIMITY
          - MAJORITY
      - name: targetUser
        in: query
        description: Filter on target user identifier.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Filter on target user identifier.
      - name: targetTeam
        in: query
        description: Filter on target team identifier.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Filter on target team identifier.
      - name: verdict
        in: query
        description: Filter on verdict.
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/ReferendumVerdict'
          description: Filter on verdict.
      - name: sort
        in: query
        description: Sort referendums.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Sort referendums.
          enum:
          - RECENT
          - OLDEST
      - name: includeVotes
        in: query
        description: Include the votes in the response.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          description: Include the votes in the response.
      - name: page
        in: query
        description: Zero-based page index (0..N)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The size of the page to be returned
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 20
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageReferendum'
  /v1/competitions/{competitionIdentifier}/teams/{teamIdentifier}/referendums/{referendumNumber}:
    x-service-id: competition-service
    get:
      tags:
      - team:referendum
      summary: Show a referendum.
      operationId: getReferendum
      parameters:
      - name: competitionIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: teamIdentifier
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: referendumNumber
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referendum'
components:
  schemas:
    ReferendumType:
      type: string
      enum:
      - INVITE
      - KICK
      - PROMOTE
      - ACCEPT_USER
      - REQUEST_MERGE
      - ACCEPT_MERGE
      - DISBAND
    Team:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        leader:
          $ref: '#/components/schemas/User'
          description: Team leader, or `null` if leaders are disabled.
        size:
          type: integer
          format: int32
        deleted:
          type: boolean
        lookingForTeammates:
          type: boolean
        members:
          type: array
          items:
            $ref: '#/components/schemas/TeamMember'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Referendum:
      type: object
      properties:
        id:
          type: integer
          format: int64
        number:
          type: integer
          format: int64
          description: Team-based referendum number.
        type:
          $ref: '#/components/schemas/ReferendumType'
          description: Referendum type.
        consensus:
          $ref: '#/components/schemas/ReferendumConsensus'
          description: Voting consensus.
        target:
          $ref: '#/components/schemas/ReferendumTarget'
          description: Target entity type. `SELF` is the current team.
        targetUser:
          $ref: '#/components/schemas/User'
          description: Target user. Only available when `target` = `USER`.
        targetTeam:
          $ref: '#/components/schemas/Team'
          description: Target team. Only available when `target` = `TEAM`.
        votes:
          type: array
          description: List of users who have already voted.
          items:
            $ref: '#/components/schemas/ReferendumVote'
        teamSize:
          type: integer
          format: int64
          description: Size of the team at the time of the referendum. Always updated during the referendum.
        verdict:
          $ref: '#/components/schemas/ReferendumVerdict'
          description: Result of the referendum.
        status:
          type: string
          description: English status of the referendum. Includes errors.
        createdAt:
          type: string
          format: date-time
          description: Creation date.
        targetUserId:
          type: integer
          format: int64
          deprecated: true
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        login:
          type: string
    ReferendumConsensus:
      type: string
      enum:
      - UNANIMITY
      - MAJORITY
    ReferendumVoteChoice:
      type: string
      enum:
      - AGAINST
      - FOR
    ReferendumVote:
      type: object
      properties:
        id:
          type: integer
          format: int64
        user:
          $ref: '#/components/schemas/User'
        choice:
          $ref: '#/components/schemas/ReferendumVoteChoice'
        createdAt:
          type: string
          format: date-time
        signature:
          type: string
          deprecated: true
        address:
          type: string
          deprecated: true
        userId:
          type: integer
          format: int64
          deprecated: true
        ipfsHash:
          type: string
          deprecated: true
        verifyUrl:
          type: string
          deprecated: true
    ReferendumVerdict:
      type: string
      enum:
      - PENDING
      - APPROVED
      - REJECTED
      - EXPIRED
    ReferendumTarget:
      type: string
      enum:
      - USER
      - TEAM
      - SELF
    ReferendumCreateForm:
      type: object
      properties:
        type:
          type: string
          enum:
          - INVITE
          - KICK
          - PROMOTE
          - ACCEPT_USER
          - REQUEST_MERGE
          - ACCEPT_MERGE
          - DISBAND
        targetUserId:
          type: integer
          format: int64
        targetTeamId:
          type: integer
          format: int64
      required:
      - targetTeamId
      - targetUserId
      - type
    PageReferendum:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int64
        pageSize:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
        content:
          type: array
          items:
            $ref: '#/components/schemas/Referendum'
    TeamMember:
      type: object
      properties:
        id:
          type: integer
          format: int64
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time
        userId:
          type: integer
          format: int64
          deprecated: true
    ReferendumVoteCreateForm:
      type: object
      properties:
        choice:
          type: string
          enum:
          - AGAINST
          - FOR
        signature:
          type: string
          deprecated: true
      required:
      - choice
  securitySchemes:
    apiKey:
      type: apiKey
      name: apiKey
      in: query
      scheme: token
    accessToken:
      type: http
      in: header
      scheme: Bearer
externalDocs:
  description: docs.crunchdao.com
  url: https://docs.crunchdao.com