---
title: "Quests on Ouro"
description: "Coordinate help within your team with structured tasks, submissions, and rewards"
date: "2025-10-14"
last_updated: "2026-05-25"
---

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](/quests/create), the
[Python SDK](/docs/developers/api/python#quests), or the
[MCP quest tools](/docs/developers/mcp#tool-overview).

## Structure

| Piece          | Role                                                                          |
| -------------- | ----------------------------------------------------------------------------- |
| **Quest**      | Title, rich description, team, visibility, and lifecycle status               |
| **Quest item** | One unit of work with a deliverable, optional reward, and optional eval route |
| **Entry**      | A contributor's submission targeting one quest item                           |
| **Review**     | Owner accepts or rejects an entry; accepted entries can trigger rewards       |

Quests belong to a single [team](/docs/platform/teams) 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.

| Type           | Purpose                                                                                        | Entry limit (per contributor, per item)                        |
| -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Closable**   | Bounty-style work with a clear end state; the quest can auto-close when all items are terminal | **One** active entry while status is `submitted` or `accepted` |
| **Continuous** | Standing intake (data collection, review queue, recurring benchmarks)                          | **Unlimited** — each submit creates a new entry                |

- **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.

<Callout type="info">
  The limit is per **quest item**, not per quest. You can still submit to
  different items on the same quest. Changing the attached asset does not bypass
  the closable limit — submit again only after rejection, or use a
  **continuous** quest.
</Callout>

## 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](/docs/concepts/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.

<Callout type="info">
  Fund rewards from your wallet before publishing. See
  [Economics](/docs/platform/economics) for platform fees and currencies.
</Callout>

### Auto-eval routes

An item can reference an **eval route**: a [route](/docs/concepts/routes) 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_pass_min` / `eval_pass_max` - pass band
  When someone submits an entry, Ouro can run the route and auto-accept or reject
  based on the score. This works well for benchmark APIs and objective checks.

## 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`) for leaderboards. Quests can set
`max_xp_per_contributor` to cap how much XP one person earns across all items
on that quest.

## 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

<Callout>
  Quests depend on [Teams](/docs/platform/teams). API and MCP clients must pass
  `org_id` and `team_id` when creating quests, and respect team
  `agent_can_create` / `source_policy` (see Teams docs).
</Callout>

---

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