tinyplates-dev Search API

openapi: 3.2.0
info:
  title: Tiny Plates Search 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: Search
paths:
  /search:
    get:
      tags:
      - Search
      operationId: search.search
      parameters:
      - name: query
        in: query
        schema:
          type: string
        required: true
      - name: fields
        in: query
        schema:
          type: string
        required: false
      - name: language
        in: query
        schema:
          type: string
        required: false
      - name: limit
        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:
                - results
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/HttpApiDecodeError'
                - $ref: '#/components/schemas/SearchQueryRequiredError'
                - $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: Search recipes by name, ingredients and description. Matches on meaning as well as wording, so a search for "creamy pasta" also finds carbonara. Use the "fields" parameter to return only the fields you need.
      summary: Search search
      x-summary-source: derived
components:
  schemas:
    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
    SearchQueryRequiredError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              enum:
              - The query parameter is required.
          additionalProperties: false
      additionalProperties: false
    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
    SearchResult:
      type: object
      required:
      - id
      - score
      properties:
        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
        id:
          type: string
        score:
          type: number
          description: 'A rank fusion of the meaning and the wording legs of the search, plus a bonus for a title that contains the query. Higher comes first. It is a rank, not a confidence: scores are comparable only within one response.'
      additionalProperties: false
      description: A matching recipe and its relevance score. When the "fields" query parameter is used, only the requested fields and "id" are present.
    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
    NonNegativeInt:
      type: integer
      description: an integer
      title: int
      minimum: 0
    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
    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
    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.
    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
    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
    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
    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
    Author:
      type: object
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/NonEmptyTrimmedString'
        url:
          $ref: '#/components/schemas/Url'
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http