openapi: '3.0.0'
info:
  title: Decentraland Governance API
  version: '1.0.0'
servers:
  - url: localhost:4000/api
tags:
  - name: Proposals
    description: The Proposals section of the API provides endpoints to interact with proposals and grants related to the. DAO. Proposals are the format community members use to propose changes to the Decentraland ecosystem.
  - name: Coauthor
    description: The Coauthor section of the API is focused on retrieving information about the co-authors associated with a particular proposal. Co-authors are individuals or organizations who are collaborating on a proposal, and may have contributed to its creation.
  - name: Projects
    description: The Projects section of the API provides endpoints to interact with projects.  
  - name: Project Updates
    description: The Project Updates section of the API is focused on retrieving information related to updates associated with a specific approved Grant. Updates are  used to inform the community or stakeholders about the progress of a Grant project, highlighting any important milestones, challenges, or changes.
  - name: DAO Committee
    description: The DAO Committee section of the API is focused on retrieving information related to the members of the DAO Committee, individuals resnponsible for executing transactions on chain, enacting proposals and with access to the DAO Treasury.
  - name: Votes
    description: The Votes section of the API is focused on retrieving information related to the voting process associated with a specific proposal. Votes are the way community members express their support or opposition to a proposal.
  - name: Events
    description: The Events section of the API is focused on retrieving information related to the user actions regarding proposals creation, proposal updates, and comments.
  - name: Subscriptions (User Watchlist)
    description: The Subscriptions section of the API is focused on retrieving information related to the subscriptions associated with a specific proposal. This feature is called Watchlist on the Governance dApp. Watchlists are usually used to have a closer look on updates or changes related to a proposal.
  - name: Badges
    description: Endpoints related to user badges
  - name: Users
    description: These endpoints handle user validation
  - name: Budgets
    description: The Budgets section of the API is focused on retrieving information related to the grants program budgets.
paths:
  /proposals:
    get:
      tags:
        - Proposals
      summary: Get proposals filtered by the given query params
      parameters:
        - name: user
          $ref: '#/components/parameters/user'
        - name: type
          $ref: '#/components/parameters/proposalType'
        - name: status
          $ref: '#/components/parameters/proposalStatus'
        - name: subscribed
          $ref: '#/components/parameters/isSubscribed'
        - name: coauthor
          $ref: '#/components/parameters/isCoauthor'
        - name: search
          $ref: '#/components/parameters/search'
        - name: timeFrame
          $ref: '#/components/parameters/timeFrame'
        - name: timeFrameKey
          $ref: '#/components/parameters/timeFrameKey'
        - name: order
          $ref: '#/components/parameters/order'
        - name: limit
          $ref: '#/components/parameters/limit'
        - name: offset
          $ref: '#/components/parameters/offset'
        - name: snapshotIds
          $ref: '#/components/parameters/snapshotIds'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/grants/{address}:
    get:
      tags:
        - Proposals
      summary: Get active and past enacted grants from the given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{proposal}:
    get:
      tags:
        - Proposals
      summary: Get the proposal from the given ID
      parameters:
        - name: proposalId
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '404':
          $ref: '#/components/responses/404'
  /proposals/{proposal}/comments:
    get:
      tags:
        - Proposals
      summary: Get the proposal comments from the given ID
      parameters:
        - name: proposalId
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/priority/{address}:
    get:
      tags:
        - Proposals
      summary: Get priority proposals
      description: Retrieve a list of Governance and project-related proposals. Optionally filter by a specific address.
      parameters:
        - name: address
          in: path
          required: false
          description: User Ethereum address to filter priority proposals
          allowEmptyValue: true
          schema:
            $ref: '#/components/schemas/ethAddress'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
  /proposals/linked-wearables/image:
    get:
      tags:
        - Proposals
      summary: Check if a given image is valid for linked wearables gallery
      parameters:
        - name: image URL
          $ref: '#/components/parameters/image_url'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /coauthors/{proposal}:
    get:
      tags:
        - Coauthor
      summary: Get the coauthors of the given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /coauthors/{proposal}/{status}:
    get:
      tags:
        - Coauthor
      summary: Get the coauthors of the given proposal ID filtered by the given request status
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
        - name: status
          $ref: '#/components/parameters/coauthorStatus'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /coauthors/proposals/{address}:
    get:
      tags:
        - Coauthor
      summary: Get the proposals in which the given address is a co-author
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /coauthors/proposals/{address}/{status}:
    get:
      tags:
        - Coauthor
      summary: Get the proposals in which the given address is a co-author by request status
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
        - name: status
          $ref: '#/components/parameters/coauthorStatus'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /projects:
    get:
      tags:
        - Projects
      summary: Get projects ordered from the most recent to the oldest
      responses:
        '200':
          $ref: '#/components/responses/200'
  /projects/pitches-total:
    get:
      tags:
        - Projects
      summary: Get the total number of open pitches for projects
      responses:
        '200':
          $ref: '#/components/responses/200'
  /projects/tenders-total:
    get:
      tags:
        - Projects
      summary: Get the total number of open tenders for projects
      responses:
        '200':
          $ref: '#/components/responses/200'

  /proposals/{proposal}/updates:
    get:
      tags:
        - Project Updates
      summary: Get the updates from the given proposal
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /updates/financials:
    get:
      tags:
        - Project Updates
      summary: Get all financial records
      parameters:
        - name: page_size
          in: query
          description: Page size
          schema:
            $ref: '#/components/schemas/limitOffset'
        - name: page_number
          in: query
          description: Page number
          schema:
            $ref: '#/components/schemas/limitOffset'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
  /updates/{update}:
    get:
      tags:
        - Project Updates
      summary: Get the update details from the given update ID
      parameters:
        - name: update
          $ref: '#/components/parameters/updateId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /updates/{update}/comments:
    get:
      tags:
        - Project Updates
      summary: Get the update comments from the given update ID
      parameters:
        - name: update
          $ref: '#/components/parameters/updateId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /committee:
    get:
      tags:
        - DAO Committee
      summary: Get the DAO Committee members addresses
      responses:
        '200':
          $ref: '#/components/responses/200'

  /votes:
    get:
      tags:
        - Votes
      summary: Get the cached votes from the given proposal ID
      parameters:
        - name: id
          in: query
          description: Proposal ID
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/200'
  /votes/participation:
    get:
      tags:
        - Votes
      summary: Get the high quality votes count for the last 30 days and the last week
      responses:
        '200':
          $ref: '#/components/responses/200'
  /votes/{address}:
    get:
      tags:
        - Votes
      summary: Get the votes from a given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /votes/top-voters:
    get:
      tags:
        - Votes
      summary: Get the top voters for the last 30 days
      parameters:
        - name: limit
          in: query
          required: false
          description: >-
            How many voters to return. Must be a whole number between 1 and 100;
            anything else is rejected with a 400. Defaults to 5 when omitted, but an
            empty value is not the same as omitting it and is rejected.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 5
      responses:
        '400':
          description: The limit was not a whole number between 1 and 100
        '200':
          $ref: '#/components/responses/200'
  /events:
    get:
      tags:
        - Events
      summary: Get the latest user actions on proposals creation, proposal updates, and comments
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{proposal}/votes:
    get:
      tags:
        - Votes
      summary: Get the votes from a given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /proposals/{proposal}/subscriptions:
    get:
      tags:
        - Subscriptions (User Watchlist)
      summary: Get the subscriptions from a given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /badges/{address}:
    get:
      tags:
        - Badges
      summary: Get badges for the given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'

  /user/{address}/is-validated:
    get:
      tags:
        - Users
      summary: Check if the given address is validated
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
        - name: account
          in: query
          required: true
          description: >-
            Which linked account to check. Repeat the parameter to ask about more
            than one, in which case every one of them must be linked for the
            answer to be true. Every value must be recognised: if any is not, the
            request is rejected rather than answered about the rest.
          schema:
            type: array
            minItems: 1
            items:
              type: string
              enum:
                - forum
                - discord
                - push
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          description: No account was given, or one of them was not a recognised account type

  /budget/current:
    get:
      tags:
        - Budgets
      summary: Get the budget for the current quarter
      responses:
        '200':
          $ref: '#/components/responses/200'
  /budget/contested/{proposal}:
    get:
      tags:
        - Budgets
      summary: Get the budget being contested for a given proposal and the contestants
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /budget/{category}:
    get:
      tags:
        - Budgets
      summary: Get the available quarter budget for a given category
      parameters:
        - name: category
          in: path
          description: Budget category
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/200'

############# COMPONENTS #############

components:
  ## Schemas
  schemas:
    coauthorStatus:
      type: string
      pattern: '(APPROVED|REJECTED|PENDING)'
    ethAddress:
      type: string
      pattern: '^0x[a-fA-F0-9]{40}$'
    proposalType:
      type: string
      pattern: '(poi|catalyst|ban_name|grant|linked_wearables|poll|draft|governance|hiring)'
    proposalStatus:
      type: string
      pattern: '(pending|active|finished|rejected|passed|enacted|deleted)'
    order:
      type: string
      pattern: '(ASC|DESC)'
    limitOffset:
      type: integer
      minimum: 0
    url:
      type: string
      pattern: '^(https:\/\/)([a-zA-Z0-9._-]+)(:[0-9]+)?(\/[a-zA-Z0-9._-]*)*(\?[a-zA-Z0-9._-]*)?(\#[a-zA-Z0-9._-=]*)?$'
  ## Parameters
  parameters:
    user:
      name: user
      in: query
      description: User eth address
      schema:
        $ref: '#/components/schemas/ethAddress'
    proposalType:
      name: type
      in: query
      description: Proposal type
      example: poi
      schema:
        $ref: '#/components/schemas/proposalType'
    proposalStatus:
      name: status
      in: query
      description: Proposal status
      example: enacted
      schema:
        $ref: '#/components/schemas/proposalStatus'
    isSubscribed:
      name: subscribed
      in: query
      description: is user subscribed to the proposals
      schema:
        type: boolean
    isCoauthor:
      name: coauthor
      in: query
      description: is user coauthoring the proposals
      schema:
        type: boolean
    search:
      name: search
      in: query
      description: text included within the proposals
      schema:
        type: string
    timeFrame:
      name: timeFrame
      in: query
      example: 2days
      schema:
        type: string
    timeFrameKey:
      name: timeFrameKey
      in: query
      example: finish_at
      schema:
        type: string
    order:
      name: order
      in: query
      description: ascending or descending
      example: ASC
      schema:
        $ref: '#/components/schemas/order'
    limit:
      name: limit
      in: query
      schema:
        $ref: '#/components/schemas/limitOffset'
    offset:
      name: offset
      in: query
      schema:
        $ref: '#/components/schemas/limitOffset'
    snapshotIds:
      name: snapshotIds
      in: query
      description: snapshot proposal IDs
      schema:
        type: string
    image_url:
      name: url
      in: query
      description: image URL
      schema:
        $ref: '#/components/schemas/url'
    address:
      name: address
      in: path
      description: User eth address
      required: true
      schema:
        $ref: '#/components/schemas/ethAddress'
    proposalId:
      name: proposal
      in: path
      description: Proposal ID
      required: true
      schema:
        type: string
    updateId:
      name: update
      in: path
      description: Update ID
      required: true
      schema:
        type: string
    coauthorStatus:
      name: status
      in: path
      description: Request status
      required: true
      schema:
        $ref: '#/components/schemas/coauthorStatus'
  ## Responses
  responses:
    '200':
      description: successful operation
    '400':
      description: bad request
    '404':
      description: not found