---
title: "Read the quest file"
method: GET
path: "/quests"
tags: ["Quests"]
---

# Read the quest file

`GET /quests`

## Request

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

What there is to do for the GEO work, newest first, every active project by default. Each
quest carries `journal_entries` and `last_entry_at`, how many actions were recorded against
it and when the last one happened; the entries themselves are read with `GET
/projects/{id}/logbook?quest_id=`. The open file also carries `pending`, the work the
measurement itself is holding for review, composed on every read so it empties on its own as
the moves are made.

## Query parameters

- `status` 'open' | 'done' | 'dismissed': 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.
- `project_id` string, uuid

## Response `200`

The quest file. `pending` comes with the open file; on the project-scoped read it also
carries `corroboration_candidates`.

- object
  - `quests` 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
  - `pending` QuestPending: The work the measurement itself is holding for review, composed on every read from the product's own registries, so it empties on its own as the moves are made.
    - `surfaces_to_align` object[], required: The surfaces whose canon moved since they were last marked aligned.
      - `project_id` string, uuid
      - `project` string
      - `surface_id` string, uuid
      - `surface` string
      - `url` string
    - `corroborations_to_refresh` object[], required: The corroborations recorded or published BEFORE the current canon version whose request channel is not `none`, oldest first. A suggested move, never a status.
      - `project_id` string, uuid
      - `project` string
      - `corroboration_id` string, uuid
      - `corroboration` string
      - `url` string
      - `published_on` string, date, nullable
      - `request_channel` 'available' | 'none' | 'unknown': Whether someone can be asked to change the page: `available` (a contact or a process exists), `none` (nobody to ask) or `unknown` (not filled in, the default). Three states, because "no channel" and "not filled in" are two different facts.
    - `corroborations_to_reread` object[], required: The lines whose last reading found the text moved, the link gone, or the page silent.
      - `project_id` string, uuid
      - `project` string
      - `corroboration_id` string, uuid
      - `corroboration` string
      - `url` string
      - `mention_finding` string, nullable
      - `link_finding` string, nullable
      - `checked_at` string, date-time, nullable
    - `keyword_discoveries` object[], required: The trackers with suggestions waiting; read them with `GET /trackers/{id}/discoveries`.
      - `tracker_id` string, uuid
      - `tracker` string
      - `project_id` string, uuid, nullable
      - `project` string, nullable
      - `count` integer
    - `corroboration_candidates` CorroborationCandidate[]: The same entries as `GET /projects/{id}/corroboration-candidates`. They are computed per project, so the key comes with the project-scoped read.
      - `url` string, required
      - `domain` string, required
      - `excerpt` string, nullable, required
      - `matched_by` 'website' | 'name', required: The strength of the proof: `website` means the full domain of the brand appears in the excerpt, which is near proof; `name` means only the name did, so read the page before recording it.
      - `engines` Engine[], required
      - `seen_on` string, date, required
      - `published_on` string, date, nullable, required
      - `suggested` 'surface' | 'ask' | 'corroboration', required: The registry the filing is proposed in: `surface` when the host is a known profile place, `ask` when the address looks like a listing on a place outside that catalogue, so it can be either side, and `corroboration` otherwise. On an `ask`, the test that settles it is the criterion itself: if they change that page, does the change stay?
      - `page_check` object: Present when the page was read.
        - `result` string, nullable
        - `excerpt` string, nullable
        - `checked_at` string, date-time

## Other responses

- `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_status` or `invalid_project`: the message lists the catalogue.
- `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)