Gitcoin Bounties API

openapi: 3.1.0
info:
  title: Gitcoin Core Bounties API
  version: 0.1.0
  description: Read-only REST API providing access to Gitcoin bounties and grants data. Supports filtering by experience level, project length, bounty type, owner address, open status, and GitHub URL. Returns JSON-formatted data including funding amounts, contributor addresses, token types, and project metadata.
  termsOfService: https://gitcoin.co/terms
  contact:
    name: Gitcoin Support
    url: https://support.gitcoin.co/
  license:
    name: Gitcoin Terms
    url: https://gitcoin.co/terms
servers:
- url: https://gitcoin.co/api/v0.1
  description: Gitcoin API v0.1
tags:
- name: Bounties
  description: Operations related to Gitcoin bounties
paths:
  /bounties/:
    get:
      operationId: listBounties
      summary: List Bounties
      description: Returns a list of bounties with their current status. Supports filtering by experience level, project length, bounty type, owner address, open status, and GitHub URL.
      tags:
      - Bounties
      parameters:
      - name: experience_level
        in: query
        description: Filter by experience level (e.g., Beginner, Intermediate, Advanced)
        schema:
          type: string
      - name: project_length
        in: query
        description: Filter by project length (e.g., Hours, Days, Weeks, Months)
        schema:
          type: string
          enum:
          - Hours
          - Days
          - Weeks
          - Months
      - name: bounty_type
        in: query
        description: Filter by bounty type (e.g., Bug, Feature, Security)
        schema:
          type: string
          enum:
          - Bug
          - Feature
          - Security
          - Documentation
          - Design
      - name: bounty_owner_address
        in: query
        description: Filter by Ethereum address of the bounty owner
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: is_open
        in: query
        description: Filter by whether the bounty is open
        schema:
          type: boolean
      - name: github_url
        in: query
        description: Filter by GitHub URL. Can be a comma-separated list of GitHub URLs.
        schema:
          type: string
      - name: pk
        in: query
        description: Return a single bounty by its primary key ID
        schema:
          type: integer
      - name: order_by
        in: query
        description: Order results by a field key. Prefix with '-' for descending order (e.g., -expires_date)
        schema:
          type: string
      - name: limit
        in: query
        description: Limit number of results returned
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
      responses:
        '200':
          description: A list of bounties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bounty'
components:
  schemas:
    Bounty:
      type: object
      description: A Gitcoin bounty representing a funding opportunity for open source work
      properties:
        url:
          type: string
          format: uri
          description: URL for this specific bounty
          example: https://gitcoin.co/api/v0.1/bounties/9/
        created_on:
          type: string
          format: date-time
          description: Creation timestamp in ISO 8601 format
        modified_on:
          type: string
          format: date-time
          description: Last modified timestamp in ISO 8601 format
        title:
          type: string
          description: Title of the bounty
        web3_created:
          type: string
          format: date-time
          description: Creation timestamp for the on-chain transaction holding this bounty
        value_in_token:
          type: string
          description: Amount of tokens rewarded for the bounty
        token_name:
          type: string
          description: Type of token reward (e.g., ETH, GIT)
          example: ETH
        token_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Address where the tokens are located
        bounty_type:
          type: string
          description: Type of bounty (e.g., Bug, Feature, Security)
        project_length:
          type: string
          description: Relative length of project (e.g., Hours, Days, Weeks, Months)
        experience_level:
          type: string
          description: Recommended experience level
        github_url:
          type: string
          format: uri
          description: URL on GitHub where the bounty description can be found
        github_org_name:
          type: string
          description: GitHub organization name
        github_repo_name:
          type: string
          description: GitHub repository name
        github_issue_number:
          type: string
          description: GitHub issue number
        keywords:
          type: string
          description: Comma-delimited list of keywords
        current_bounty:
          type: boolean
          description: Whether this bounty is the most current revision
        expires_date:
          type: string
          format: date-time
          description: Date before which the bounty must be completed
        value_in_eth:
          type: number
          description: Value of the bounty in Ethereum (wei)
        value_in_usdt:
          type: number
          format: float
          description: Approximation of value in USD at bounty web3_created timestamp
        value_in_usdt_now:
          type: number
          format: float
          description: Approximation of current value in USD
        now:
          type: string
          format: date-time
          description: Current date_time on the server
        action_urls:
          type: object
          description: A list of URLs where a user can take action against the bounty
        paid:
          type: array
          items:
            type: string
          description: List of users who have been paid from the bounty
        is_open:
          type: boolean
          description: True if the bounty has not been completed
        status:
          type: string
          enum:
          - open
          - started
          - submitted
          - done
          - expired
          description: Current status of the bounty
        bounty_owner_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Ethereum address of the person who owns the bounty
        bounty_owner_email:
          type: string
          format: email
          description: Email of the bounty owner
        bounty_owner_github_username:
          type: string
          description: GitHub username of the bounty owner
        metadata:
          type: object
          description: Miscellaneous metadata about the bounty and the creator
        fulfiller_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Ethereum address of the person who fulfilled the bounty
        fulfiller_email:
          type: string
          format: email
          nullable: true
          description: Email of the person fulfilling the bounty
        fulfiller_github_username:
          type: string
          nullable: true
          description: GitHub username of the fulfiller
        fulfiller_metadata:
          type: object
          description: githubUsername and notificationEmail for the fulfiller
    EthereumAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: An Ethereum wallet address with leading 0x
      example: '0x636f3093258412b96c43bef3663f1b853253ec59'
externalDocs:
  description: Gitcoin API Documentation
  url: https://docs.gitcoin.co/mk_rest_api/