---
title: "List versions"
method: GET
path: "/v2/versions"
tags: ["versions"]
---

# List versions

`GET /v2/versions`

## Request

- Base URL: `https://api.storydoc.com`
- URL: `https://api.storydoc.com/v2/versions`
- Auth: HTTP bearer

Lists the versions in your organization, newest first - the same versions the Versions tab shows to the person who created the API key: versions of Live stories in folders they can open (or in no folder), with each story's primary version left out. An administrator's key sees every folder. Every row carries the version's status (Live, Expired, Draft or Accepted, derived exactly as in the Versions tab), its story, the story's folder and the sender. Use it to find versions nobody has opened yet, or poll it with `dateField=updatedAt&dateFrom=<last sync>` to pick up changes (edits and acceptances update `updatedAt`; expiry does not - it follows from `expireAt`). A key scoped to one story only ever lists that story's versions. Variable values are not included; fetch one version with GET /v2/versions/{versionId} for those.

## Query parameters

- `storyId` string
- `folderId` string
- `senderEmail` string, email
- `title` string
- `status` string
- `hasAcceptButton` boolean
- `dateField` 'createdAt' | 'updatedAt'
- `dateFrom` string
- `dateTo` string
- `page` integer
- `pageSize` integer

## Response `200`

A page of versions

- VersionListResponse
  - `data` VersionSummary[]
    - `id` string: Version ID
    - `title` string, nullable: Version title
    - `status` 'Live' | 'Expired' | 'Draft' | 'Accepted': Accepted: the reader accepted it. Draft: unpublished, the link is off. Expired: past its expiry date. Live: otherwise.
    - `storyId` string: The story (template) the version was created from
    - `storyTitle` string, nullable: The story's title; null for a standalone version
    - `folder` object, nullable: The folder the story is filed in, and who can open it; null at the root
      - `id` string
      - `name` string
      - `path` string[]: Folder names from the root down
      - `sharedWithEveryone` boolean: True when everyone in your organization can open the folder (the app's "Share with everyone in your organization"). This is about your team, not the public: it says nothing about who can open the version's link.
      - `members` object[]: Who can open the folder when it is not shared with everyone; empty when it is. Access is set per folder (a parent's members do not carry over), and organization administrators can open every folder without being listed.
        - `name` string, nullable
        - `email` string, nullable
        - `role` 'Owner' | 'Editor', nullable
    - `sender` object, nullable
      - `name` string, nullable: Sender's name
      - `email` string, nullable: Sender's email
    - `url` string, uri, nullable: Public URL for the version; null when it is a Draft
    - `shortUrl` string, uri, nullable: Shortened URL for the version
    - `editorUrl` string, uri: URL to edit the version in the Storydoc editor
    - `versionUrl` string, uri: URL to the version's details in the Storydoc platform
    - `isPublic` boolean: True when the version never expires
    - `expireAt` string, date-time, nullable: When the link expires
    - `hasAcceptButton` boolean: Whether the version has an Accept button - a proposal the reader can accept. Not accepted yet: true here with a status other than Accepted.
    - `acceptedAt` string, date-time, nullable: When the reader accepted it; null unless Accepted
    - `source` string, nullable: How the version was created, e.g. Manual or API
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `pagination` object
    - `page` integer
    - `pageSize` integer
    - `hasMore` boolean: Whether another page follows

## Other responses

- `400`: Invalid query parameter
- `403`: Authentication failed, the key is scoped to a different story, the member who created the key has left the organization, or a legacy org token has been replaced by a newer one
- `404`: senderEmail is not a user of your organization, storyId is not a Live story, or folderId does not exist
- `429`: Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/storydoc/apis/storydoc-api-v2.md) - [All operations](https://skmtc.dev/storydoc/apis/storydoc-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/storydoc/apis/storydoc-api-v2/revisions/366e7d124e9e?raw)