Recipes API

Search and sort community plugins.

Quickstart

Execute a search at https://trmnl.com/recipes, then append JSON to the URL.

# search for "weather"
https://trmnl.com/recipes?search=weather&sort-by=newest

# in JSON format
https://trmnl.com/recipes.json?search=weather&sort-by=newest

List Recipes

GET /recipes.json

Returns published recipes only. Unlisted recipes stay out of the list, but you can still fetch one by ID (below).

Need more than read access -- recipe markup, or installing a recipe on your account? Use the authenticated /api/recipes endpoints instead.

Example Request https://trmnl.com/recipes.json?sort-by=install

Query Params

All are optional.

Name	Type	Description
search	string	Full-text search. Partial words OK, plus small typos in the name. Ignored under 3 characters. Prefix with # to filter by category, URL-encoded as %23calendar
sort-by	string	Option by which to rank results (default newest)
user_id	integer	ID of the author, e.g. 51
per_page	integer	Results count (maximum 100, default 25)
page	integer	Page number (default 1)

Valid sort-by options:

• oldest

• newest

• popularity (installs + forks)

• fork

• install

Searches are limited to 60 requests per minute per IP address. Past that you'll get a 429.

Example Response

200

{
  "data": [{
      "id": 49610,
      "user_id": 1158,
      "name": "Weather Chum",
      "description": "Todays weather, hourly and forecast",
      "published_at": "2025-05-14T05:32:00.000Z",
      "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/ajjlbek4cabcvhk3s1lxggn8cgon",
      "icon_content_type": "image/png",
      "screenshot_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/kh7q90o1biy072d2et0u7t3qf8km",
      "author_bio": null,
      "custom_fields": [
        {
          "keyname": "user_location",
          "field_type": "string",
          "name": "Weather Location",
          "placeholder": "New York, NY",
          "description": "Choose a location",
          "help_text": "Please be precise. Examples: \u003C/br\u003E Paris, France (City/country) \u003C/br\u003E 10101 (Pass US Zipcode, UK Postcode, Canada Postal code)\u003C/br\u003E 33.7501,84.3885 (Lat/long)\u003C/br\u003E",
          "required": true
        },
        {
          "keyname": "metric",
          "name": "Temperature Metric",
          "description": "Celsius or Fahrenheit?",
          "field_type": "select",
          "options": [
            "Fahrenheit",
            "Celsius"
          ],
          "default": "Fahrenheit"
        }
      ],
      "stats": {
        "installs": 1102,
        "forks": 383
      }
  }],
  "total": 38,
  "from": 1,
  "to": 25,
  "per_page": 25,
  "current_page": 1,
  "prev_page_url": null,
  "next_page_url": "/recipes.json?page=2&per_page=25&search=weather&sort-by=popularity"
}

author_bio is the recipe's author_bio custom field, repeated at the top level for convenience (null when the recipe has none). stats counts installs + forks of the recipe.

Get a single Recipe

GET /recipes/{id}.json

Works for published + unlisted recipes. An unknown ID redirects (302) to /recipes instead of returning a 404.

Example Request https://trmnl.com/recipes/16382.json

Example Response

200

{
  "data": {
    "id": 16382,
    "user_id": 934,
    "name": "Matrix",
    "description": "The Digital Rain",
    "published_at": "2025-02-10T11:33:00.000Z",
    "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/mtpxyr22spnwjheeh5kv1p7tpk6n",
    "icon_content_type": "image/png",
    "screenshot_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/7i54we946jo1uhiq4y29dqwdtxgm",
    "author_bio": {
      "keyname": "doesnt_matter",
      "name": "About This Plugin",
      "field_type": "author_bio",
      "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.",
      "category": "calendar,life"
    },
    "custom_fields": [
      {
        "keyname": "doesnt_matter",
        "name": "About This Plugin",
        "field_type": "author_bio",
        "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.",
        "category": "calendar,life"
      },
      {
        "keyname": "message",
        "field_type": "string",
        "name": "Message",
        "default": "%date",
        "help_text": "%date to display current date"
      }
    ],
    "stats": {
      "installs": 285,
      "forks": 37
    }
  }
}