RootRewards Quest API

Complete API documentation for RootRewards integration

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

Note

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

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

Integration Notes

1. Address Format: Addresses are automatically converted to checksum format
2. Quest Ownership: Only quest owners can retrieve detailed information or allocate points
3. Real-time Validation: All requests validate quest status, remaining points, and account existence
4. 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

Source: https://docs.therootnetwork.com/rootrewards/api-reference · captured 2026-05-16 · part of TRN Docs source map