---
title: "Create an instance"
method: POST
path: "/recipes/{recipe_id}/instances"
tags: ["Private"]
---

# Create an instance

`POST /recipes/{recipe_id}/instances`

Create an instance in the recipe and add to mongo

## Path parameters

- `recipe_id` string, required

## Request body

- AddInstance — An instance represents a single dataset
  - `dataset_id` string — A unique id for a dataset
  - `editions` string[] — Types of editions within the dataset
  - `title` string — The title for the dataset
  - `code_lists` CodeList[] — A list of all code lists within this instance
    - `id` string — A unique id for a single code list
    - `name` string — The name of the codelist
    - `href` string — A URL to the code list
    - `is_hierarchy` boolean — A bool to inform if there is hierarchy for codelist

## Response `200`

A json object of specific recipe with new added instance

- Recipe — An object returned for a recipe
  - `id` string — A unique id for the recipe
  - `alias` string — An alias for the recipe
  - `format` 'v4' | 'cantabular_blob' | 'cantabular_table' — The recipe format
  - `files` InputFile[]
    - `description` string, required — The description of the input file
  - `output_instances` Instance[] — A list of all instances created using this recipe
    - `dataset_id` string — A unique id for a dataset
    - `editions` string[] — Types of editions within the dataset
    - `title` string — The title for the dataset
    - `code_lists` CodeList[] — A list of all code lists within this instance
      - `id` string — A unique id for a single code list
      - `name` string — The name of the codelist
      - `href` string — A URL to the code list
      - `is_hierarchy` boolean — A bool to inform if there is hierarchy for codelist
  - `cantabular_blob` string — A Cantabular-specific collection of data

## Other responses

- `400` — An incomplete/invalid instance entered in request to be added to mongo
- `401` — Unauthorisation request as invalid auth token given
- `500` — Failed to process the request due to an internal error

---

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