# List versions

**GET /v2/versions**

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.


## Servers
- Production API server: https://api.storydoc.com (Production API server)


## Authentication methods
- Bearer auth


## Parameters


### Query parameters

- **storyId** (string)
  Only versions created from this story (template). Must be a Live story.

- **folderId** (string)
  Only versions whose story is in this folder or any folder under it - the Versions tab's Location filter. A version sits in its story's folder. Folder ids come from GET /v2/folders. 404 if the folder does not exist.

- **senderEmail** (string(email))
  Only versions sent by this user of your organization

- **title** (string)
  Only versions whose title contains this text (case-insensitive, at most 200 characters)

- **status** (string)
  Comma-separated list of statuses to include

- **hasAcceptButton** (boolean)
  true: only proposals - versions with an Accept button. false: only versions without one. Combine with status for open proposals: `hasAcceptButton=true&status=Live`.

- **dateField** (string)
  Which date dateFrom/dateTo apply to

- **dateFrom** (string)
  Inclusive start (ISO 8601, UTC)

- **dateTo** (string)
  Inclusive end (ISO 8601, UTC). A date without a time covers that whole day.

- **page** (integer)
  1-based page number

- **pageSize** (integer)
  Versions per page



## Responses
### 200
A page of versions

#### Body: application/json (object)
- **data** (array[object])

- **pagination** (object)


### 400
Invalid query parameter

#### Body: application/json (object)
- **error** (string)


### 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

#### Body: application/json (object)
- **error** (string)

- **code** (string)
  `VARIABLES_PLAN_REQUIRED` when the story uses variables above the account's plan; absent for authentication failures.

- **requiredPlan** (string)
  With `VARIABLES_PLAN_REQUIRED`: the lowest plan that covers every blocked variable.

- **variables** (array[object])
  With `VARIABLES_PLAN_REQUIRED`: the blocked variables and the plan each needs.


### 404
senderEmail is not a user of your organization, storyId is not a Live story, or folderId does not exist

#### Body: application/json (object)
- **error** (string)


### 429
Too many requests

#### Body: application/json (object)
- **error** (string)


### 500
Internal server error

#### Body: application/json (object)
- **error** (string)

- **errorId** (string)



[Powered by Bump.sh](https://bump.sh)