tinyplates-dev Pantry API

openapi: 3.2.0
info:
  title: Tiny Plates Pantry API
  version: 2.0.0
  description: 'Read API for the recipe database. Recipes are scraped from the web, then normalized into a canonical model with structured ingredients, numbered steps, times in seconds, servings, nutrition, media and classification.


    Documentation: https://www.tinyplates.dev/docs, where a signed-in reader can run any endpoint against this API. Create a key at https://www.tinyplates.dev.


    Authentication: an API key is required. Send it as an Authorization: Bearer header. Each account may make 50 requests a day and 300 a week, counted across all of its keys.'
servers:
- description: Production.
  url: https://api.tinyplates.dev
- description: Local development.
  url: http://localhost:6891
security:
- BearerAuth: []
tags:
- name: pantry
paths:
  /pantry:
    get:
      tags:
      - pantry
      operationId: pantry.list
      parameters:
      - name: ingredients
        in: query
        schema:
          type: string
        required: true
      - name: language
        in: query
        schema:
          type: string
        required: false
      - name: limit
        in: query
        schema:
          type: string
        required: false
      - name: maxMissing
        in: query
        schema:
          type: string
        required: false
      - name: offset
        in: query
        schema:
          type: string
        required: false
      - name: staples
        in: query
        schema:
          type: string
        required: false
      - name: without
        in: query
        schema:
          type: string
        required: false
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - pagination
                - recipes
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  recipes:
                    type: array
                    items:
                      $ref: '#/components/schemas/PantryRecipe'
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/HttpApiDecodeError'
                - $ref: '#/components/schemas/InvalidParameterError'
        '401':
          description: ApiKeyDisabledError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ApiKeyDisabledError'
                - $ref: '#/components/schemas/ApiKeyExpiredError'
                - $ref: '#/components/schemas/ApiKeyRequiredError'
                - $ref: '#/components/schemas/InvalidApiKeyError'
        '429':
          description: DailyAllowanceExceededError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/DailyAllowanceExceededError'
                - $ref: '#/components/schemas/DailyLimitReachedError'
                - $ref: '#/components/schemas/WeeklyAllowanceExceededError'
                - $ref: '#/components/schemas/WeeklyLimitReachedError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      description: 'What you can cook from what you have. `ingredients` is the pantry: 1 to 20 comma-separated ingredient names or canonical ids. A name can be in any language the recipes are in, so "kyckling" works as well as "chicken", and a food covers its cuts and kinds: "chicken" covers chicken breast and "onion" covers red onion, but not chicken broth or onion powder. Only recipes that use at least one of them are returned, best covered first, and each carries the pantry ingredients it uses and the ingredients you are missing. Salt, pepper, water, oil, sugar and flour are taken as already in the kitchen: they are reported in `assumedIngredients` and left out of the coverage and of `missingIngredients`. Send `staples=false` to count them as ingredients you need. `maxMissing` narrows the results to recipes you are short no more than that many ingredients for — `maxMissing=0` is what you can cook right now. `without` leaves out recipes that contain any of the listed allergen features from /vocabularies, such as "milk,peanuts"; it is informational, not medical advice.'
      summary: Rank recipes by how much of them your pantry covers
components:
  schemas:
    PantryRecipe:
      type: object
      required:
      - id
      - instructions
      - language
      - media
      - times
      - title
      - categories
      - courses
      - createdAt
      - cuisines
      - groups
      - ingredients
      - tags
      - text
      - updatedAt
      - url
      - assumedIngredients
      - coverage
      - matchedIngredients
      - missingIngredients
      properties:
        id:
          type: string
        author:
          $ref: '#/components/schemas/Author'
        description:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        dietary:
          $ref: '#/components/schemas/Dietary'
        instructions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RecipeInstruction'
        language:
          $ref: '#/components/schemas/Language'
        media:
          type: array
          items:
            $ref: '#/components/schemas/RecipeMedia'
        notes:
          type: array
          items:
            $ref: '#/components/schemas/NonEmptyTrimmedString'
        nutrition:
          $ref: '#/components/schemas/Nutrition'
        rating:
          $ref: '#/components/schemas/Rating'
        servings:
          $ref: '#/components/schemas/Servings'
        times:
          $ref: '#/components/schemas/RecipeTimes'
        title:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        allergens:
          $ref: '#/components/schemas/RecipeAllergens'
        categories:
          type: array
          items:
            type: string
        courses:
          type: array
          items:
            type: string
        createdAt:
          $ref: '#/components/schemas/Date'
        cuisines:
          type: array
          items:
            type: string
        equipment:
          type: array
          items:
            type: string
        groups:
          $ref: '#/components/schemas/RecipeGroups'
        ingredients:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RecipeIngredient'
        tags:
          type: array
          items:
            type: string
        techniques:
          type: array
          items:
            type: string
        text:
          $ref: '#/components/schemas/RecipeText'
        updatedAt:
          $ref: '#/components/schemas/Date'
        url:
          type: string
        assumedIngredients:
          type: array
          items:
            type: string
          description: The staples this recipe uses — salt, pepper, water, oil, sugar, flour — taken as already in your kitchen, and so counted neither in the coverage nor as missing. Empty when "staples=false".
        coverage:
          type: number
          description: The share of this recipe's ingredients your pantry covers, from 0 to 1, rounded to two decimals. Higher comes first.
        matchedIngredients:
          type: array
          items:
            type: string
          description: The recipe ingredients your pantry covers, as the recipe names them.
        missingIngredients:
          type: array
          items:
            type: string
          description: The recipe ingredients your pantry does not cover, as the recipe names them.
      additionalProperties: false
      description: A recipe together with what your pantry covers and what it does not. Ingredient names are the recipe's own, in its own language.
    VideoMedia:
      type: object
      required:
      - id
      - role
      - type
      - url
      properties:
        alt:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        caption:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        id:
          $ref: '#/components/schemas/Trimmed'
          description: a non empty string
          title: nonEmptyString
          minLength: 1
        license:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        sourceUrl:
          $ref: '#/components/schemas/Url'
        step:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
        duration:
          $ref: '#/components/schemas/Duration'
        embedUrl:
          $ref: '#/components/schemas/Url'
        provider:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        role:
          type: string
          enum:
          - gallery
          - step
        thumbnailUrl:
          $ref: '#/components/schemas/Url'
        type:
          type: string
          enum:
          - video
        url:
          $ref: '#/components/schemas/Url'
        videoId:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
      additionalProperties: false
    ApiKeyRequiredError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - 'An API key is required. Pass it as an Authorization: Bearer header.'
          additionalProperties: false
      additionalProperties: false
    InvalidParameterError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    NonNegative:
      type: number
      description: a non-negative number
      title: nonNegative
      minimum: 0
    NonEmptyTrimmedString:
      type: string
      description: a non empty string
      title: nonEmptyString
      pattern: ^\S[\s\S]*\S$|^\S$|^$
      minLength: 1
    Dietary:
      type: object
      required: []
      properties:
        dairyFree:
          type: boolean
        glutenFree:
          type: boolean
        pescatarian:
          type: boolean
        vegan:
          type: boolean
        vegetarian:
          type: boolean
      additionalProperties: false
      description: Diet flags declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no.
    Duration:
      type: object
      required:
      - seconds
      properties:
        seconds:
          $ref: '#/components/schemas/NonNegativeInt'
      additionalProperties: false
    RecipeAllergens:
      type: object
      required:
      - celery
      - crustaceans
      - eggs
      - fish
      - gluten-cereals
      - lupin
      - milk
      - molluscs
      - mustard
      - nuts-eu
      - peanuts
      - sesame
      - soy
      - sulphites
      - tree-nuts-us
      - wheat
      - disclaimer
      properties:
        celery:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        crustaceans:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        eggs:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        fish:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        gluten-cereals:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        lupin:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        milk:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        molluscs:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        mustard:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        nuts-eu:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        peanuts:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        sesame:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        soy:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        sulphites:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        tree-nuts-us:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        wheat:
          type: boolean
          description: Whether the recipe contains this regulated allergen.
        disclaimer:
          type: string
          enum:
          - Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy.
      additionalProperties: false
    Temperature:
      type: object
      required:
      - unit
      - value
      properties:
        unit:
          type: string
          enum:
          - C
          - F
        value:
          type: number
      additionalProperties: false
    Trimmed:
      type: string
      description: a string with no leading or trailing whitespace
      title: trimmed
      pattern: ^\S[\s\S]*\S$|^\S$|^$
    Slug:
      type: string
      description: a string matching the pattern ^[a-z0-9]+(-[a-z0-9]+)*$
      pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
    Language:
      type: string
      description: a string matching the pattern ^[a-z]{2}$
      pattern: ^[a-z]{2}$
    Issue:
      type: object
      required:
      - _tag
      - path
      - message
      properties:
        _tag:
          type: string
          enum:
          - Pointer
          - Unexpected
          - Missing
          - Composite
          - Refinement
          - Transformation
          - Type
          - Forbidden
          description: The tag identifying the type of parse issue
        path:
          type: array
          items:
            $ref: '#/components/schemas/PropertyKey'
          description: The path to the property where the issue occurred
        message:
          type: string
          description: A descriptive message explaining the issue
      additionalProperties: false
      description: Represents an error encountered while parsing a value to match the schema
    Date:
      type: string
      description: a string to be decoded into a Date
    WeeklyAllowanceExceededError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - Weekly allowance of 300 requests used. It covers the last 7 days. Paid plans include more; see https://www.tinyplates.dev/pricing.
          additionalProperties: false
      additionalProperties: false
    RecipeMedia:
      anyOf:
      - $ref: '#/components/schemas/ImageMedia'
      - $ref: '#/components/schemas/VideoMedia'
    ImageVariant:
      type: object
      required:
      - url
      properties:
        height:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
        url:
          $ref: '#/components/schemas/Url'
        width:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
      additionalProperties: false
    Rating:
      type: object
      required:
      - count
      - value
      properties:
        best:
          $ref: '#/components/schemas/Positive'
        count:
          $ref: '#/components/schemas/NonNegativeInt'
        reviewCount:
          $ref: '#/components/schemas/NonNegativeInt'
        value:
          $ref: '#/components/schemas/NonNegative'
        worst:
          $ref: '#/components/schemas/NonNegative'
      additionalProperties: false
    Quantity:
      type: object
      required:
      - value
      properties:
        max:
          $ref: '#/components/schemas/NonNegative'
        unit:
          $ref: '#/components/schemas/Unit'
        value:
          $ref: '#/components/schemas/NonNegative'
      additionalProperties: false
    RecipeIngredient:
      type: object
      required:
      - display
      - name
      - optional
      - original
      properties:
        display:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        group:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        localName:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        localPreparation:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        ingredientId:
          type: string
          description: a string matching the pattern ^[a-z0-9]+(-[a-z0-9]+)*$
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
        name:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        note:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        optional:
          type: boolean
        original:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        preparation:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        quantity:
          $ref: '#/components/schemas/Quantity'
        size:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
      additionalProperties: false
    PropertyKey:
      anyOf:
      - type: string
      - type: number
      - type: object
        required:
        - _tag
        - key
        properties:
          _tag:
            type: string
            enum:
            - symbol
          key:
            type: string
        additionalProperties: false
        description: an object to be decoded into a globally shared symbol
    NonNegativeInt:
      type: integer
      description: an integer
      title: int
      minimum: 0
    Url:
      type: string
      description: a string matching the pattern ^https?:\/\/\S+$
      pattern: ^https?:\/\/\S+$
    DailyLimitReachedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    HttpApiDecodeError:
      type: object
      required:
      - issues
      - message
      - _tag
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
        message:
          type: string
        _tag:
          type: string
          enum:
          - HttpApiDecodeError
      additionalProperties: false
      description: The request did not match the expected schema
    RecipeGroups:
      type: array
      items:
        type: string
      description: The distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
    Unit:
      type: string
      enum:
      - g
      - kg
      - lb
      - oz
      - cl
      - cup
      - dl
      - fl-oz
      - gallon
      - l
      - ml
      - pint
      - quart
      - tbsp
      - tsp
      - bag
      - bottle
      - box
      - bunch
      - can
      - clove
      - cube
      - dash
      - drop
      - ear
      - handful
      - head
      - jar
      - knob
      - leaf
      - package
      - packet
      - piece
      - pinch
      - portion
      - pot
      - scoop
      - sheet
      - shot
      - slice
      - sprig
      - stalk
      - stick
      - tub
      - cm
      - inch
    RecipeInstruction:
      type: object
      required:
      - step
      - text
      properties:
        duration:
          $ref: '#/components/schemas/Duration'
        equipment:
          type: array
          items:
            $ref: '#/components/schemas/Slug'
        group:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        ingredients:
          type: array
          items:
            type: string
            description: a string matching the pattern ^[a-z0-9]+(-[a-z0-9]+)*$
            pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
        step:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
        techniques:
          type: array
          items:
            $ref: '#/components/schemas/Slug'
        temperature:
          $ref: '#/components/schemas/Temperature'
        text:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
      additionalProperties: false
    Servings:
      type: object
      required:
      - original
      properties:
        max:
          $ref: '#/components/schemas/Positive'
        original:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        quantity:
          $ref: '#/components/schemas/Positive'
        unit:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
      additionalProperties: false
    WeeklyLimitReachedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    ApiKeyDisabledError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - This API key has been disabled.
          additionalProperties: false
      additionalProperties: false
    Positive:
      type: number
      description: a positive number
      title: positive
      exclusiveMinimum: 0
    DailyAllowanceExceededError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - Daily allowance of 50 requests used. It resets at midnight UTC. Paid plans include more; see https://www.tinyplates.dev/pricing.
          additionalProperties: false
      additionalProperties: false
    ApiKeyExpiredError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - This API key has expired.
          additionalProperties: false
      additionalProperties: false
    NutrientValue:
      type: object
      required:
      - unit
      - value
      properties:
        unit:
          $ref: '#/components/schemas/NutrientUnit'
        value:
          $ref: '#/components/schemas/NonNegative'
      additionalProperties: false
    NutrientUnit:
      type: string
      enum:
      - IU
      - g
      - kcal
      - mg
      - µg
    RecipeText:
      type: object
      required:
      - ingredients
      - instructions
      properties:
        ingredients:
          type: array
          items:
            type: string
        instructions:
          type: array
          items:
            type: string
      additionalProperties: false
      description: 'The recipe as lines of text: each ingredient''s `display` line and each step''s `text`, in order. A convenience for rendering; everything here is also in the structured fields.'
    ImageMedia:
      type: object
      required:
      - id
      - role
      - type
      - url
      properties:
        alt:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        caption:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        id:
          $ref: '#/components/schemas/Trimmed'
          description: a non empty string
          title: nonEmptyString
          minLength: 1
        license:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        sourceUrl:
          $ref: '#/components/schemas/Url'
        step:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
        height:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
        role:
          type: string
          enum:
          - gallery
          - hero
          - step
          - thumbnail
        type:
          type: string
          enum:
          - image
        url:
          $ref: '#/components/schemas/Url'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/ImageVariant'
        width:
          type: integer
          description: a positive number
          title: positive
          exclusiveMinimum: 0
      additionalProperties: false
    RecipeTimes:
      type: object
      required: []
      properties:
        cook:
          $ref: '#/components/schemas/Duration'
        inactive:
          $ref: '#/components/schemas/Duration'
        prep:
          $ref: '#/components/schemas/Duration'
        total:
          $ref: '#/components/schemas/Duration'
      additionalProperties: false
    InternalError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - Something went wrong. Please try again.
          additionalProperties: false
      additionalProperties: false
    InvalidApiKeyError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - Invalid API key.
          additionalProperties: false
      additionalProperties: false
    Nutrition:
      type: object
      required:
      - basis
      - source
      properties:
        basis:
          type: object
          required:
          - type
          properties:
            description:
              $ref: '#/components/schemas/NonEmptyTrimmedString'
            servings:
              $ref: '#/components/schemas/Positive'
            type:
              type: string
              enum:
              - 100g
              - recipe
              - serving
          additionalProperties: false
        calories:
          $ref: '#/components/schemas/NutrientValue'
        carbohydrates:
          $ref: '#/components/schemas/NutrientValue'
        cholesterol:
          $ref: '#/components/schemas/NutrientValue'
        fat:
          $ref: '#/components/schemas/NutrientValue'
        fiber:
          $ref: '#/components/schemas/NutrientValue'
        micronutrients:
          type: object
          required: []
          properties: {}
          patternProperties:
            ? ''
            : $ref: '#/components/schemas/NutrientValue'
          propertyNames:
            $ref: '#/components/schemas/Slug'
        protein:
          $ref: '#/components/schemas/NutrientValue'
        saturatedFat:
          $ref: '#/components/schemas/NutrientValue'
        sodium:
          $ref: '#/components/schemas/NutrientValue'
        source:
          type: string
          enum:
          - calculated
          - provided
        sugar:
          $ref: '#/components/schemas/NutrientValue'
      additionalProperties: false
    Pagination:
      type: object
      required:
      - limit
      - offset
      - total
      properties:
        limit:
          type: number
        offset:
          type: number
        total:
          type: number
      additionalProperties: false
      description: Offset pagination. `limit` is capped at 100.
    Author:
      type: object
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        url:
          $ref: '#/components/schemas/Url'
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http