---
title: "List Documents"
method: GET
path: "/v1/documents"
tags: ["documents"]
---

# List Documents

`GET /v1/documents`

## Request

- Base URL: `https://api.versionstory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.versionstory.com/v1/documents`
- Auth: HTTP bearer

List the Documents in the user's account, newest first: each document's history, with its document_id,
name, version_count and latest_version. Use it only for a document the user has no
file of and that no earlier result names ("the Mission draft", "my NDA"); then GET /v1/documents/{document_id} lists its
versions. A name matching one of the user's files (in their folder, attached or linked) means that
file: upload it with POST /v1/files and work on it as given, without looking for the name here first,
unless the user asks for the stored versions.
A page holds up to limit Documents; pass next_cursor to read the next one.

## Query parameters

- `limit` integer: How many Documents to return.
- `cursor` string, nullable: Opaque continuation cursor from a prior page (its next_cursor).

## Headers

- `X-Customer-Id` string, nullable: Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide.

## Response `200`

Successful Response

- DocumentListResponse
  - `documents` Document[], required: This page's Documents, newest first, each without its versions.
    - `document_id` string, required: The Document's id.
    - `name` string, nullable: The Document's name: the name it was given, else its first file's.
    - `version_count` integer, required: How many versions it has.
    - `latest_version` VersionReference: A version a response points at: a parent, a Document's latest version, an edit's version. Sent back as it is, it names the version in a request (VersionLocator reads its version_id).
      - `document_id` string, required: The Document the version belongs to.
      - `version_id` string, required: The version's id.
      - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id.
      - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it.
    - `created_at` string, nullable: When the Document was made: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.
    - `updated_at` string, nullable: When the Document last changed: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.
    - `metadata` object: Your own string values by key, stored and returned as they were sent.
  - `next_cursor` string, nullable: Send it as cursor for the next page; absent on the last page.

## Other responses

- `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal.

---

[API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)