Futureverse Quests API

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.
  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:
    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
    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.
    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'
    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).
    AllocatePointsResponse:
      type: object
      properties:
        payout:
          $ref: '#/components/schemas/Payout'
  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.