openapi: 3.0.0
info:
version: '3'
title: Kitchen Stories Internal Articles Admin User Private Recipes API
description: ''
contact:
email: hello@kitchenstories.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.kitchenstories.io/api
description: LIVE Environment
- url: https://api.dev.kitchenstories.io/api
description: Development Environment
- url: http://localhost:8000/api
description: Local Environment
security:
- bearerAuth: []
- ApiKeyAuth: []
tags:
- name: User Private Recipes
paths:
/users/me/recipes/:
get:
summary: List all Recipes from currently authenticated user
operationId: user-me-list-recipes
tags:
- User Private Recipes
parameters:
- name: simplified
in: query
description: Get simplified recipe schema
schema:
type: boolean
responses:
'200':
description: Get all Recipes from current user
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/recipe_pagination'
'403':
description: Forbidden. When user is not logged in
post:
summary: Create a new Private Recipe
operationId: user-recipe-create
tags:
- User Private Recipes
requestBody:
description: "## detailed notes for using this endpoint:\n### uuids:\n- for fields that are uuids (`image` `ingredient_id`, `unit_id`, `ingredient_additional_information_id`, `ingredient_characteristic_id`, `image_id`, `video_id` etc) :\n- you can not use non-uuid\n- omitting the field, putting null, or empty string will work - null is recommended\n### ingredients:\n- you must provide atleast one of `name` or `ingredient_id`, without these it wont error but this ingredient will be ignored. if both are provided the `name` field is ignored\n- from the api-perspective the rest are optional - if no amount/unit is provided none is returned etc. i dont know how clients handle these.\n- __important__ : __every__ valid uuid provided _MUST_ match with a uuid in the db for that item. if a `unit_id` is given in the `ingredient_id` field, or a `utensil_additional_information_id` in the `ingredient_additional_information_id` then the recipe __will not work__.\n### steps:\n- although you can omit `utensils` / `selected_ingredient_index` , if you have them in the json they can not be null , [] - empty list is the correct way to denote a list is not used.\n- `description` is required.\n- `selected_ingredient_index` is a reference to the ingredient list above. [0] means to include the 1st ingrediant from the list in this step. [2,4] means to include the 3rd and 5th. if it is out of range it will be ignored\n- the backend supports using the same ingredients for different steps (although at this stage clients do not allow this). splitting ingredients between steps is not supported.\n### utensils :\n- are embedded in the step (unlike ingredients), similar though you need to provide `name` or `utensil_id` , if both are provided the `name` is ignored\n\n<details> <summary> FULL EXAMPLE JSON </summary>\n```\n{\n \"title\": \"Red chilaquiles\",\n \"difficulty\": \"easy\",\n \"image_id\": \"9f7deaf1-7539-4c26-b4b8-af79e82ff712\",\n \"servings\": {\n \"amount\": 2,\n \"type\": \"portion\"\n },\n \"chefs_note\": \"you can make your own sauce but this is the easy version. often serve with a fried egg or pulled chicken breast\",\n \"tags\": [\"9d531987-ae3e-43c4-bc06-7848ddbc825f\"],\n \"ingredients\": [{\n \"name\": \"corn chips\",\n \"amount\": 150.0,\n \"unit_id\": \"81939ac3-6943-4be2-9842-e9ca99fd831d\",\n \"additional_information_id\": null,\n \"characteristic_id\": null\n },\n {\n \"ingredient_id\": \"d359a8dd-9708-42e1-b290-5e1c079d16a5\",\n \"amount\": 300.0,\n \"unit_id\": \"81939ac3-6943-4be2-9842-e9ca99fd831d\",\n \"additional_information_id\": null,\n \"characteristic_id\": null\n },\n {\n \"ingredient_id\": \"d0402a2e-5804-487d-b860-b3200482ad9e\",\n \"amount\": 1.0,\n \"unit_id\": \"7be4e87a-2957-43c9-9efb-ab7947c25281\",\n \"additional_information_id\": null,\n \"characteristic_id\": null\n },\n {\n \"ingredient_id\": \"99e187a9-bbbc-4b95-8809-3916f97398e8\",\n \"amount\": 0.5,\n \"unit_id\": \"81939ac3-6943-4be2-9842-e9ca99fd831d\",\n \"additional_information_id\": null,\n \"characteristic_id\": null\n },\n {\n \"ingredient_id\": \"f084f606-b16b-44bb-bc44-973a63af0670\",\n \"amount\": 4.0,\n \"unit_id\": \"44191cfe-a2dd-4e11-89a6-1594fce3731d\",\n \"additional_information_id\": \"7bb5693f-c4ea-42b1-857d-b7baad5888ea\",\n \"characteristic_id\": null\n },\n {\n \"ingredient_id\": \"7f91c6b3-b748-4e42-afeb-06ea90d23a29\",\n \"amount\": 1.0,\n \"unit_id\": \"44191cfe-a2dd-4e11-89a6-1594fce3731d\",\n \"additional_information_id\": \"7bb5693f-c4ea-42b1-857d-b7baad5888ea\",\n \"characteristic_id\": \"e878c5d3-99c1-4703-b623-fddf9b69da5f\"\n },\n {\n \"ingredient_id\": \"f35a951b-f320-43a1-94de-66582e547e2f\",\n \"amount\": 1.0,\n \"unit_id\": \"7818cfdb-c946-4ff8-99f8-1bea2f024aee\",\n \"additional_information_id\": null,\n \"characteristic_id\": null\n }\n ],\n \"steps\": [{\n \"description\": \"grate garlic into frying pan with cooking oil, stir until light brown\",\n \"image_id\": \"10d50b09-9868-4a90-9da9-98f92d270a62\",\n \"video_id\": null,\n \"selected_ingredient_indices\": [3, 6],\n \"utensils\": [{\n \"utensil_id\": \"a2dd43a1-643c-4e7f-9502-4eccfd384edb\"\n }]\n },\n {\n \"description\": \"add tomato sauce to pan. let this cook for a bit\",\n \"image_id\": \"af0fa325-612e-4459-8960-16915cad3c2f\",\n \"video_id\": null,\n \"selected_ingredient_indices\": [1],\n \"utensils\": []\n },\n {\n \"description\": \"add chilli oil paste\",\n \"image_id\": \"e9d9f2ae-acf7-49cc-b26d-2804e9017047\",\n \"video_id\": null,\n \"selected_ingredient_indices\": [2],\n \"utensils\": []\n },\n {\n \"description\": \"add the corn chips, mix together in pan.\",\n \"image_id\": \"74f593ab-7d28-448d-9dd4-847ef9b4dbad\",\n \"video_id\": null,\n \"selected_ingredient_indices\": [0],\n \"utensils\": []\n },\n {\n \"description\": \"add cheese and onion as garnish\",\n \"image_id\": \"9bbf5576-9282-47b6-a3f4-54e8fd9ac92d\",\n \"video_id\": null,\n \"selected_ingredient_indices\": [4, 5],\n \"utensils\": []\n }\n ]\n}\n```\n</details>\n"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/recipe_add_json'
responses:
'200':
description: Operation successfull
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/form_id_response'
'403':
description: Forbidden. When user is not logged in
'404':
description: NotFound. When User Recipe does not exists
/users/me/recipes/{uuid}/:
get:
summary: Details of given Private Recipe
operationId: users-me-recipe-detail
tags:
- User Private Recipes
parameters:
- name: uuid
in: path
description: Private Recipe uuid
required: true
schema:
type: string
format: uuid
- name: simplified
in: query
description: Get simplified recipe schema
schema:
type: boolean
responses:
'200':
description: Get Recipe with the specified uuid
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/recipe'
'404':
description: User Recipe not found
put:
summary: Update the given Private Recipe
operationId: user-recipe-update
tags:
- User Private Recipes
parameters:
- name: uuid
in: path
description: Recipe uuid
required: true
schema:
type: string
format: uuid
requestBody:
description: see [POST](#/UserPrivateRecipes/user-recipe-create) endpoint documentation for detailed description of using this endpoint
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/recipe_add_json'
responses:
'200':
description: Operation successfull
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/form_response'
'403':
description: Forbidden. When user is not logged in
'404':
description: NotFound. When User Recipe does not exists
delete:
summary: Delete a Private Recipe
operationId: users-me-delete-recipe
tags:
- User Private Recipes
parameters:
- name: uuid
in: path
description: id of the recipe
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Operation successfull
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/form_response'
'403':
description: Forbidden. When user is not logged in
'404':
description: NotFound. When User Recipe does not exists
/users/me/recipes/{uuid}/submit/:
post:
summary: Submits the given Private Recipe to UGC review.
operationId: user-recipe-submit
tags:
- User Private Recipes
parameters:
- name: uuid
in: path
description: id of the recipe
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Operation successfull
content:
application/vnd.ajns.kitchenstories+json; version=3:
schema:
$ref: '#/components/schemas/form_id_response'
'403':
description: Forbidden. When user is not logged in
'404':
description: NotFound. When User Recipe does not exists
components:
schemas:
legacy_unit:
type: object
properties:
id:
type: string
ingredient_pluralizable:
type: boolean
name:
type: object
properties:
rendered:
type: string
one:
type: string
many:
type: string
required:
- rendered
additionalProperties: false
required:
- name
category_simplified:
type: object
properties:
id:
type: string
title:
type: string
slug:
type: string
path:
type: array
items:
$ref: '#/components/schemas/path_item'
children:
type: array
items:
$ref: '#/components/schemas/child_item'
required:
- slug
- title
- id
links:
type: object
properties:
first:
type: string
format: uri
last:
type: string
format: uri
next:
type: string
format: uri
prev:
type: string
format: uri
required:
- last
- first
additionalProperties: false
content_meta_markdown:
type: object
properties:
markdown:
type: string
minLength: 1
maxLength: 5000
required:
- markdown
step:
type: object
properties:
headline:
type: string
text:
type: string
tip:
type: object
properties:
title:
type: string
description:
type: string
video:
$ref: '#/components/schemas/video'
required:
- description
- title
image:
$ref: '#/components/schemas/image'
video:
$ref: '#/components/schemas/video'
utensils:
type: array
items:
$ref: '#/components/schemas/recipe_utensil'
ingredients:
type: array
items:
$ref: '#/components/schemas/recipe_ingredient'
required:
- text
additional_information:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
characteristic:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
size:
type: object
properties:
id:
type: string
name:
type: string
metric:
type: string
imperial:
type: string
required:
- id
additionalProperties: false
unit:
type: object
properties:
id:
type: string
type:
type: string
featured_order:
type: number
ingredient_pluralizable:
type: boolean
name:
type: object
properties:
one:
type: string
many:
type: string
rendered:
type: string
required:
- rendered
additionalProperties: false
required:
- id
- name
- ingredient_pluralizable
- type
image:
type: object
properties:
id:
oneOf:
- type: string
- type: number
url:
type: string
format: uri
source:
type: string
source_link:
type: string
width:
type: number
height:
type: number
required:
- url
additionalProperties: false
form_response:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
recipe_utensil:
type: object
properties:
id:
type: string
amount:
type: number
name:
type: object
properties:
rendered:
type: string
one:
type: string
many:
type: string
required:
- rendered
additionalProperties: false
characteristic:
$ref: '#/components/schemas/characteristic'
additional_information:
$ref: '#/components/schemas/additional_information'
size:
$ref: '#/components/schemas/size'
required:
- name
comment_image:
type: object
properties:
comment:
type: string
author:
$ref: '#/components/schemas/user_public'
original_location:
type: string
image:
$ref: '#/components/schemas/image'
created:
type: string
format: date-time
required:
- author
- created
- image
- original_location
- comment
user_recipe_ingredient:
type: object
properties:
name:
type: string
nullable: true
ingredient_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
amount:
type: number
nullable: true
unit_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
additional_information_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
characteristic_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
meta:
type: object
properties:
pagination:
type: object
properties:
pages:
type: number
count:
type: number
page:
type: number
required:
- page
- pages
- count
additionalProperties: false
required:
- pagination
additionalProperties: false
content_meta_faq:
type: object
properties:
question:
type: string
minLength: 1
maxLength: 500
answer:
type: string
minLength: 1
maxLength: 5000
required:
- answer
- question
child_item:
type: object
properties:
id:
type: string
title:
type: string
path:
type: array
items:
$ref: '#/components/schemas/path_item'
slug:
type: string
children:
type: array
items:
$ref: '#/components/schemas/child_item'
required:
- id
- slug
- title
recipe_pagination:
type: object
properties:
links:
$ref: '#/components/schemas/links'
meta:
$ref: '#/components/schemas/meta'
data:
type: array
items:
$ref: '#/components/schemas/recipe'
required:
- data
- links
- meta
form_id_response:
type: object
properties:
errors:
type: array
items:
type: string
id:
type: string
required:
- id
- errors
video:
type: object
properties:
id:
type: string
title:
type: string
slug:
type: string
type:
type: string
content_id:
type: string
remote_id:
type: string
url:
type: string
format: uri
recipe_url:
type: string
format: uri
width:
type: number
height:
type: number
duration:
type: number
image:
$ref: '#/components/schemas/image'
meta:
$ref: '#/components/schemas/wagtail_meta'
publishing:
type: object
properties:
created:
type: string
format: date-time
updated:
type: string
format: date-time
published:
type: string
format: date-time
state:
type: string
playback-state:
type: string
enum:
- not-playable
- processing
- ready
required:
- created
- updated
- state
- playback-state
user_reactions:
type: object
properties:
view_count:
type: number
required:
- view_count
required:
- content_id
- duration
- title
- id
- slug
- meta
recipe_ingredient:
type: object
properties:
id:
type: string
name:
type: object
properties:
rendered:
type: string
one:
type: string
many:
type: string
required:
- rendered
additionalProperties: false
measurement:
type: object
properties:
imperial:
type: object
properties:
amount:
type: number
unit:
oneOf:
- $ref: '#/components/schemas/legacy_unit'
- $ref: '#/components/schemas/unit'
additionalProperties: false
metric:
type: object
properties:
amount:
type: number
unit:
oneOf:
- $ref: '#/components/schemas/legacy_unit'
- $ref: '#/components/schemas/unit'
additionalProperties: false
additionalProperties: false
characteristic:
$ref: '#/components/schemas/characteristic'
additional_information:
$ref: '#/components/schemas/additional_information'
is_divided:
type: boolean
is_partner:
type: boolean
is_searcheable:
type: boolean
url:
type: string
required:
- name
user_public:
type: object
properties:
id:
type: string
type:
type: string
enum:
- community
- contributor
- editor
new_type:
type: string
enum:
- community
- contributor
- editor
- partner
- external
name:
type: string
slug:
type: string
occupation:
type: string
description:
type: string
image:
$ref: '#/components/schemas/image'
nullable: true
banner_image:
$ref: '#/components/schemas/image'
wide_banner_image:
$ref: '#/components/schemas/image'
website:
type: string
format: uri
is_premium:
type: boolean
created:
type: string
format: date-time
required:
- type
- new_type
- name
- id
wagtail_meta:
type: object
properties:
title:
type: string
description:
type: string
hreflang:
type: object
properties:
en:
type: string
format: uri
de:
type: string
format: uri
zh:
type: string
format: uri
required:
- en
required:
- hreflang
additionalProperties: false
user_recipe_utensil:
type: object
properties:
name:
type: string
nullable: true
utensil_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
amount:
type: number
nullable: true
utensil_size_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
additional_information_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
characteristic_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
content_meta_external_product:
type: object
properties:
title:
type: string
minLength: 1
maxLength: 37
subtitle:
type: string
maxLength: 25
image:
type: string
format: uri
cta:
type: string
maxLength: 20
url:
type: string
format: uri
required:
- image
- url
- title
content_meta:
type: object
properties:
key:
type: string
type:
type: string
value:
oneOf:
- $ref: '#/components/schemas/content_meta_external_link'
- $ref: '#/components/schemas/content_meta_external_product'
- $ref: '#/components/schemas/content_meta_faq'
- $ref: '#/components/schemas/content_meta_markdown'
campaign:
type: string
language:
type: string
required:
- type
- key
- uuid
tag:
type: object
properties:
id:
type: string
title:
type: string
slug:
type: string
type:
type: string
is_hidden:
type: boolean
recipe:
type: object
properties:
id:
type: string
title:
type: string
slug:
type: string
type:
type: string
content_id:
type: string
difficulty:
type: string
chefs_note:
type: string
image:
$ref: '#/components/schemas/image'
nullable: true
author:
$ref: '#/components/schemas/user_public'
url:
type: string
format: uri
duration:
type: object
properties:
preparation:
type: number
baking:
type: number
resting:
type: number
required:
- preparation
- resting
- baking
nullable: true
user_reactions:
type: object
properties:
rating:
type: number
rating_count:
type: number
images:
type: array
items:
$ref: '#/components/schemas/comment_image'
maxItems: 4
comments_count:
type: number
images_count:
type: number
like_count:
type: number
quality:
type: number
required:
- comments_count
- images_count
- like_count
- quality
servings:
type: object
properties:
amount:
type: number
type:
type: string
required:
- amount
- type
nutrition:
type: object
properties:
calories:
type: number
fat:
type: number
protein:
type: number
carbohydrate:
type: number
required:
- protein
- fat
- calories
- carbohydrate
publishing:
type: object
properties:
created:
type: string
format: date-time
updated:
type: string
format: date-time
published:
type: string
format: date-time
state:
type: string
enum:
- draft
- submitted
- rejected
- live
- expired
- scheduled
required:
- created
- updated
- state
meta:
$ref: '#/components/schemas/wagtail_meta'
tags:
type: array
items:
$ref: '#/components/schemas/tag'
content_meta:
type: array
items:
$ref: '#/components/schemas/content_meta'
categories:
type: object
properties:
main:
$ref: '#/components/schemas/category_simplified'
additional:
type: array
items:
$ref: '#/components/schemas/category_simplified'
video:
$ref: '#/components/schemas/video'
howto_videos:
type: array
items:
$ref: '#/components/schemas/video'
steps:
type: array
items:
$ref: '#/components/schemas/step'
utensils:
type: array
items:
$ref: '#/components/schemas/recipe_utensil'
ingredients:
type: array
items:
type: object
properties:
list:
type: array
items:
$ref: '#/components/schemas/recipe_ingredient'
required:
- list
additionalProperties: false
required:
- content_id
- type
- publishing
- title
- steps
- slug
- url
- user_reactions
- author
- servings
- ingredients
- id
recipe_add_json:
type: object
properties:
title:
type: string
image_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
difficulty:
type: string
enum:
- easy
- medium
- hard
preparation_time:
type: number
nullable: true
resting_time:
type: number
nullable: true
baking_time:
type: number
nullable: true
chefs_note:
type: string
nullable: true
ingredients:
type: array
items:
$ref: '#/components/schemas/user_recipe_ingredient'
steps:
type: array
items:
$ref: '#/components/schemas/user_recipe_step'
tags:
type: array
items:
type: string
servings:
type: object
properties:
amount:
type: number
type:
type: string
enum:
- portion
- piece
required:
- amount
- type
additionalProperties: false
required:
- difficulty
- servings
- title
content_meta_external_link:
type: object
properties:
url:
type: string
format: uri
required:
- url
user_recipe_step:
type: object
properties:
description:
type: string
nullable: true
image_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
video_id:
oneOf:
- type: string
pattern: '[0-9a-f-]{36}'
- type: string
pattern: ^$
- nullable: true
selected_ingredient_indices:
type: array
items:
type: number
utensils:
type: array
items:
$ref: '#/components/schemas/user_recipe_utensil'
required:
- description
path_item:
type: object
properties:
id:
type: string
title:
type: string
slug:
type: string
required:
- id
- slug
- title
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
ApiKeyAuth:
type: apiKey
in: header
name: X-Ultron-User