> ## Documentation Index > Fetch the complete documentation index at: https://docs.therootnetwork.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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 ```http 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 ```json { "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 ```http 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 ```json { "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 ```http 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 ```json { "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 ```http 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 ```json { "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 ```json { "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