openapi: 3.2.0
info:
  title: RootRewards Quest Quests API
  version: '2025-08-16'
  summary: Retrieve quest and campaign information and allocate RootRewards points to FuturePass addresses.
  description: 'The RootRewards Quest API lets an approved external service read quest and campaign detail and allocate points from a quest budget to a FuturePass (Pass) address on The Root Network.


    PROVENANCE — this document was GENERATED by API Evangelist from Futureverse''s own published reference at https://docs.therootnetwork.com/rootrewards/api-reference (HTTP 200, fetched 2026-08-16) and the companion testing guide at https://docs.therootnetwork.com/rootrewards/testing-instructions (HTTP 200). Futureverse does NOT publish an OpenAPI description for this API. Every path, parameter, header, request body, response shape and status code below is transcribed from those two pages; nothing is invented.


    BASE URL IS NOT PUBLISHED. The reference states verbatim: "You will receive the Base URL, API key, and testing instructions when your Quest application is approved." The `server` block below therefore carries a REQUIRED variable rather than a guessed host — API Evangelist has not seen the real host and will not fabricate one.'
  contact:
    name: The Root Network documentation
    url: https://docs.therootnetwork.com/rootrewards/overview
  x-provenance:
    generated: '2026-08-16'
    method: generated
    generated-by: API Evangelist enrichment pipeline (local-v1)
    source: https://docs.therootnetwork.com/rootrewards/api-reference
    source-status: 200
    first-party: false
servers:
- url: '{baseUrl}'
  description: Base URL is issued privately to approved Quest applications and is not published. A separate staging base URL is issued for API-only testing.
  variables:
    baseUrl:
      default: https://REPLACE-WITH-BASE-URL-ISSUED-ON-APPROVAL
      description: The base URL Futureverse issues when a Quest application is approved.
security:
- questApiKey: []
tags:
- name: quests
  description: Quest detail, public quest discovery, and point allocation.
paths:
  /quests:
    get:
      operationId: listPublicQuests
      tags:
      - quests
      summary: Get public quests
      description: Retrieves public quests. No API key required.
      security: []
      parameters:
      - name: owner
        in: query
        required: false
        description: Pass address of the quest owner.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicQuest'
        '400':
          description: Quests are disabled or bad request
  /quests/{questId}:
    parameters:
    - name: questId
      in: path
      required: true
      description: Numeric ID of the quest.
      schema:
        type: integer
    get:
      operationId: getQuest
      tags:
      - quests
      summary: Get quest details
      description: Retrieves detailed information about a specific quest, including its payout history. Only the quest owner may call this.
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of payouts to return.
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of payouts to skip.
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestDetail'
        '400':
          description: Quests are disabled or bad request
        '401':
          description: Unauthorized (invalid API key or not quest owner)
        '404':
          description: Quest not found
    post:
      operationId: allocateQuestPoints
      tags:
      - quests
      summary: Allocate quest points
      description: Allocates points from a quest budget to a specified Pass address. Addresses are converted to checksum format server-side. Points are allocated within the current active earning period.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocatePointsRequest'
      responses:
        '200':
          description: Points successfully allocated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocatePointsResponse'
        '400':
          description: Bad request — quest inactive, insufficient points, account not found, quests disabled, or the quest's action type is deactivated.
        '401':
          description: Unauthorized (invalid API key or not quest owner)
        '404':
          description: Quest not found
components:
  schemas:
    QuestDetail:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        total_points:
          type: integer
        points_remaining:
          type: integer
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        is_active:
          type: boolean
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/Payout'
    Payout:
      type: object
      properties:
        id:
          type: string
        amount:
          type: integer
        created_at:
          type: string
          format: date-time
        account:
          type: object
          properties:
            pass:
              type: string
              description: FuturePass address.
    AllocatePointsResponse:
      type: object
      properties:
        payout:
          $ref: '#/components/schemas/Payout'
    AllocatePointsRequest:
      type: object
      required:
      - points
      - address
      properties:
        points:
          type: integer
          description: Number of points to allocate.
        address:
          type: string
          description: Pass address to receive points (converted to checksum format server-side).
    PublicQuest:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        total_points:
          type: integer
        expected_points_per_completion:
          type: integer
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        campaign:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            description:
              type: string
  securitySchemes:
    questApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Quest API key. Must start with the prefix `sk_` and be associated with the quest owner account. Issued on Quest application approval; never expose it in client-side code.