---
title: "Add a quest"
method: POST
path: "/quests"
tags: ["Quests"]
---

# Add a quest

`POST /quests`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/quests`
- Auth: HTTP bearer

`project_id` travels in the body: the file is account-wide, the project is data. The call is
idempotent on `(project, title)` while the quest is open: send it again and you get the quest
already in the file, with `200` instead of `201`. A closed quest with the same title does not
block: doing the move again later is a new quest with its own history.

## Request body

- object
  - `project_id` string, uuid, required
  - `title` string, required: A short wording of the move: it is what the file shows.
  - `notes` string, nullable

## Response `200`

A quest with this title is already open in this project: it is the one that comes back.

- QuestEnvelope
  - `quest` Quest, required
    - `id` string, uuid, required
    - `project_id` string, uuid, required
    - `project` string, required: The name of the project.
    - `title` string, required
    - `notes` string, nullable, required
    - `status` 'open' | 'done' | 'dismissed', required: A quest opens as `open` and closes as `done` (the move happened) or `dismissed` (the customer set it aside); both stay readable as history, and both reopen.
    - `author` string, nullable, required
    - `created_at` string, date-time, required
    - `closed_at` string, date-time, nullable, required
    - `journal_entries` integer, required: How many actions were recorded against this quest.
    - `last_entry_at` string, date-time, nullable, required

## Other responses

- `201`: The quest, added.
- `401`: `unauthenticated`: missing, unknown or revoked key.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `404`: `not_found`: unknown for this account.
- `422`: `invalid_quest` or `invalid_project`.
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/epovest/apis/epovest-api.md) · [All operations](https://skmtc.dev/epovest/apis/epovest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/epovest/apis/epovest-api/revisions/7a78ee27ecbb?raw)