---
title: "Create one or more dimensions"
method: PATCH
path: "/instances/{instance_id}/dimensions"
tags: ["Private"]
---

# Create one or more dimensions

`PATCH /instances/{instance_id}/dimensions`

## Request

- Base URL: `https://api.beta.ons.gov.uk/v1`
- URL: `https://api.beta.ons.gov.uk/v1/instances/{instance_id}/dimensions`
- Auth: API key in header `Authorization`

Create one or more dimensions which are related to an instance

## Path parameters

- `instance_id` string, required

## Headers

- `If-Match` string

## Request body

- object[]: A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404.
  - `op` 'add': The operation to be made on path. * add - Sets the value for the provided path
  - `path` '/-' | '/{dimension}/options/{option}/order' | '/{dimension}/options/{option}/node_id': Path to value that needs to be operated on.
  - `value` string: A list of dimensions that will be added to the instance.

## Response `200`

All dimensions were successfully created

- object[]: A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404.
  - `op` 'add': The operation to be made on path. * add - Sets the value for the provided path
  - `path` '/-' | '/{dimension}/options/{option}/order' | '/{dimension}/options/{option}/node_id': Path to value that needs to be operated on.
  - `value` string: A list of dimensions that will be added to the instance.

## Other responses

- `400`: Failed to process the request due to invalid request
- `404`: The instance was not found
- `409`: Failed to process the request due to a conflict
- `500`: Failed to process the request due to an internal error

---

[API](https://skmtc.dev/office-of-national-statistics/apis/dataset-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/revisions/a2947a13d675?raw)