Introduction


# Introduction

Welcome to Questful, your comprehensive questing as a service platform. Whether you're building a game, a loyalty program, or any application that needs a quest and reward system, Questful provides the tools and infrastructure you need to create engaging experiences for your users.

## About Questful

Questful is a powerful platform that enables you to create and manage quests and rewards for your applications. Our platform is designed to be simple yet powerful, allowing you to focus on building great experiences while we handle the technical complexity of quest and reward management.

## Core Features

Questful provides a comprehensive set of features to help you build engaging quest systems:

- **Quest Management**: Create and manage different types of quests including standard quests and daily quests
- **Reward System**: Design and implement flexible reward systems that motivate your users
- **User Progress Tracking**: Monitor user progress and completion status for all quests
- **API Integration**: Simple REST API endpoints for seamless integration with your application
- **Dashboard**: Intuitive dashboard for managing quests, rewards, and user progress
- **Scalability**: Built to scale with your community, from small projects to enterprise solutions

## Getting Started

To begin using Questful, follow these steps:

1. **Sign Up**: Create your account at [questful.dev](https://questful.dev)
2. **Create Rewards**: Set up the rewards that users can earn by completing quests
3. **Create Quests**: Define quests with specific requirements and associated rewards
4. **Integrate API**: Use our API endpoints to track quest completion and reward redemption

## API Endpoints

Questful provides several key API endpoints for managing quests and rewards:

- `POST /api/v1/completeQuest`: Mark quests as completed and award rewards
- `POST /api/v1/redeemReward`: Allow users to redeem their earned rewards
- `GET /api/v1/getQuests`: Retrieve quest information
- `GET /api/v1/getUsers`: Access user data and progress
- `GET /api/v1/getRedeemedRewards`: Retreive rewards redemption transactions
- `GET /api/v1/getCompletedQuests`: Retreive quests completion transactions

## Subscription Plans

Questful offers flexible subscription plans to suit your needs:

- **Grow Plan**: Perfect for small to medium applications
  - 100 API calls per minute
  - Up to 10,000 transactions
  - Support for up to 5,000 users
- **Pro Plan**: Ideal for growing applications
  - 500 API calls per minute
  - Up to 100,000 transactions
  - Support for up to 100,000 users
- **Enterprise Plan**: For large-scale applications
  - Unlimited API calls
  - Unlimited transactions
  - Unlimited users

## Support and Resources

At Questful, we're committed to your success. We provide:

- Comprehensive documentation
- Developer guides and examples
- Technical support
- Regular updates and improvements

## Why Choose Questful?

Questful stands out for several reasons:

- **Simple API**: Clean, intuitive API that lets you integrate questing into your platform in minutes
- **Community Focus**: Focus on building and engaging your community while we handle the technical complexity
- **Scalable**: Built to scale with your community, from small projects to enterprise solutions
- **Comprehensive Docs**: Detailed documentation and examples to get you started quickly
- **Flexible Integration**: Works with any tech stack. Integrate questing into your existing platform seamlessly
- **Developer First**: Built by developers for developers, with a focus on simplicity and reliability

Thank you for choosing Questful. Let's build something amazing together!

Introduction to Questful Questing Platform: A powerful questing as a service platform for creating and managing quests and rewards in your applications

Getting Started


# Key Concepts

This guide explains the core concepts and relationships in the Questful platform, helping you understand how different components work together.

## Entities and Relationships

```
    User[User] --> Quest[Quest]
    User --> Reward[Reward]
    Quest --> Reward
    User --> Redemption[Reward Redemption]
    Reward --> Redemption
    User --> Completion[Quest Completion]
    Quest --> Completion
    Completion --> Reward
```

### Core Entities

1. **Users**
   - Represent your application's users
   - Identified by a unique `customerId`
   - Can have multiple rewards
   - Can complete multiple quests

2. **Quests**
   - Tasks or challenges users can complete
   - Associated with specific rewards
   - Can be of different types (standard, daily, social)
   - May require social media verification

3. **Rewards**
   - Points or items users can earn
   - Can be redeemed for various purposes
   - Tracked with balances per user

4. **Quest Completions**
   - Records when a user completes a quest
   - Links users to completed quests
   - Triggers reward distribution
   - Maintains completion history
   - Tracks completion timestamps

5. **Reward Redemptions**
   - Records of users redeeming their rewards
   - Maintains transaction history
   - Updates user reward balances

## Users and CustomerId

The `customerId` is the primary identifier for users in the Questful platform:

- Must be unique within your account
- Can be any string that uniquely identifies a user in your system
- Used across all API endpoints to reference users
- Automatically creates a new user if it doesn't exist

Example:
```json
{
  "customerId": "user_123",
}
```

## Quests and Quest Types

### Quest Types

**1. Standard Quests**
   - One-time completion quests
   - Can only be completed once per user
   - Perfect for tutorial or achievement quests

**2. Daily Quests**
   - Reset every 24 hours
   - Can be completed once per day
   - Ideal for daily engagement activities

**3. Social Quests**
   - Require social media interaction verification
   - Currently supports Twitter follow quests
   - Real-time verification of social actions
   - Can only be completed once per user
   - Perfect for community building and social engagement

### Quest Structure

```json
{
  "id": "quest_123",
  "name": "Welcome Quest",
  "description": "Complete your first quest",
  "type": "standard | daily | twitter-follow",
  "rewardAmount": 100,
  "rewardId": "reward_123",
  "status": "live",
  "startDate": "2024-12-31T23:59:59Z",
  "endDate": "2025-12-31T23:59:59Z",
  "socialQuestParams": {
    "twitterFollowParams": {
      "accountToFollowUsername": "questful" // Required for twitter-follow quests
    }
    "twitterRetweetParams": {
            postIdToRetweet: "123"; // Required for twitter-retweet quests
        }
        "twitterCommentParams": {
            postIdToComment: "123"; // Required for twitter-comment quests
        }
  },
  "createdAt": "2024-12-31T23:59:59Z",
  "updatedAt": "2024-12-31T23:59:59Z"
}
```

## Rewards

Rewards are the points or items users can earn and redeem:

### Reward Structure

```json
{
  "id": "reward_123",
  "name": "Experience Points",
}
```

## Quest Lifecycle

**1. Creation**
   - Quest is created with specific requirements and rewards
   - Can be set as "draft", "published" or "archived"
   - Expiration date is required
   - For social quests, required social parameters must be configured

**2. Publishing**
   - Quest status is set to "published"
   - Quest becomes available to users

**3. Completion**
   - User completes the quest requirements
   - For social quests, system verifies the social action (e.g., Twitter follow)
   - You make an API call to our system to trigger the quest completion for the user
   - Rewards amount is awarded to the user
   - Quest is marked as completed

**4. Reset/Expiration**
   - Daily quests reset at midnight UTC
   - Social and Standard quests can only be completed once
   - Expired quests become unavailable

## Reward Lifecycle

**1. Earning**
   - User completes a quest
   - System awards specified reward amount
   - Balance is updated immediately

**2. Accumulation**
   - Rewards are stored in user's balance
   - Can be viewed through API
   - Separate balances per reward

**3. Redemption**
   - User requests reward redemption
   - System verifies sufficient balance
   - Balance is updated after redemption

**4. History**
   - All transactions are recorded
   - Includes earning and redemption history
   - Can be queried through API

### Rewards Redemption Process

**1. Initiation**
   - User requests reward redemption
   - You make an API call to our system to process the Redemption
   - System checks current balance
   - Validates redemption amount

**2. Processing**
   - Deducts amount from balance
   - Creates redemption record
   - Generates transaction ID

**3. Completion**
   - Updates user's reward balance
   - Returns new balance to user
   - Records transaction in history

### Important Notes

- Redemptions cannot exceed available balance
- Redemption history is permanent and cannot be reversed
- Balances are updated atomically to prevent race conditions
- Social quest verifications are performed in real-time
- Twitter usernames for social quests must be provided without the @ symbol 

Understanding the core concepts and relationships in the Questful platform

Key Concepts

API Key


Your secret API Key is your access key to use Questful Platform. Each organization can create and have only one API Key active at any given moment in time. 

⚠️ Important: Do not share your API key with others, or expose it in the browser or other client-side code. You are the sole responsible of keeping your API Key safe and avoid any unintended usage of your key.

## Creating an API Key

To create an API Key, follow these steps:
- Access the API Key section: Navigate to the [API Key section](questful.dev/apiKey).
- Create an API Key: Click on "Create New API Key" Button.

Note: Clicking on the "Create New API Key" while an API Key is already in use, it will result in the revoking of the existing one. This action is irreversible.

Learn how to create an API Key to use Questful Platform.

How to Create an API Key


## Deleting an API Key

To Delete an API Key, follow these steps:
- Access the API Key section: Navigate to the [API Key section](questful.dev/apiKey).
- Delete an API Key: Click on "Delete API Key" Button.

Note: Clicking on the "Delete New API Key" will revoke the currently active API Key. This action is irreversible.

Learn how to Delete an API Key to use Questful Platform.

How to Delete an API Key

Endpoints


# Complete Quest

This endpoint allows you to mark a quest as completed for a user and award the associated rewards.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
POST /api/v1/completeQuest
```

## Request Body

```json
{
  "customerId": "string",     // Required: The unique identifier for the user
  "questId": "string",        // Required: The ID of the quest to complete
  "twitterUsername": "string" // Required only for twitter-follow quests: The username of the user completing the quest (without @ symbol)
}
```

## Response

### Success Response (200 OK)

```json
{
  "questId": "string",
  "customerId": "string",
  "status": "success",
  "newRewardsBalance": number,
  "txId": "string"
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Invalid body",
    "details": {
      // Validation error details
    }
  }
  ```
  - When the request body is invalid
  - When the quest is not yet active
  - When the quest has ended
  - When the user has already completed a standard quest
  - When the user has already completed a daily quest today (resets at 00:00 UTC)
  - When the Twitter username is missing for twitter-follow quests
  - When the Twitter username starts with @ (should be provided without @)
  - When the user has not followed the required Twitter account

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in request"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the quest user limit"
  }
  ```
  - When you've reached your plan's user limit
  - When you've reached your plan's transaction limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Quest Types

The endpoint supports different types of quests:

### Standard Quests
- Can only be completed once per user
- No additional parameters required

### Daily Quests
- Can be completed once per day per user
- Resets at 00:00 UTC
- No additional parameters required

### Social Quests
Currently supports:

#### Twitter Follow Quests
- Requires the user to follow a specific Twitter account
- Additional required parameter: `twitterUsername` (without @ symbol)
- Verifies that the user has actually followed the specified account
- Can only be completed once per user
- The account to follow is configured in the quest settings

## Notes

- For standard quests and social quests, a user can only complete each quest once
- Daily quests can be completed once per day (resets at 00:00 UTC)
- The endpoint will automatically create a new user if the provided customerId doesn't exist
- The response includes the new balance of rewards after completing the quest
- Twitter usernames must be provided without the @ symbol
- Social quest verification is performed in real-time 

Complete a quest for a user and award the associated rewards

Complete Quest


# Redeem Reward

This endpoint allows you to redeem rewards for a user, deducting the specified amount from their rewards balance.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
POST /api/v1/redeemReward
```

## Request Body

```json
{
  "customerId": "string",  // Required: The unique identifier for the user
  "rewardId": "string",    // Required: The ID of the reward to redeem
  "redeemAmount": number   // Required: The amount of rewards to redeem
}
```

## Response

### Success Response (200 OK)

```json
{
  "customerId": "string",
  "rewardId": "string",
  "redeemAmount": number,
  "newRewardsBalance": number,
  "txId": "string"
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Invalid body",
    "details": {
      // Validation error details
    }
  }
  ```
  - When the request body is invalid
  - When the user has insufficient rewards balance
  - When the reward is not available

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in request"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the reward user limit"
  }
  ```
  - When you've reached your plan's user limit
  - When you've reached your plan's transaction limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- The endpoint will automatically create a new user if the provided customerId doesn't exist
- The response includes the new balance of rewards after the redemption
- Each redemption transaction is tracked with a unique transaction ID (txId)
- The redeemAmount must be a positive number 

Redeem Reward


# Get Completed Quests

This endpoint allows you to retrieve completed quests for users in your organization. You can filter by specific quest ID or user ID.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
GET /api/v1/getCompletedQuests
```

## Query Parameters

- `questId` (string, optional) - Filter results by specific quest ID
- `userId` (string, optional) - Filter results by specific user ID

## Response

### Success Response (200 OK)

```json
{
  "completedQuests": [
    {
      // Quest completion transaction details
    }
  ]
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Invalid query parameters",
    "details": {
      // Validation error details
    }
  }
  ```
  - When the query parameters are invalid

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in quest"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **405 Method Not Allowed**
  ```json
  {
    "error": "Invalid quest method"
  }
  ```
  - When using a method other than GET

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the quest limit per minute. Please slow down tiger."
  }
  ```
  - When you've exceeded your plan's rate limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Starter Plan**: 10 API calls per minute
- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- Results are filtered by your organization ID automatically
- You can combine questId and userId filters to get more specific results
- The endpoint returns an array of completed quest transactions 

Get Completed Quests


# Get Rewards Balance

This endpoint allows you to retrieve the current rewards balance for a user.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
GET /api/v1/getRewardsBalance
```

## Query Parameters

- `customerId` (string, required) - The unique identifier for the user
- `rewardId` (string, required) - The ID of the reward type to check balance for

## Response

### Success Response (200 OK)

```json
{
  "customerId": "string",
  "rewardId": "string",
  "balance": number
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Missing required parameters",
    "details": {
      // Validation error details
    }
  }
  ```
  - When required query parameters are missing
  - When query parameters are invalid

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in request"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the balance check limit"
  }
  ```
  - When you've reached your plan's user limit
  - When you've reached your plan's transaction limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- The endpoint will return a balance of 0 for new users
- The balance is specific to the reward type specified by rewardId
- This endpoint is read-only and does not modify any data 

Get the current rewards balance for a user

Get Rewards Balance


# Get Quests

This endpoint allows you to retrieve all available quests for a user, including their completion status and rewards.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
GET /api/v1/getQuests
```

## Query Parameters

- `questId` (string, optional) - Filter results by specific quest ID
- `status` (enum, optional) - Filter results by quest status. Valid values: 'draft', 'published', 'archived'

## Response

### Success Response (200 OK)

```json
{
  "customerId": "string",
  "quests": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "type": "standard" | "daily",
      "rewardAmount": number,
      "rewardId": "string",
      "isCompleted": boolean,
      "completedAt": "string" | null,
      "expiresAt": "string" | null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Missing required parameters",
    "details": {
      // Validation error details
    }
  }
  ```
  - When required query parameters are missing
  - When query parameters are invalid

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in request"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the quest retrieval limit"
  }
  ```
  - When you've reached your plan's user limit
  - When you've reached your plan's transaction limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- The endpoint will return an empty quests array for new users
- Daily quests are automatically reset at midnight UTC
- The response includes both active and completed quests
- Each quest includes its reward information and completion status
- The expiresAt field is only present for time-limited quests 

Get Quests


# Get Redeemed Rewards

This endpoint allows you to retrieve the history of redeemed rewards in your organization. You can filter by specific reward ID or customer ID.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
GET /api/v1/getRedeemedRewards
```

## Query Parameters

- `rewardId` (string, optional) - Filter results by specific reward ID
- `customerId` (string, optional) - Filter results by specific customer ID

## Response

### Success Response (200 OK)

```json
{
  "redeemedRewards": [
    {
      // Reward redemption transaction details
    }
  ]
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Invalid query parameters",
    "details": {
      // Validation error details
    }
  }
  ```
  - When the query parameters are invalid

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in quest"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **405 Method Not Allowed**
  ```json
  {
    "error": "Invalid quest method"
  }
  ```
  - When using a method other than GET

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the quest limit per minute. Please slow down tiger."
  }
  ```
  - When you've exceeded your plan's rate limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Starter Plan**: 10 API calls per minute
- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- Results are filtered by your organization ID automatically
- You can combine rewardId and customerId filters to get more specific results
- The endpoint returns an array of reward redemption transactions
- Transaction history includes details about each reward redemption 

Get Redeemed Rewards


# Get Users

This endpoint allows you to retrieve all users associated with your account, including their quest and reward information.

## Authentication

To access this endpoint, you must include an `Authorization` header with your API key:

```
Authorization: YOUR_API_KEY
```

## Endpoint

```
GET /api/v1/getUsers
```

## Query Parameters

- `customerId` (string, required): The unique identifier of the customer to retrieve users for

## Response

### Success Response (200 OK)

```json
{
  "users": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "quests": {
        "total": number,
        "completed": number,
        "active": number
      },
      "rewards": {
        "total": number,
        "redeemed": number,
        "available": number
      }
    }
  ],
  "pagination": {
    "total": number,
    "page": number,
    "limit": number,
    "totalPages": number
  }
}
```

### Error Responses

- **400 Bad Request**
  ```json
  {
    "error": "Invalid parameters",
    "details": {
      // Validation error details
    }
  }
  ```
  - When query parameters are invalid
  - When page or limit values are out of range

- **403 Forbidden**
  ```json
  {
    "error": "No API Key in request"
  }
  ```
  - When no API key is provided
  - When the API key is invalid
  - When the endpoint is not allowed with your current subscription plan

- **429 Too Many Requests**
  ```json
  {
    "error": "You have reached the user retrieval limit"
  }
  ```
  - When you've reached your plan's user limit
  - When you've reached your plan's transaction limit

- **500 Internal Server Error**
  ```json
  {
    "error": "An unexpected error occurred",
    "details": "Error message"
  }
  ```

## Rate Limits

Rate limits vary by subscription plan:

- **Grow Plan**: 100 API calls per minute
- **Pro Plan**: 500 API calls per minute
- **Enterprise Plan**: Unlimited API calls

## Notes

- The endpoint supports pagination to handle large numbers of users
- The search parameter can be used to filter users by their ID or name
- The response includes summary statistics for each user's quests and rewards
- The pagination object provides information about the current page and total results
- Users are sorted by creation date in descending order (newest first) 

Get Users

Changelogs


## Release Date: March 1, 2025

We are excited to announce the initial release of Questful, version 1.0. In this inaugural version, there are no changes to report as it marks the starting point of our API's journey.

**Key Highlights:**

- Version: 1.0
- Release Date: March 1, 2025
- No Changes: This release establishes the foundation of our API Platform, and no modifications or updates have been made since its inception.

We are committed to providing you with a stable and reliable API to enhance your application's capabilities. Stay tuned for future updates and enhancements as we continue to evolve and improve our API.

If you have any questions or require assistance, please don't hesitate to reach out to our support team.

Thank you for choosing our API, and we look forward to serving your needs in the future!

---

Documentation

Explore our guides and examples to integrate Questful Platform in your app.

Introduction

API Key

Endpoints

Changelogs

Introduction

API Key

Endpoints

Changelogs