Forklet Search Explore

Forklet API

Recipes in grams that scale. Public recipes, profiles and search can be read without signing in; everything else needs a personal API token (Settings, API) sent as "Authorization: Bearer fk_...". A read token cannot change anything. Amounts in documents are decimal strings, never floats. Errors are { "error": { "code", "message", "field" } }.

Getting Started

Everything is under https://forklet.co/api/v1. Reading a public recipe needs nothing:

curl https://forklet.co/api/v1/recipes/SHORT_ID?servings=6&units=grams

For your own recipes and lists, make a token in Settings, API and send it with every request:

curl -H "Authorization: Bearer fk_…" https://forklet.co/api/v1/shopping-lists

How It Behaves

  • Limits. 1000 requests an hour per token, 300 per address without one. Every answer says how many are left in X-RateLimit-Remaining; after the limit it is 429 with Retry-After.
  • Pages. Lists take limit (up to 100) and return next_cursor; send it back as cursor for the next page.
  • Drafts. Reading a draft gives its revision (also the ETag); changes must send it as If-Match, so two editors never overwrite each other.
  • Errors. { "error": { "code", "message", "field" } } with the matching status; the message is written for people.
  • Amounts. Documents keep amounts as decimal strings, never floats. The recipe format is described as a JSON Schema: forklet-1.json.

The whole API as OpenAPI 3.1: openapi.json.

Endpoints

POST /recipes

Create a private draft. Needs a token (or the site’s own sign in).

Send { title } for an empty recipe, or { doc } with a Forklet document.

GET /recipes/{id}

A recipe with its current published version.

Add a scale or units to get it computed on the server as well. The owner can add draft=1 for the draft.

  • id path, required · The recipe’s short id (8 letters and digits).
  • scale query · Multiply everything (2 = double).
  • servings query · Scale to this many servings.
  • base query · Scale so the base weighs this many grams.
  • pieces query · Scale to this many pieces (with piece_g, of this size).
  • mass_g query · Scale to this finished weight in grams.
  • volume_ml query · Scale to this finished volume in ml.
  • pan query · Scale to a pan: round:260 or rect:200x300 (mm).
  • units query · How amounts are shown.
  • variant query · A variant key of the recipe.
  • draft query

GET /recipes/{id}/versions/{n}

One published version.

  • id path, required · The recipe’s short id (8 letters and digits).
  • n path, required
  • scale query · Multiply everything (2 = double).
  • servings query · Scale to this many servings.
  • base query · Scale so the base weighs this many grams.
  • pieces query · Scale to this many pieces (with piece_g, of this size).
  • mass_g query · Scale to this finished weight in grams.
  • volume_ml query · Scale to this finished volume in ml.
  • pan query · Scale to a pan: round:260 or rect:200x300 (mm).
  • units query · How amounts are shown.
  • variant query · A variant key of the recipe.

GET /recipes/{id}/resolved

The fully expanded recipe.

Included recipes pulled in and every amount computed at the scale asked for.

  • id path, required · The recipe’s short id (8 letters and digits).
  • scale query · Multiply everything (2 = double).
  • servings query · Scale to this many servings.
  • base query · Scale so the base weighs this many grams.
  • pieces query · Scale to this many pieces (with piece_g, of this size).
  • mass_g query · Scale to this finished weight in grams.
  • volume_ml query · Scale to this finished volume in ml.
  • pan query · Scale to a pan: round:260 or rect:200x300 (mm).
  • units query · How amounts are shown.
  • variant query · A variant key of the recipe.

GET /recipes/{id}/draft

Your draft and its revision. Needs a token (or the site’s own sign in).

  • id path, required · The recipe’s short id (8 letters and digits).

PUT /recipes/{id}/draft

Replace your draft. Needs a token (or the site’s own sign in).

  • id path, required · The recipe’s short id (8 letters and digits).

PATCH /recipes/{id}/draft

Change part of your draft. Needs a token (or the site’s own sign in).

A JSON merge patch (RFC 7396) on the Forklet document. If-Match must be the current revision.

  • id path, required · The recipe’s short id (8 letters and digits).

POST /recipes/{id}/make-or-buy

Remember whether you make or buy a referenced recipe. Needs a token (or the site’s own sign in).

  • id path, required · The recipe’s short id (8 letters and digits).

GET /recipes/{id}/catalogs

Your catalogs, each saying whether it holds this recipe. Needs a token (or the site’s own sign in).

  • id path, required · The recipe’s short id (8 letters and digits).

POST /recipes/{id}/publish

Publish your draft, or change how it is shared. Needs a token (or the site’s own sign in).

The same rules as the publish page: checks, a hero photo for public, forks follow their original’s license, imports need rights: true.

  • id path, required · The recipe’s short id (8 letters and digits).

POST /recipes/{id}/fork

Fork a recipe. Needs a token (or the site’s own sign in).

A private credited copy; its license decides how the fork can be shared later.

  • id path, required · The recipe’s short id (8 letters and digits).

POST /import/url

Import from a recipe page. Needs a token (or the site’s own sign in).

Reads schema.org Recipe data (JSON-LD or microdata). The result is a private draft credited to the page.

POST /import/text

Parse pasted text. Needs a token (or the site’s own sign in).

Nothing is saved: the document it becomes and the lines to check.

GET /search

Search public recipes.

  • q query
  • inc query · Ingredient slugs to include, comma separated.
  • exc query · Ingredient slugs to leave out.
  • time query · At most this many minutes.
  • diet query
  • free query · Allergens to avoid, comma separated.
  • sort query
  • limit query · Items per page, 1 to 100.
  • cursor query · The next_cursor of the previous page.

GET /users/{username}

A public profile.

  • username path, required

GET /ingredients

Ingredient autocomplete.

Up to 10 ingredients whose name or another name matches.

  • q query, required

POST /batches/{id}/weights

Record what you weighed for one line of a test batch (weigh log). Needs a token (or the site’s own sign in).

  • id path, required · The batch id.

POST /media

Upload a photo (JPEG, PNG, WebP, AVIF or HEIC, up to 15 MB). Needs a token (or the site’s own sign in).

  • purpose query

POST /media/video

Add a YouTube or Vimeo video by its link. Needs a token (or the site’s own sign in).

PATCH /media/{id}

Describe one of your photos: alt text, credit, focal point. Needs a token (or the site’s own sign in).

  • id path, required · The media id.

DELETE /media/{id}

Delete one of your photos. Needs a token (or the site’s own sign in).

  • id path, required · The media id.

GET /schema/forklet-1.json

The Forklet recipe format as a JSON Schema.

GET /catalogs

Your catalogs. Needs a token (or the site’s own sign in).

  • limit query · Items per page, 1 to 100.
  • cursor query · The next_cursor of the previous page.

POST /catalogs

Make a catalog. Needs a token (or the site’s own sign in).

GET /catalogs/{id}

A catalog you can see, with its recipes and catalogs.

  • id path, required · The catalog id.

PATCH /catalogs/{id}

Rename or change one of yours. Needs a token (or the site’s own sign in).

  • id path, required · The catalog id.

DELETE /catalogs/{id}

Delete one of yours. Needs a token (or the site’s own sign in).

The recipes in it are not touched.

  • id path, required · The catalog id.

PUT /catalogs/{id}/recipes/{recipe}

Add a recipe to one of your catalogs. Needs a token (or the site’s own sign in).

  • id path, required · The catalog id.
  • recipe path, required

DELETE /catalogs/{id}/recipes/{recipe}

Take a recipe out. Needs a token (or the site’s own sign in).

  • id path, required · The catalog id.
  • recipe path, required

PUT /catalogs/{id}/catalogs/{child}

Put a catalog inside one of yours. Needs a token (or the site’s own sign in).

Your own, or someone else’s public catalog.

  • id path, required · The catalog id.
  • child path, required · The catalog to put inside.

DELETE /catalogs/{id}/catalogs/{child}

Take a catalog out. Needs a token (or the site’s own sign in).

  • id path, required · The catalog id.
  • child path, required · The catalog to take out.

PATCH /catalogs/{id}/items/{item}

Move an item to a new position. Needs a token (or the site’s own sign in).

Item ids come with GET /catalogs/{id}.

  • id path, required · The catalog id.
  • item path, required · The item id.

GET /shopping-lists

Your lists (and your household’s shared ones). Needs a token (or the site’s own sign in).

  • limit query · Items per page, 1 to 100.
  • cursor query · The next_cursor of the previous page.

POST /shopping-lists

Make a list. Needs a token (or the site’s own sign in).

GET /shopping-lists/{id}

A list with its items and the recipes behind them. Needs a token (or the site’s own sign in).

  • id path, required · The list id.

PATCH /shopping-lists/{id}

Rename a list. Needs a token (or the site’s own sign in).

  • id path, required · The list id.

DELETE /shopping-lists/{id}

Delete a list. Needs a token (or the site’s own sign in).

  • id path, required · The list id.

POST /shopping-lists/{id}/recipes

Add a recipe at a scale. Needs a token (or the site’s own sign in).

mode multiplier (value 2 = double), servings or base (grams, with component); make_or_buy chooses for referenced recipes by line key.

  • id path, required · The list id.

PATCH /shopping-lists/{id}/items/{item}

Set an item’s state. Needs a token (or the site’s own sign in).

  • id path, required · The list id.
  • item path, required

GET /pantry

Your pantry staples. Needs a token (or the site’s own sign in).

PATCH /pantry

Add or remove staples. Needs a token (or the site’s own sign in).

By ingredient name or slug; unknown names are reported, never guessed.