API tasks
What are API Tasks?
The API task type allows you to connect your external application or platform directly to claimr’s reward system. These tasks listen for specific API calls from your platform and let you reward users for actions, values, or events that happen outside claimr.
Use API tasks to
Reward users for actions performed in your own app or platform that are not native to claimr.
Synchronize user progress and achievements from your external platform with their claimr profile.
Track important metrics or activity data that reflect engagement in your product.
Create reward systems that react instantly to real-time data from your application.
API tasks combine both event-based and value-based logic. When rewarding users based on continuous value streams, event counts, or specific actions with measurable results, your platform will use the POST /stream/value and POST /action/value methods. For details on how to set these up, see the sections on POST /stream/value and POST /action/value in the API Methods article.
There are five main types of API tasks you can configure:
Custom events count: Track how many times a custom event occurred.
Custom events value: Track the total numeric value of a custom event.
API number value: Fetch and verify a numeric value returned by an API input.
API stream value: Track live data continuously sent from your API endpoint.
API score: Validate a user score returned by your API.
Custom events count
Go to your quest and click + Create new task.
Under the Category section, select API.
Choose Custom Events Count from the list of task types.
Click Continue to proceed to task settings.
Now move on to configuring the specific settings for your task.
Completion points: Set the number of points awarded once the user reaches the required event count.
Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 5% multiplier increases the final reward by 5%.
Recurrence: Control how often users can complete the task: Once – can only be completed one time per user. 8h – available once every eight hours. Daily – available once every 24 hours. Weekly – available once every 7 days. Multiple – stays open and can be completed as many times as needed, one after another, without any waiting time.
Event category (optional): A tag that helps you organize and group event types.
Event name: The exact event identifier being tracked. Example, “Session”.
Platform: The platform or integration source that sends the event. For these tasks, “web3”.
Query (optional): A filter that defines which events should be counted based on specific parameters inside the event data. If a query is set, only events matching the filter are counted. For example, if your event contains {"itemID": 2}, a query like [?itemId==2] will count only those events where itemID equals 2. If no query is set, all received events are counted.
Events count: The minimum number of events required to trigger the reward.
Start at (optional): The date and time when the task becomes active. If set, events that occur before this time are ignored.
End at (optional): The date and time when the task stops being active. If set, events after this time are ignored.
If both Start at and End at are defined, only events that occur within this period are counted.
Claim button text (optional): Custom label for the task’s claim button. Example: “Get your reward”).
Refresh button text (optional): Custom label for the button that updates task progress. Example, “Update”.
Optional toggles
Hide progress? Hide progress information from the user interface.
Is progressive reward? When enabled, the final reward scales based on how much the user exceeds the required event count. For example, if the expected count is 100 and the user reaches 300, they receive 3× the reward. This setting motivates users to continue performing actions beyond the minimum requirement.
Is continuous? When enabled, the task remains open even after completion. Users can continue earning additional points each time they meet the task conditions again. This option also affects recurrence logic. Example: With daily recurrence and continuous off – all events are tracked and counted. With daily recurrence and continuous on – only events from the last 24 hours are considered.
Max progressive count (optional) Set the maximum event count that can be used to calculate progressive rewards. If the user exceeds this number, the reward will still be capped at the maximum. For example, if the maximum progressive count is 1,000 and the user completes 10,000 events, they will receive the reward for 1,000 events only.
Once you’re done:
Click Create task to save and add it to your quest right away. You’ll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click Advanced settings to configure additional options specific to this task type.
Custom events value
Go to your quest and click + Create new task.
Under the Category section, select API.
Choose Custom Events Value from the list of task types.
Click Continue to proceed to task settings.
Now move on to configuring the specific settings for your task.
• Completion points: Set the number of points awarded once the total event value reaches the threshold.
• Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 10% multiplier increases the final reward by 10%.
• Recurrence: Control how often users can complete the task: Once – can only be completed one time per user. 8h – available once every eight hours. Daily – available once every 24 hours. Weekly – available once every 7 days. Multiple – stays open and can be completed as many times as needed, one after another, without any waiting time.
• Event category (optional): A tag that helps you organize and group event types.
• Event name: The exact event identifier being tracked. Example, “Session”.
• Platform: The platform or integration source that sends the event. For these tasks, “web3”.
• Query (optional): A path that extracts or filters the numeric value from incoming events. If a query is set, only the data that matches the filter will be used to calculate the total value.
For example, a query like [].data.bet extracts the “bet” value from each event in a list of received data. If no query is set, all event values are included.
• Events value: The minimum total value needed across all received events to trigger the reward.
• Start at (optional): The date and time when the task becomes active. If set, events that occur before this time are ignored.
• End at (optional): The date and time when the task stops being active. If set, events after this time are ignored.
If both Start at and End at are defined, only events that occur within this period are counted.
• Claim button text (optional): Custom label for the task’s claim button. Example, “Get reward”.
• Refresh button text (optional): Custom label for the button that updates task progress. Example, “Update”.
Optional toggles
• Hide progress? Hide progress information from the user interface.
• Is progressive reward? When enabled, the final reward scales based on how much the user exceeds the required event value. For example, if the expected value is 100 and the user reaches 300, they receive 3× the reward. This setting is useful when the event contains numeric or quantity-based data, such as deposit amount, total bets, or items collected.
• Is continuous? When enabled, the task remains open even after completion. Users can continue earning additional points each time they reach the required value again. This option also affects recurrence logic. Example: With daily recurrence and continuous off – the total value is counted across all events. With daily recurrence and continuous on – only the value from the last 24 hours is considered.
• Max progressive value (optional) Set the maximum total value that can be used to calculate progressive rewards. If the user exceeds this number, the reward will still be capped at the maximum. For example, if the maximum progressive value is 1,000 and the user reaches 10,000, they will receive the reward for 1,000 only.
Once you’re done:
Click Create task to save and add it to your quest right away. You’ll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click Advanced settings to configure additional options specific to this task type.
Example of a query generated with AI
Prompt example: Provide a JMESPath query to extract the data.bet attribute from each item in a list.
Prompt answer:
To extract the data.bet attribute from each item in a list using JMESPath, use the query [].data.bet:
[] — iterates over each element in the list.
.data.bet — accesses the data.bet attribute of each element.
[
{ "data": { "bet": 100 } },
{ "data": { "bet": 200 } },
{ "data": { "bet": 300 } }
]Result
[100, 200, 300]API number value
Go to your quest and click + Create new task.
Under the Category section, select API.
Choose API number value from the list of task types.
Click Continue to proceed to task settings.
Now move on to configuring the specific settings for your task.
Completion points: Set the number of points awarded when the user completes the task.
Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 20% multiplier increases the final reward by 20%.
Message (optional): Enter a message that can be displayed to the user upon successful completion. Example:
You earned {api_user_value} EpiValue out of {api_min_value} required.
Min value: Define the target score or XP value that a user needs to reach for this task to be considered complete. When the incoming value (received via API for this task) meets or exceeds this Min value, the task is marked as completed.
Button Text (optional): Enter the text that will appear on the claim button for this task. Example: Claim your reward.
Once you’re done:
Click Create task to save and add it to your quest right away. You’ll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click Advanced settings to configure additional options specific to this task type.
API stream value
Go to your quest and click + Create new task.
Under the Category section, select API.
Choose API stream value from the list of task types.
Click Continue to proceed to task settings.
Now move on to configuring the specific settings for your task.
• Completion points: Set the number of points awarded when the user completes the task.
• Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 10% multiplier increases the final reward by 10%.
• Message (optional): Enter a message that can be displayed to the user upon successful completion. Example: Make purchases in the range {api_min_value}-{api_max_value}, at least {api_event_count} times for a total amount of at least {api_total_value}.
• Stream name: Define a unique identifier for a group of tasks. Multiple tasks can share the same stream name to react collectively to API calls. Choose a meaningful name for your stream (e.g., sales_stream, order_processing).
• Min stream value: Set the minimum value threshold. Any values passed by API calls below this limit will be ignored. Set this to the lowest value considered significant for your task (e.g., if values below 10 are irrelevant, set min stream value to 10).
• Max stream value: Set the maximum value threshold. Any values passed by API calls above this limit will be ignored. Set this to the highest value that is relevant (e.g., if values above 1000 should be ignored, set max stream value to 1000).
• Expected success events count: Define the minimum number of events within the specified Min stream value and Max stream value limits required to consider the task as completed. Specify the number of successful events needed (e.g., if at least 50 events are needed, set expected success event count to 50).
• Expected total success events value: Specify the total sum of all events within the specified Min stream value and Max stream value limits required to consider the task as completed. Define the cumulative value needed for task completion (e.g., if the total value must be at least 5000, set expected total success events value to 5000).
• Button text (optional): Enter the text that will appear on the claim button for this task. Example: Get reward.
Once you’re done:
Click Create task to save and add it to your quest right away. You’ll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click Advanced settings to configure additional options specific to this task type.
API score
Go to your quest and click + Create new task.
Under the Category section, select API.
Choose API Score from the list of task types.
Click Continue to proceed to task settings.
Now move on to configuring the specific settings for your task.
These settings control how a user's score or points (XP) for this task are updated based on values received via an API, and what constitutes task completion.
• Completion points: The number of points awarded when the user completes the task.
• Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 10% multiplier increases the final reward by 10%.
• Message (optional): Enter a message that can be displayed to the user upon successful completion.
• Increment XP: Determines how an incoming value (received via API for this task) affects the user’s current XP or score. If Increment XP is enabled: The incoming value is added to the user’s current XP. New XP = Current XP + value If Increment XP is disabled: The incoming value replaces (overwrites) the user’s current XP. New XP = value
• Final score (optional): Enter the target score or XP value that a user needs to reach for this task to be considered complete.
When the user’s current XP for this task (calculated according to the Increment XP setting) reaches or exceeds this Final score, the task is marked as completed.
Examples of Increment XP behavior
Current XP = 80, incoming value = 20
If Increment XP is on → New XP = 80 + 20 = 100
If Increment XP is off → New XP = 20
Task completion example
If Final score is set to 200: The task will be marked as complete when the user’s current XP for this task becomes 200 or greater, regardless of whether Increment XP is on or off (as it only affects how the current XP is calculated with each new value received).
Once you’re done:
Click Create task to save and add it to your quest right away. You’ll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click Advanced settings to configure additional options specific to this task type.
Last updated
Was this helpful?