Adding API quests#

A quest is a container for one or more tasks. Social tasks — join a Discord, wishlist on Steam — validate themselves. Tasks about your game need something to tell Gamearly whether the player did the thing, and there are two ways to provide that.

Pick per task, not per project. A single quest can mix both.

1. API task — you decide, on your servers#

The task can be anything your game can measure: finish the tutorial, reach Diamond rank, own the collector's edition, beat the boss without dying, find the level 2 easter egg.

Gamearly has no way to know whether any of that happened, so you answer for it:

The player presses Verify in Gamearly.
We send a signed request to a verification endpoint that you host.
You reply completed: true or completed: false.

You can also skip the round trip entirely and push the completion to /quests/complete_task the moment it happens in your game. That is the smoother experience — the task is already done when the player looks at it, instead of them waiting on a spinner while we call your server.

Cost: an HTTPS endpoint you host, operate and keep fast. Benefit: it can express anything, because you write the logic.

2. In-game event quest — validates itself#

If your game already reports in-game events, a quest can be built directly on top of one. An admin picks an event name and a target, and that is the whole setup:

event: killed_monster    target: 10     ->  "Kill 10 monsters"

From then on it runs itself. Every matching event that arrives advances that player's progress, and the quest completes the moment the target is reached. There is no verification endpoint, no complete_task call, and no extra integration — the events you are already sending are the mechanism.

That is the part worth emphasising: one integration serves two purposes. The killed_monster event you send is simultaneously

a row in your analytics — trends, funnels, cohort breakdowns on your dashboard, and
live quest progress for that player.

You do not instrument your game twice, and you cannot have a quest that disagrees with your charts, because both read the same stream.

Cost: none beyond sending events, which you want anyway. Benefit: progress is incremental and automatic, and players see it move in real time. Limit: the quest can only express what an event can — "this happened, this many times". For anything requiring judgement, use an API task.

Choosing between them#

	API task	In-game event quest
Who decides completion	your server	the event stream
You must host an endpoint	yes	no
Progress shown to the player	complete / not complete	incremental, live
Works for arbitrary logic	yes	only "event X, N times"
Extra work if you already send events	an endpoint	none

If you are only going to do one thing

Send in-game events. They cost one integration, they power your analytics regardless, and they turn quest creation into something an admin can do in the dashboard without shipping a game update or touching your backend.

Guardrails on both#

Quest progress is clamped to the task's target, so a flood of events or repeated complete_task calls can never earn more than one completion.

complete_task is private-key only, and this is the anti-cheat boundary

Completing a task grants its reward, so the call requires quests:write — which only your private key (gak_prv_…) holds. Calling it with the public key returns 403 insufficient_scope. That is not an oversight to work around: a key shipped inside your game can be extracted by anyone who owns it, and a route that grants rewards must not be reachable from there. Call complete_task from your server.

The same applies to event quests. If a quest grants something you care about, send the deciding events from your server with the private key — which marks them trusted — and turn on "require trusted events for quests". Ordinary telemetry keeps coming from the client with the public key.

Prerequisites#

Gamearly Connect — link your users to their Gamearly accounts, so rewards land on the right person.
For API tasks: a verification endpoint.
For event quests: you are sending in-game events.

Retroactive by design

Events sent for a player before they linked their Gamearly account are attributed once they link, so a quest can complete on history you already reported.