GOOD Grants Leaderboard API

openapi: 3.2.0
info:
  title: Good Grants Leaderboard API
  version: '2.3'
  description: 'The Good Grants API enables you to programmatically manage grant-making programs, funding cycles, and application workflows.


    Use this API to:

    - Create and manage grant applications and submissions

    - Automate review workflows and scoring assignments

    - Track grant payments and fund allocations

    - Generate compliance reports and analytics

    - Integrate with external systems via webhooks


    All API requests require authentication using an API key provided in the `X-Api-Key` header.'
  license:
    name: Creative Force Client Subscription Terms
    url: https://creativeforce.team/agreement/
servers:
- url: https://api.us.cr4ce.com
  description: US regional endpoint
- url: https://api.eu.cr4ce.com
  description: EU regional endpoint
- url: https://api.au.cr4ce.com
  description: Australasia regional endpoint
- url: https://api.ca.cr4ce.com
  description: Canada regional endpoint
- url: https://api.hk.cr4ce.com
  description: Hong Kong regional endpoint
security:
- ApiKeyAuth: []
tags:
- name: Leaderboard
  description: 'Use these operations to retrieve ranking results and scores for applications.

    The leaderboard shows how applications rank based on score sets, with support for filtering by category, chapter, and tags.


    Results can be filtered to show specific subsets of the funding program.

    Note: The leaderboard is read-only and reflects calculated results from the review process.'
paths:
  /leaderboard:
    get:
      summary: List leaderboard results
      operationId: GetLeaderboardCollectionV23
      tags:
      - Leaderboard
      parameters:
      - $ref: '#/components/parameters/leaderboardScoreSetFilter'
      - $ref: '#/components/parameters/categoryFilter'
      - $ref: '#/components/parameters/chapterFilter'
      - $ref: '#/components/parameters/entryFilter'
      - $ref: '#/components/parameters/tagFilter'
      - $ref: '#/components/parameters/archivedFilter'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/leaderboardOrder'
      - $ref: '#/components/parameters/sortDirection'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/X-Api-Language'
      responses:
        '200':
          description: Paginated list of leaderboard results.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardList'
            application/xml:
              schema:
                $ref: '#/components/schemas/LeaderboardList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      description: List leaderboard results. A missing or unresolvable `score_set` parameter returns `404 Not Found`.
components:
  schemas:
    Forbidden:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 403
            maximum: 403
    NotFound:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 404
            maximum: 404
    BadRequest:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 400
            maximum: 400
    TooManyRequests:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 429
            maximum: 429
    Leaderboard:
      title: Leaderboard
      description: Single row in a score-set leaderboard, representing one application and its scores.
      type: object
      properties:
        slug:
          type: string
          description: Short URL-safe identifier for the application.
        title:
          type: string
          description: Title of the application as submitted by the applicant.
        tags:
          type: string
          description: Comma-separated tags applied to the application, empty string if none.
        category:
          type:
          - object
          - 'null'
          description: Category the application was submitted to, `null` if not assigned.
          properties:
            slug:
              type: string
              description: Short URL-safe identifier for the category.
            link:
              type: string
              format: uri
              description: Canonical URL for the category resource.
            name:
              type: object
              description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
              additionalProperties:
                type: string
        chapter:
          type:
          - object
          - 'null'
          description: Chapter the application belongs to, `null` if not assigned.
          properties:
            slug:
              type: string
              description: Short URL-safe identifier for the chapter.
            link:
              type: string
              format: uri
              description: Canonical URL for the chapter resource.
            name:
              type: object
              description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
              additionalProperties:
                type: string
        division:
          type:
          - string
          - 'null'
          description: Division the application is assigned to, `null` if not assigned.
        submitted:
          type: string
          format: date-time
          description: Date and time when the application was submitted, in ISO 8601 format.
        auto_score:
          type:
          - number
          - 'null'
          description: Automated score calculated from the application's auto-scored fields, `null` if none.
        status:
          type: string
          description: Submission status of the application.
        grant_status:
          type:
          - string
          - 'null'
          description: Grant status of the application, `null` unless grants are enabled.
        link:
          type: string
          format: uri
          description: Canonical URL for the application resource.
        scores:
          description: Scores for the application, shaped by the score set mode (`voting`, `qualifying`, `scoring`, or `top_pick`).
          anyOf:
          - title: Voting
            type: object
            description: Scores returned for a `voting` score set.
            properties:
              total_votes:
                type: integer
                description: Total number of votes the application received.
          - title: Qualifying
            type: object
            description: Scores returned for a `qualifying` score set.
            properties:
              final_decision:
                type:
                - string
                - 'null'
                enum:
                - pass
                - fail
                - unsure
                description: Qualifying decision recorded for the application, `null` if none recorded.
          - title: Scoring
            type: object
            description: Scores returned for a `scoring` score set.
            properties:
              total_score:
                type: object
                description: Aggregated score across all criteria.
                properties:
                  value:
                    type: number
                    description: Total score awarded across all criteria.
                  max_score:
                    oneOf:
                    - type: integer
                    - type: string
                    description: Maximum achievable total score, empty string if none configured.
                  final_score:
                    type: string
                    description: Formatted total score, such as `8/10`, or `-` if no maximum is configured.
              criteria:
                type: array
                description: Per-criterion scores making up the total.
                items:
                  type: object
                  properties:
                    name:
                      type: object
                      description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
                      additionalProperties:
                        type: string
                    value:
                      type: number
                      description: Score awarded for the criterion.
                    max_score:
                      type: integer
                      description: Maximum achievable score for the criterion.
                    final_score:
                      type: string
                      description: Formatted criterion score, such as `4/5`.
                    weight:
                      type: number
                      description: Relative weight of the criterion in the total.
          - title: Top Pick
            type: object
            description: Scores returned for a `top_pick` score set, keyed by preference position (for example, `preference_1`), with the number of reviewers at that position.
            additionalProperties:
              type: integer
      example:
        slug: AbCdEfGh
        title: Sustainable Cities Initiative
        tags: ''
        category:
          slug: IjKlMnOp
          link: https://api.au.cr4ce.com/category/IjKlMnOp
          name:
            en_GB: Documentary
        chapter:
          slug: QrStUvWx
          link: https://api.au.cr4ce.com/chapter/QrStUvWx
          name:
            en_GB: United Kingdom
        division: null
        submitted: '2026-01-15T09:00:00Z'
        auto_score: 0
        status: submitted
        grant_status: null
        link: https://api.au.cr4ce.com/application/AbCdEfGh
        scores:
          total_score:
            value: 8
            max_score: 10
            final_score: 8/10
          criteria:
          - name:
              en_GB: Originality
            value: 4
            max_score: 5
            final_score: 4/5
            weight: 1
    LeaderboardList:
      title: Leaderboard list
      description: Paginated leaderboard for a single score set, with ranked applications in `data` alongside the score set and season.
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            description: Leaderboard rows for the current page.
            items:
              $ref: '#/components/schemas/Leaderboard'
          score_set:
            type: object
            description: Score set the leaderboard is calculated for.
            properties:
              slug:
                type: string
                description: Short URL-safe identifier for the score set.
              name:
                type: object
                description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
                additionalProperties:
                  type: string
              mode:
                type: string
                enum:
                - voting
                - qualifying
                - scoring
                - top_pick
                description: Scoring mode of the score set, determines the shape of each row's `scores` object.
              form:
                type: object
                description: Form the score set scores applications from.
                properties:
                  slug:
                    type: string
                    description: Short URL-safe identifier for the form.
                  link:
                    type: string
                    format: uri
                    description: Canonical URL for the form resource.
                  name:
                    type: object
                    description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
                    additionalProperties:
                      type: string
          season:
            type: object
            description: Season the leaderboard belongs to.
            properties:
              slug:
                type: string
                description: Short URL-safe identifier for the season.
              link:
                type: string
                format: uri
                description: Canonical URL for the season resource.
              name:
                type: object
                description: Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.
                additionalProperties:
                  type: string
      example:
        current_page: 1
        data:
        - slug: AbCdEfGh
          title: Sustainable Cities Initiative
          tags: ''
          category:
            slug: IjKlMnOp
            link: https://api.au.cr4ce.com/category/IjKlMnOp
            name:
              en_GB: Documentary
          chapter:
            slug: QrStUvWx
            link: https://api.au.cr4ce.com/chapter/QrStUvWx
            name:
              en_GB: United Kingdom
          division: null
          submitted: '2026-01-15T09:00:00Z'
          auto_score: 0
          status: submitted
          grant_status: null
          link: https://api.au.cr4ce.com/application/AbCdEfGh
          scores:
            total_votes: 12
        - slug: MnOpQrSt
          title: Ocean Cleanup Documentary
          tags: ''
          category:
            slug: IjKlMnOp
            link: https://api.au.cr4ce.com/category/IjKlMnOp
            name:
              en_GB: Documentary
          chapter:
            slug: QrStUvWx
            link: https://api.au.cr4ce.com/chapter/QrStUvWx
            name:
              en_GB: United Kingdom
          division: null
          submitted: '2026-01-12T14:20:00Z'
          auto_score: 0
          status: submitted
          grant_status: null
          link: https://api.au.cr4ce.com/application/MnOpQrSt
          scores:
            total_votes: 9
        first_page_url: https://api.au.cr4ce.com/leaderboard?score_set=UvWxYzAb&page=1
        from: 1
        last_page: 1
        last_page_url: https://api.au.cr4ce.com/leaderboard?score_set=UvWxYzAb&page=1
        next_page_url: ''
        path: https://api.au.cr4ce.com/leaderboard
        per_page: 10
        prev_page_url: ''
        to: 2
        total: 2
        score_set:
          slug: UvWxYzAb
          name:
            en_GB: Voting
          mode: voting
          form:
            slug: GhIjKlMn
            link: https://api.au.cr4ce.com/form/GhIjKlMn
            name:
              en_GB: Application form
        season:
          slug: CdEfGhIj
          link: https://api.au.cr4ce.com/season/CdEfGhIj
          name:
            en_GB: '2025'
    Pagination:
      type: object
      title: Pagination
      properties:
        current_page:
          type: integer
          description: Number of the page returned by this response, starting at `1`.
        first_page_url:
          type: string
          description: URL of the first page in the result set, relative when the requested page is beyond the last page.
        from:
          type:
          - integer
          - 'null'
          description: Position of the first record on this page within the full result set, starting at `1`, or `null` when the requested page is beyond the last page.
        last_page:
          type: integer
          description: Total number of pages.
        last_page_url:
          type: string
          description: URL of the last page in the result set, relative when the requested page is beyond the last page.
        next_page_url:
          type: string
          description: URL of the next page in the result set, empty when the current page is the last page.
        path:
          type: string
          description: Canonical URL of the endpoint, without query parameters.
        per_page:
          type: integer
          default: 10
          description: Maximum number of records returned per page.
        prev_page_url:
          type: string
          description: URL of the previous page in the result set, empty when the current page is the first page.
        to:
          type:
          - integer
          - 'null'
          description: Position of the last record on this page within the full result set, or `null` when the requested page is beyond the last page.
        total:
          type: integer
          description: Total number of records across all pages.
    BaseProblem:
      description: Standard error envelope for all API error responses.
      type: object
      properties:
        message:
          type: string
        status_code:
          type: integer
          minimum: 400
          maximum: 599
    Unauthorized:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 401
            maximum: 401
  parameters:
    sortDirection:
      name: dir
      in: query
      required: false
      description: Sort in ascending or descending order. Invalid values are rejected with `400 Bad Request`.
      schema:
        type: string
        enum:
        - asc
        - desc
    Accept:
      name: Accept
      in: header
      required: true
      description: Defines the response type.
      schema:
        type: string
        enum:
        - application/vnd.Creative Force.v2.3+json
        - application/vnd.Creative Force.v2.3+xml
    tagFilter:
      name: tag
      in: query
      required: false
      description: Filter by tag.
      schema:
        type: string
    categoryFilter:
      name: category
      in: query
      required: false
      description: Filter by category slug.
      schema:
        type: string
    leaderboardOrder:
      name: order
      in: query
      required: false
      description: 'Sort by a supported leaderboard field.

        * `category` - Sort by category slug.

        * `chapter` - Sort by chapter slug.'
      schema:
        type: string
        enum:
        - category
        - chapter
        - division
        - link
        - slug
        - status
        - submitted
        - auto_score
        - title
        - tags
    X-Api-Language:
      name: x-api-language
      in: header
      required: false
      description: 'Defines the languages included in the response. If non are provided, the account default language is returned.


        Value `all` overrides any other values present.


        You can request multiple languages using a comma-separated string of languages.


        The selected language must be supported by your account or a `400` error is returned.'
      style: simple
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - all
          - ar_AR
          - bg_BG
          - bn_IN
          - ca_ES
          - cs_CZ
          - cy_GB
          - da_DK
          - de_DE
          - en_GB
          - en_US
          - el_GR
          - es_NN
          - es_LA
          - et_EE
          - fa_NN
          - fi_FI
          - fr_FR
          - fr_CA
          - he_IL
          - hi_IN
          - hr_HR
          - hu_HU
          - hy_AM
          - it_IT
          - ja_JP
          - ko_KR
          - lt_LT
          - ms_MY
          - nl_NL
          - nb_NO
          - pl_PL
          - pt_BR
          - ro_RO
          - ru_RU
          - sk_SK
          - sl_SI
          - sq_AL
          - sr_RS
          - sv_SE
          - sw_NN
          - th_TH
          - tr_TR
          - uk_UA
          - vi_VN
          - zh_CN
          - zh_HK
      example:
      - en_GB
      - fr_FR
    perPage:
      name: per_page
      in: query
      required: false
      description: 'Limit the number of items returned to between 1 and 100.


        If you provide a value outside this range, you will receive a `400` response.

        '
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    leaderboardScoreSetFilter:
      name: score_set
      in: query
      required: true
      description: Filter by score set slug.
      schema:
        type: string
    archivedFilter:
      name: archived
      in: query
      required: false
      description: 'Filter by archive mode.

        * `only` - Show only archived resources.

        * `all` - Include archived resources.

        * `none` - Exclude archived resources.'
      schema:
        type: string
        enum:
        - only
        - all
        - none
    chapterFilter:
      name: chapter
      in: query
      required: false
      description: Filter by chapter slug.
      schema:
        type: string
    entryFilter:
      name: application
      in: query
      required: false
      description: Filter by application slug.
      schema:
        type: string
    page:
      name: page
      in: query
      required: false
      description: Specify the page number to return.
      schema:
        type: integer
        minimum: 1
        default: 1
  responses:
    NotFound:
      description: Resource identified by the path slug does not exist. Returned when the slug is well-formed but no record matches it.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
        application/xml:
          schema:
            $ref: '#/components/schemas/NotFound'
    ServiceUnavailable:
      description: Service is temporarily unavailable due to regional maintenance.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                description: Human-readable maintenance status.
            example:
              status: Maintenance in progress
        application/xml:
          schema:
            type: object
            properties:
              status:
                type: string
                description: Human-readable maintenance status.
            example:
              status: Maintenance in progress
    Unauthorized:
      description: Missing `x-api-key` header.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
        application/xml:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    BadRequest:
      description: 'Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, invalid JSON in the request body, or an invalid slug format in a path parameter.'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
        application/xml:
          schema:
            $ref: '#/components/schemas/BadRequest'
    TooManyRequests:
      description: Rate limit of 60 requests per minute exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
        application/xml:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
    Forbidden:
      description: 'Authenticated request denied. Common causes: invalid or unknown

        API key, suspended account, `api` feature not enabled for

        the account, or a read-only API key used for a request that

        is not a `GET`.'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Forbidden'
        application/xml:
          schema:
            $ref: '#/components/schemas/Forbidden'
  headers:
    X-RateLimit-Remaining:
      description: Number of requests remaining in the current rate limit window.
      schema:
        type: integer
        example: 58
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per minute.
      schema:
        type: integer
        example: 60
    X-RateLimit-Reset:
      description: Unix timestamp when the rate limit window resets.
      schema:
        type: integer
        example: 1783470988
    Retry-After:
      description: Number of seconds the client should wait before retrying.
      schema:
        type: integer
      example: 60
    ETag:
      description: Entity tag for the selected representation.
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key used to authenticate and authorise every request.

        Include it in the `x-api-key` header.'