---
title: "Create a version"
method: POST
path: "/datasets/{id}/editions/{edition}/versions"
tags: ["Private"]
---

# Create a version

`POST /datasets/{id}/editions/{edition}/versions`

Create a version for a dataset series.  This will set the state of the version and dataset series to be associated.

## Path parameters

- `id` string, required
- `edition` string, required

## Request body

- Version — An object containing information about published datasets from the ONS
  - `alerts` Alert[] — A list of alerts, for example corrections after the resource has been published
    - `date` string, date-time, required — The date and time of publication of the version
    - `description` string, required — Detail of what a user needs to be aware of for this dataset
    - `type` 'alert' | 'correction', required — The type of alert. Available types: * `alert`: Important contextual information relevant to the interpretation of a specific version of the dataset. * `correction`: A correction notice summarising the data changes made in the corrected as compared to the superseded version.
  - `collection_id` string — **Internal Only: This is an internal only field and is not present once a dataset is published.** The id of the unpublished collection (of datasets) that this dataset is associated with."
  - `dataset_id` string — The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
  - `dimensions` Dimension[] — A list of codelists for each dimension of this version
    - `description` string
    - `dimension` string — The name of the dimension
    - `href` string — A link to the code-list entry for the dimension
    - `id` string — The id of the dimension
    - `is_area_type` boolean — Indicates if a dimension is an area-type (census datasets only)
    - `label` string
    - `links` object
      - `code_list` object — The code list related to this dimension
        - `href` string — A URL to the code list
        - `id` string — The unique id for the code list
      - `options` OptionsLink — A list of links related to this dimension
        - `href` string — A URL to a list of options for this dimension
      - `version` VersionLink — The dataset version this resource belongs to
        - `href` string — A URL to the version this resource relates to
        - `id` string — The version number this resource relates to
    - `number_of_options` integer — The number of options available for this dimension
    - `variable` string — The variable name (census datasets only)
  - `distributions` Distribution[], required — A list of representations of the dataset available and how to access them.
    - `title` string, required — The title or label of the distribution.
    - `download_url` string, url, required — URL to directly download a file for the distribution in the specified format.
    - `byte_size` integer — The size in bytes of the download file referenced by `download_url`.
    - `format` 'csv' | 'sdmx' | 'xls' | 'xlsx' | 'csdb', required — The format for the download file referenced by `download_url`. Formats supported: * `csv` * `sdmx` * `xls` * `xlsx` * `csdb`
    - `media_type` 'text/csv' | 'application/vnd.sdmx.structurespecificdata+xml' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain' — The IANA media type for the download file referenced by `download_url`. Media Types supported: * `text/csv`: CSV files * `application/vnd.sdmx.structurespecificdata+xml`: SDMX files * `application/vnd.ms-excel`: Excel (XLS) files * `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: Excel (XLSX) files * `text/plain`: Plain text (used for CSDB output structured text files)
  - `downloads` object — **Deprecated:** These fields have been deprecated and replaced by the `distributions` list. A selection of download objects containing information of downloadable files.
    - `csv` DownloadObject — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `csvw` object — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `txt` object — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `xls` DownloadObject — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
  - `edition` string — The unique identifier for an edition of a dataset. The edition ID cannot be changed once first published. If a subsequent version of the edition attempts to change the edition ID, they will be treated as the first version of a new edition instead.
  - `edition_title` string, required — The human readable title of the edition.
  - `is_based_on` IsBasedOn — Information about the population-type that the dataset is based on (census 2021 only)
    - `id` string — The population-type that the dataset is based on
    - `type` string — The type of the dataset
  - `is_migration` boolean — Indicates whether this version was created as part of a dataset migration
  - `last_updated` string, date-time — The date and time of the last update to the resource. For published resources this is the date and time the latest change was published.
  - `latest_changes` LatestChange[] — A list of changes between version of an edition for a dataset and the previous version of the same dataset edition
    - `description` string — A description of what has changed between versions
    - `name` string — The title of the change that has occurred between versions
  - `links` VersionLinks — A list of links related to this resource
    - `dataset` DatasetLink — An object containing the dataset id and link
      - `href` string — A URL to the parent dataset for this resource
      - `id` string — The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `dimensions` object
      - `href` string — A URL to list dimensions for this version
    - `edition` EditionLink — An object containing the edition and link
      - `href` string — A URL to the dataset edition for a version
      - `id` string — The unique id for the dataset edition for a version
    - `self` object — A link to this resource
      - `href` string — A URL to this resource
    - `web_page` object — A link to the location of this version of the dataset on the web
      - `href` string — The uri to the location of this version of the dataset on the web
    - `versions` object
      - `href` string — A URL to all versions for an edition of a dataset
  - `lowest_geography` 'oa' | 'lsoa' | 'msoa' | 'wpc' | 'ltla' | 'rgn' — The lowest geography this dataset is available at (Census datasets only) Possible geographies: * `oa`: Output Areas * `lsoa`: Lower layer Super Output Areas * `msoa`: Middle layer Super Output Areas * `wpc`: Westminster Parliamentary constituencies * `ltla`: Lower Tier Local Authorities * `rgn`: Regions
  - `quality_designation` 'accredited-official' | 'official' | 'official-in-development' | 'no-accreditation' — The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation`
  - `release_date` string, date-time, required — The release date of this version of the dataset
  - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published' — The state of the resource, can only be one of the following: * created * completed (instances only) * failed (instances only) * edition-confirmed (instances and versions only) * associated (not editions) * published
  - `type` 'filterable' | 'cantabular_flexible_table' | 'cantabular_multivariate_table' | 'static' — The type of dataset as determined by the backing data store. Used to determine which functionality is available for a dataset. Available types: * `filterable`: Datasets provided by Customise My Data product providing ability to filter observations by specific dimension options. * `cantabular_flexible_table`: Dataset derived from a `cantabular_blob` allowing the option to change the geography level and filter on specific areas. * `cantabular_multivariate_table`: Dataset with multiple variables derived from a `cantabular_blob` allowing the option to customise the dataset by adding or removing dimensions as well as by changing the geography level and dimension categorisation. * `static`: Datasets available as a flat file download without additional querying capabilities.
  - `usage_notes` UsageNote[] — A list of usage notes relating to the dataset
    - `title` string, required — The title of the usage note.
    - `note` string, required — The usage note text.
  - `version` integer — A number identifying the version for an edition from a dataset

## Response `201`

A json object containing a version

## Other responses

- `400` — Invalid request, reasons can be one of the following: * invalid request body * dataset id was incorrect * edition was incorrect * an unpublished version of the dataset already exists
- `401` — Unauthorised to update version of dataset
- `404` — Dataset series was not found for a dataset using the id and edition provided
- `500` — Failed to process the request due to an internal error

---

[API](https://skmtc.net/office-of-national-statistics/apis/dataset-api.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/dataset-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/dataset-api/versions/a2947a13d675/schema)