RootRewards Quest API - The Root Network

This document provides integration guidelines for the RootRewards API endpoints that allow external services to retrieve quest information and allocate points to user addresses.

You will receive the Base URL, API key, and testing instructions when your Quest application is approved.

Quests and Campaigns explained

A Quest is a single earnable action with its own points budget, active window, and rules. Points are always allocated to a user for completing a quest using POST /quests/{questId}.
A Campaign is a collection or promotion that groups related quests for discovery and presentation (e.g., via GET /campaigns/{id} or GET /quests). Campaigns don’t hold balances and don’t allocate points—allocations always happen at the quest level.

Authentication

Some endpoints require an API key passed via the x-api-key header. The API key must:

Start with the prefix sk_
Be associated with the quest owner account

Endpoints

Get Quest Details

GET /quests/{questId}

Retrieves detailed information about a specific quest.

Parameters

Parameter	Type	Location	Required	Description
`questId`	integer	path	Yes	Numeric ID of the quest
`limit`	integer	query	No	Number of payouts to return (default: 20)
`offset`	integer	query	No	Number of payouts to skip (default: 0)

Headers

Header	Required	Description
`x-api-key`	Yes	Your API key starting with `sk_`

Response

{
  "id": 123,
  "name": "Quest Name",
  "description": "Quest description",
  "total_points": 10000,
  "points_remaining": 7500,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "is_active": true,
  "payouts": [
    {
      "id": "payout_123",
      "amount": 100,
      "created_at": "2024-01-15T10:30:00Z",
      "account": { "pass": "0xfff..." }
    }
  ]
}

Status Codes

Code	Description
`200`	Success
`400`	Quests are disabled or bad request
`401`	Unauthorized (invalid API key or not quest owner)
`404`	Quest not found

Get Public Quests

GET /quests

Retrieves public quests.

Parameters

Parameter	Type	Location	Required	Description
`owner`	string	query	No	Pass address of the quest owner

Headers

Header	Required	Description
`x-api-key`	No	API key not required for this endpoint

Response

{
  "id": 123,
  "name": "Quest Name",
  "description": "Quest description",
  "total_points": 10000,
  "expected_points_per_completion": 50,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "campaign": {
    "id": "payout_123",
    "name": "Campaign Name",
    "description": "Campaign Description"
  }
}

Status Codes

Code	Description
`200`	Success
`400`	Quests are disabled or bad request

Get Campaign Details

GET /campaigns/{id}

Retrieves public campaign details.

Parameters

Parameter	Type	Location	Required	Description
`id`	integer	path	Yes	Numeric ID of the campaign

Headers

Header	Required	Description
`x-api-key`	No	API key not required for this endpoint

Response

{
  "id": 123,
  "created_at": "2024-01-11T01:08:07.352Z",
  "updated_at": "2024-01-11T01:08:07.352Z",
  "name": "Campaign Name",
  "description": "Campaign description",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "is_active": true,
  "external_app_id": null,
  "quests": [
    {
      "id": 1,
      "name": "Quest Name",
      "created_at": "2024-02-01T01:20:51.240Z",
      "updated_at": "2024-02-02T01:20:51.240Z",
      "description": "Quest Description",
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-01T00:00:00Z",
      "is_public": true,
      "total_points": 10000,
      "expected_points_per_completion": 20,
      "owner_id": "user_xxxxxxxxxxxxxxxx",
      "campaign_id": 1
    }
  ]
}

Status Codes

Code	Description
`200`	Success
`400`	Campaign is disabled or bad request
`404`	Campaign not found

Allocate Quest Points

POST /quests/{questId}

Allocates points from a quest to a specified Pass address.

Parameters

Parameter	Type	Location	Required	Description
`questId`	integer	path	Yes	Numeric ID of the quest

Headers

Header	Required	Description
`x-api-key`	Yes	Your API key starting with `sk_`

Request Body

{
  "points": 100,
  "address": "0xFfFFFFff00000000000000000000000000000001"
}

Field	Type	Required	Description
`points`	integer	Yes	Number of points to allocate
`address`	string	Yes	Pass address to receive points (will be converted to checksum format)

Response

{
  "payout": {
    "id": "tx_abc123",
    "amount": 100,
    "created_at": "2024-01-15T10:30:00Z",
    "account": {
      "pass": "user_pass_id"
    }
  }
}

Status Codes

Code	Description
`200`	Points successfully allocated
`400`	Bad request (quest inactive, insufficient points, account not found, etc.)
`401`	Unauthorized (invalid API key or not quest owner)
`404`	Quest not found

Error Handling

Common Error Scenarios

Quests Disabled: When the quest feature flag is disabled
Quest Not Active: When current time is outside quest’s start/end period
Insufficient Points: When requested points exceed quest’s remaining points
Account Not Found: When the target address doesn’t have an associated account
Action Type Inactive: When the quest’s action type is deactivated

Integration Notes

Address Format: Addresses are automatically converted to checksum format
Quest Ownership: Only quest owners can retrieve detailed information or allocate points
Real-time Validation: All requests validate quest status, remaining points, and account existence
Earning Periods: Points are allocated within the current active earning period

Security Considerations

Store API keys securely and never expose them in client-side code
Use HTTPS for all API communications
Validate addresses on your end before sending requests
Monitor API usage for unusual patterns

​Authentication

​Endpoints

​Get Quest Details

​Parameters

​Headers

​Response

​Status Codes

​Get Public Quests

​Parameters

​Headers

​Response

​Status Codes

​Get Campaign Details

​Parameters

​Headers

​Response

​Status Codes

​Allocate Quest Points

​Parameters

​Headers

​Request Body

​Response

​Status Codes

​Error Handling

​Common Error Scenarios

​Integration Notes

​Security Considerations

Authentication

Endpoints

Get Quest Details

Parameters

Headers

Response

Status Codes

Get Public Quests

Parameters

Headers

Response

Status Codes

Get Campaign Details

Parameters

Headers

Response

Status Codes

Allocate Quest Points

Parameters

Headers

Request Body

Response

Status Codes

Error Handling

Common Error Scenarios

Integration Notes

Security Considerations