tinyplates-dev Substitutions API

openapi: 3.2.0
info:
  title: Tiny Plates Substitutions 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: substitutions
paths:
  /substitutions:
    get:
      tags:
      - substitutions
      operationId: substitutions.list
      parameters:
      - name: ingredients
        in: query
        schema:
          type: string
        required: true
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - substitutions
                - unknown
                properties:
                  substitutions:
                    type: array
                    items:
                      type: object
                      required:
                      - ingredient
                      - options
                      properties:
                        ingredient:
                          type: string
                        options:
                          type: array
                          items:
                            $ref: '#/components/schemas/Substitution'
                      additionalProperties: false
                  unknown:
                    type: array
                    items:
                      type: string
                    description: The ingredients asked about that nothing is known to substitute for. Nothing is suggested for them, rather than something plausible that would not work.
                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 to use instead of an ingredient. `ingredients` is a comma-separated list of ingredient names or canonical ids. Each option says how much to use for one unit of the original, how to handle it, and what it cannot be used for. Ingredients nothing is known to substitute for come back in `unknown` rather than with a plausible guess.
      summary: What to use instead, in what amount, and when not to
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
    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
    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
    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
    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
    WeeklyLimitReachedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    Substitution:
      type: object
      required:
      - ingredient
      - ratio
      properties:
        caution:
          type: string
          description: What this swap cannot be used for. Present when the substitute changes the dish in a way the cook has to know about.
        ingredient:
          type: string
        note:
          type: string
          description: How to prepare or handle the substitute.
        ratio:
          type: number
          description: 'How much substitute to use for one unit of the original: 0.75 means three quarters as much.'
      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
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http