Read an ingredient line

POST

/api/v1/ingredient-lines/parse

curl --request POST \
  --url http://127.0.0.1:8080/api/v1/ingredient-lines/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "convention": "metric", "language": "example", "source_locale": "example", "text": "example" }'

• A local instance on its default listener.

Reads one typed ingredient line into an amount, unit, name, and note using the unit words of the line’s language. Nothing is stored. The result is the reading an import would make, so a line typed in the editor and the same line imported are read alike.

Authorizations

• bearerToken
• browserSession

Request Body^required

Media typeapplication/json

object

convention

An explicit author choice for every applicable unqualified measure of this submitted ingredient line. It outranks source-locale lookup and preserves explicit unit definitions. Omit it when unspecified

string

Allowed values: metric us au imperial

language

BCP 47 tag of the language the line is written in. Its primary language selects unit words and reading order; its region does not establish a measuring convention

string

<= 35 characters

source_locale

BCP 47 tag of the locale the recipe declares. It takes the place of language when the two are sent

string

<= 35 characters

text

required

One ingredient line as a person writes it, such as 2 cups flour, sifted or 小麦粉 200g

string

>= 1 characters <= 10000 characters

Responses

200

OK

Media typeapplication/json

object

ingredient

required

The line read as an ingredient. Its normalization method is extracted when an amount was read and unresolved when the line named a measure that could not be identified safely. A line with no amount is returned as a name

object

alternatives

Array<object> recursive| null

id

required

string

/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/

name

string

>= 1 characters <= 1000 characters

normalization

object

method

required

string

Allowed values: authored extracted inferred unresolved

review

string

Allowed values: confirmed corrected

warnings

Array<string> | null

<= 100 items

note

string

<= 1000000 characters

optional

The author sanctioned leaving this occurrence out. It belongs to the occurrence, never to the ingredient: the same thing may be optional in a garnish section and required by the method

boolean

package_size

object

amount

required

object

approximate

boolean

max

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

kind

required

string

Allowed values: simple

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

quantity

object

amount

object

approximate

boolean

max

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

kind

required

string

Allowed values: simple sum alternatives opaque

options

Array<object> | null

<= 100 items

object

amount

object

approximate

boolean

max

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

kind

required

string

Allowed values: simple sum

terms

Array<object> | null

<= 100 items

object

amount

required

object

approximate

boolean

max

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

kind

required

string

Allowed values: simple

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

terms

Array<object> | null

<= 100 items

object

amount

required

object

approximate

boolean

max

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

kind

required

string

Allowed values: simple

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

text

string

<= 1000 characters

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

recipe

The recipe that makes this ingredient, as the source identified it. Its content is not included

object

recipe_id

The other recipe’s portable document ID, not a library entry ID

string

/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/

title

The other recipe’s title as authored

string

<= 1000 characters

url

Where the other recipe is published

string format: uri

<= 10000 characters

relation

string

Allowed values: or and_or preferred

source_text

string

<= 1000000 characters

temperature

object

amount

object

approximate

boolean

max

string

<= 128 characters /^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

min

string

<= 128 characters /^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

value

string

<= 128 characters /^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

note

string

<= 1000 characters

purpose

object

kind

required

string

Allowed values: oven internal oil water surface other

label

string

<= 1000 characters

source_text

string

<= 1000 characters

text

string

<= 1000 characters

unit

string

<= 255 characters /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/

key

additional properties

any

Example

{
  "ingredient": {
    "normalization": {
      "method": "authored",
      "review": "confirmed"
    },
    "package_size": {
      "kind": "simple"
    },
    "quantity": {
      "kind": "simple",
      "options": [
        {
          "kind": "simple",
          "terms": [
            {
              "kind": "simple"
            }
          ]
        }
      ],
      "terms": [
        {
          "kind": "simple"
        }
      ]
    },
    "relation": "or",
    "temperature": {
      "purpose": {
        "kind": "oven"
      }
    }
  }
}

401

No valid session or API token (authentication-required), or the credential sent is invalid (invalid-credentials).

Media typeapplication/problem+json

object

code

required

string

detail

required

string

status

required

integer format: int64

title

required

string

type

required

string

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

default

Error

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}