---
title: "List documents, newest first"
method: GET
path: "/documents"
tags: ["Documents"]
---

# List documents, newest first

`GET /documents`

## Request

- Base URL: `https://api.eu.doconda.com/v1`
- URL: `https://api.eu.doconda.com/v1/documents`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Query parameters

- `limit` integer
- `cursor` string
- `status` 'queued' | 'running' | 'ready' | 'ready_with_warnings' | 'needs_review' | 'failed' | 'canceled'

## Response `200`

A page of documents.

- object
  - `data` object[], required
    - `id` string, required
    - `object` 'document', required
    - `name` string, nullable, required: The name you gave it (`name` when creating it).
    - `operation` 'create' | 'review' | 'edit', required
    - `format` 'docx' | 'pdf' | 'pptx' | 'xlsx' | 'artifact', nullable, required: The file you want. `docx` → Word (with a PDF too), `pdf` → only the PDF, `pptx` → PowerPoint (with a PDF), `xlsx` → Excel (with a PDF). `artifact` → a web page that keeps data (in each visitor's browser, or shared by everyone), on a signed link; with `retention: none`, a page to download (see the artifacts guide). Without it, Doconda works it out from `prompt`.
    - `type` 'report' | 'letter' | 'contract' | 'memo' | 'minutes' | 'presentation' | 'spreadsheet' | 'artifact', nullable, required: What Doconda decided the document is. It sets the default look (a contract: serif, justified, numbered clauses; a letter: no page numbers). You don't choose it: say what you want in `prompt`, and the look in `style`.
    - `mode` 'prompt' | 'content', nullable, required
    - `revision` integer, required: 1 when it's made; +1 every time its file is saved by hand (PUT /documents/{id}/file). Send it back when saving so nobody's changes are overwritten.
    - `status` 'queued' | 'running' | 'ready' | 'ready_with_warnings' | 'needs_review' | 'failed' | 'canceled', required
    - `phase` string, nullable, required
    - `pages` integer, nullable, required
    - `style_applied` object, nullable, required
      - `font` string, required
      - `font_size` number, required
      - `line_spacing` number, required
      - `colors` object, required
        - `title` string, required
        - `headings` string, required
        - `text` string, required
        - `accent` string, required
      - `align` object, required
        - `title` 'left' | 'center' | 'right' | 'justify', required
        - `headings` 'left' | 'center' | 'right' | 'justify', required
        - `body` 'left' | 'center' | 'right' | 'justify', required
      - `margins_cm` number, required
      - `orientation` 'portrait' | 'landscape', required
      - `cover_page` boolean, required
      - `table_of_contents` boolean, required
      - `page_numbers` boolean, required
      - `header` string
      - `footer` string
    - `style_unsupported` string[], required
    - `validation_summary` object, nullable, required
      - `errors` integer, required
      - `warnings` integer, required
      - `info` integer, required
    - `repair_summary` object, nullable, required
      - `iterations` integer, required
      - `applied` integer, required
      - `rejected` integer, required
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
    - `versions` object, required
      - `engine` string
      - `renderer` string
      - `model` string, nullable
    - `metadata` object, required
    - `retention` 'none' | '1d' | '7d' | '30d' | '90d', required: How long Doconda keeps a document's content (files, request, report, events; an artifact's page and data) once it finishes. `none`: 15 minutes. Then only what billing needs stays (status, format, pages, cost).
    - `expires_at` string, date-time, nullable, required: When its content will be deleted: `retention` counted from when it finished or was last saved by hand (with `retention: none`, from when it finished).
    - `route` object, nullable, required: How the file was made, and why. `fast`: in seconds, with the basic style (`quality: "fast"`). `agent`: in minutes, with any design, templates, comments, tracked changes and charts (`standard` and `best`).
      - `path` 'fast' | 'agent', required
      - `reason` string, required
    - `quality` object, nullable, required: create and edit: the quality level asked for and the one used, which sets the price.
      - `requested` 'auto' | 'fast' | 'standard' | 'best', required: `auto`: Doconda picks the level. From `prompt`, the one the request needs (when in doubt, the cheaper one); from `content` alone, `standard`; `best` to copy a file's design (except a PowerPoint template for a presentation), to use a template with documents in `sources`, or for an edit with comments or tracked changes. `max_quality` caps it.
      - `level` 'fast' | 'standard' | 'best', nullable, required: How much work goes into the file. `fast`: seconds, basic style (the `style` options), the cheapest. `standard`: a few minutes, any style, templates and charts. `best`: more review and design care, the dearest.
      - `reason` string, nullable, required
    - `artifact` object, nullable, required: Artifacts only: where the page keeps its data.
      - `storage` 'local' | 'shared', required: Where an artifact's page keeps its data. `local`: in each visitor's browser (each one sees only theirs; nothing reaches Doconda). `shared`: in Doconda, the same for everyone with the link (polls, team lists). With `retention: none`, only `local`.
    - `content_deleted_at` string, date-time, nullable, required: When its content was deleted: its retention ended, or it was deleted.
    - `outputs` object[]: Present once finished.
      - `id` string, required
      - `kind` 'docx' | 'pptx' | 'xlsx' | 'pdf' | 'preview' | 'html' | 'md', required
      - `page` integer
      - `content_type` string, required
      - `bytes` integer, required
      - `width` integer
      - `height` integer
      - `url` string, required: Signed download URL, valid 5 minutes. For `html` (an artifact), the link to the page, which works until its retention ends or you delete it; with `retention: none`, the page to download.
      - `expires_at` string, date-time, nullable, required: When `url` stops working; null for an artifact's page, which works until the document's `expires_at`.
    - `created_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: unauthorized (missing, unknown or revoked key; expired session).

---

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