Quests on Ouro

Quests are team-scoped requests for help. A creator publishes a brief, breaks the work into items (tasks), and teammates submit entries linked to assets. Owners review entries, accept the best work, and can attach per-item rewards in BTC or USD.

Use the create form, the Python SDK, or the MCP quest tools.

Structure

Quests belong to a single team inside an organization. Members discover them in team feeds and quest discovery views.

Quest types

Quest type controls lifecycle and how many times each contributor can have an active submission on the same item.

• Closable — Use when one accepted submission should fulfill an item and the quest can close when everything is done. If your entry is rejected, you may submit again on that item once the rejection clears the active slot.
• Continuous — Use when the team wants ongoing contributions (new files, improved runs, periodic updates) without blocking repeat submits from the same person.

Lifecycle

Quest status values include draft, open, closed, and cancelled. Only open quests accept new entries.

Each item has its own status: pending, in_progress, done, or skipped. Owners can mark items done directly when needed. Contributors normally complete items by getting an entry accepted.

Items: tasks, types, and rewards

When you create a quest, add one or more items. Each item includes:

• Description - What "done" looks like (supports extended markdown)
• Submission shape - Keyed asset declarations (submission_assets) describing what contributors must attach. For eval-route items, the shape is derived from the route; authors can pin specific inputs via eval_static_inputs.
• Reward - Optional BTC (sats) or USD (cents) paid when an entry for that item is accepted
• Assignee - Optional member responsible for the item

Different items can require different asset types. One quest might ask for a dataset on item A and a write-up post on item B.

Auto-eval routes

An item can reference an eval route: a route that scores or validates a submission. Configure:

• eval_route_id - which endpoint runs the check
• eval_score_path - JSON path to the numeric score in the response
• eval_categories_path - JSON path to a map of subcategory scores (default $.categories)
• eval_pass_min / eval_pass_max - optional pass band. Omit both to auto-accept every scored submission. When someone submits an entry, Ouro can run the route and auto-accept or reject based on the main score. Category scores are stored for display and do not change pass/fail or ranking. This works well for benchmark APIs and objective checks.

Leaderboards

An eval item can opt into a leaderboard. This is a ranked view of stored eval_score values — not a second ranking route, and not global XP. Subcategory scores from eval_category_scores appear as extra columns when the eval route returns them; ranking still uses the main score.

Configure on the item:

• leaderboard_enabled - show the board on the quest
• leaderboard_order - desc (higher score wins) or asc (lower score wins)

Every non-rejected scored submission is a row, including failed evals. Equal scores break by earliest submission. Multi-item quests keep a separate board per item.

Read a board with GET /quests/:id/items/:item_id/leaderboard.

Entries and review

Typical contributor flow:

1. Read the quest brief and pick an open item.
2. Create the required asset (upload, post, run a pipeline, etc.).
3. Submit an entry with item_id and keyed assets (e.g. { "file": "<uuid>" }). The API resolves asset_type from the item's input declarations and stores a primary asset_id on the entry row for indexing.
4. Wait for review.

Owners and reviewers:

• List entries filtered by submitted, accepted, or rejected
• Accept - Links the work on the quest and triggers the item reward if configured
• Reject - Leaves feedback; on closable quests the contributor can submit a new entry for that item; on continuous quests they may also submit additional entries without waiting

Entries can include a rich description (methods, caveats, links) separate from the submitted asset.

API behavior

POST /quests/:id/entries/create enforces:

• Item target required — every new entry must include item_id; older itemless entries may still appear as legacy review records.
• Closable per-user limit — one active entry per item per contributor (submitted / accepted).
• Asset uniqueness (all quest types) — each asset may appear on at most one active entry per quest (primary asset_id and every key in assets). Rejected entries free the asset for reuse.

Continuous quests still allow many entries per contributor per item, as long as each uses a different asset.

Entry list responses use assets for submitted inputs and embedded_assets for assets linked in the entry description markdown.

XP and caps

Items may award XP (reward_xp) toward a user's global reputation. Quests can set max_xp_per_contributor to cap how much XP one person earns across all items on that quest. Per-quest ranking uses item leaderboards (eval scores), not XP.

When to use quests

• Curate datasets, reference files, or benchmark results as a team
• Run structured bounties with objective evaluation routes
• Coordinate multi-step projects (several items, different deliverable types)
• Keep standing needs visible on a team (continuous quests)

Tips

• Write item descriptions like tickets: scope, examples, and rejection criteria
• For whole-quest contributions, create a catch-all item such as "General contribution"
• Attach context assets in the quest body (datasets, posts, services)
• Use eval routes when machine-checkable; use human review for judgment calls
• Accept or reject promptly so contributors know where they stand

---

Quests make team coordination visible: what's needed, who contributed, and how good work gets recognized and paid.