tinyplates-dev Shopping List API

openapi: 3.2.0
info:
  title: Tiny Plates Shopping List 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: shoppingList
paths:
  /shopping-list:
    get:
      tags:
      - shoppingList
      operationId: shoppingList.build
      parameters:
      - name: recipes
        in: query
        schema:
          type: string
        required: true
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - recipes
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShoppingItem'
                  recipes:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - servings
                      - title
                      properties:
                        id:
                          type: string
                        servings:
                          type: number
                        title:
                          type: string
                      additionalProperties: false
                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: 'One shopping list for several recipes. `recipes` is a comma-separated list of recipe ids, each optionally followed by a colon and the servings to cook — `66d0a1b2c3d4e5f6a7b8c9d0:6,66d0a1b2c3d4e5f6a7b8c9d1`. Quantities are scaled to those servings and then added up wherever they can be: grams to grams, cloves to cloves. Amounts that cannot be added, such as two cloves of garlic and 10 g of garlic, stay separate lines.'
      summary: Consolidate several recipes into one list, grouped by aisle
components:
  schemas:
    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
    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
    DailyLimitReachedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      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
    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
    InvalidParameterError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    ShoppingItem:
      type: object
      required:
      - category
      - display
      - name
      - recipeIds
      properties:
        category:
          type: string
          enum:
          - bakery
          - dairy
          - drinks
          - frozen
          - meat
          - other
          - pantry
          - produce
          - seafood
          - spices
          description: The aisle to find it in.
        display:
          type: string
          description: The line as a reader would write it, such as "6 onion".
        extras:
          type: array
          items:
            $ref: '#/components/schemas/Quantity'
          description: 'Amounts a recipe asked for in a unit this line''s own cannot take, one per unit: "1 cup" with a note of "plus 3 tbsp" is "1 cup + 3 tbsp". Buy them as well as the quantity.'
        name:
          type: string
        plusMore:
          type: boolean
          description: A recipe also asked for this without saying how much — oil for frying, a garnish — so the quantity is a minimum rather than the whole of it.
        quantity:
          $ref: '#/components/schemas/Quantity'
        recipeIds:
          type: array
          items:
            type: string
          description: The recipes that asked for it.
      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
    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
    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
    NonNegative:
      type: number
      description: a non-negative number
      title: nonNegative
      minimum: 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
    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
    WeeklyLimitReachedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          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
    Quantity:
      type: object
      required:
      - value
      properties:
        max:
          $ref: '#/components/schemas/NonNegative'
        unit:
          $ref: '#/components/schemas/Unit'
        value:
          $ref: '#/components/schemas/NonNegative'
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http