openapi: 3.1.0
info:
  title: RootRewards Quest 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.
  - name: campaigns
    description: Public campaign detail. Campaigns group quests but hold no balances.
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
  /campaigns/{id}:
    get:
      operationId: getCampaign
      tags: [campaigns]
      summary: Get campaign details
      description: Retrieves public campaign details and the quests it groups. No API key required.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric ID of the campaign.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          description: Campaign is disabled or bad request
        '404':
          description: Campaign not found
components:
  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.
  schemas:
    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'
    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
    CampaignQuest:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        is_public:
          type: boolean
        total_points:
          type: integer
        expected_points_per_completion:
          type: integer
        owner_id:
          type: string
        campaign_id:
          type: integer
    Campaign:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        name:
          type: string
        description:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        is_active:
          type: boolean
        external_app_id:
          type:
            - string
            - 'null'
        quests:
          type: array
          items:
            $ref: '#/components/schemas/CampaignQuest'
    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'