Teuko Logo Lunchbox
Log InSign Up

Teuko Public API

Read-only access to the lunchbox ideas families share on Teuko — the lunchboxes themselves, the tags used to filter them, and public follow lists. No key, no sign-up.

Start here

Everything below is described in machine-readable form too. An agent that has never seen this page can find all of it from the catalog alone.

API catalog
/.well-known/api-catalog

RFC 9727 linkset — the entry point.

OpenAPI 3.1
/openapi.json

Full description of every endpoint.

Health
/api/health

Is the API answering right now?

Auth
/auth.md

What credentials you need. Spoiler: none.

Before you build

  • Every endpoint is GET and returns JSON. Nothing here needs a credential, and nothing here writes.
  • These endpoints also serve teuko.com’s own pages, so treat the shapes as observed rather than promised. Fields may be added without notice; ignore ones you don’t recognise.
  • Please be gentle — there is one small server behind this. Cache what you read, and identify your client in the User-Agent.
  • Lunchbox photos belong to the families who posted them. Link back to /lunchbox/{slug} rather than republishing images.

Endpoints

Lunchbox Search

GET /api/search

Returns a page of 50 lunchboxes, newest first. Every filter is optional; repeating a filter widens the match (any of the given foods), while different filters narrow it (that food AND that theme). Tag ids come from /api/search-filters. Reading requires no credentials.

ParameterTypeMeaning
foodstring, repeatableFood tag id. Repeat for several.
themestring, repeatableTheme tag id. Repeat for several.
accessorystring, repeatableAccessory (boutique item) tag id. Repeat for several.
userstring, repeatableRestrict to these member ids. Repeat for several.
countrystringISO 3166-1 alpha-2 country of the member. Anything else is ignored.
fromstringEarliest post date, inclusive (YYYY-MM-DD, UTC).
tostringLatest post date, inclusive (YYYY-MM-DD, UTC).
mediastringSet to "video" for lunchboxes that have a clip.
pageintegerZero-based page. Each page holds up to 50 results.

Example

curl 'https://www.teuko.com/api/search?food=<id>'

Search Vocabulary

GET /api/search-filters

The controlled vocabulary behind Lunchbox Search. Take the id of any option and pass it to /api/search as food, theme or accessory. Ordered by how often each tag is actually used, so the head of each list is the useful part. Cached for five minutes.

Example

curl 'https://www.teuko.com/api/search-filters'

Follow Lists

GET /api/follows

Keyed by username rather than id, so an id harvested elsewhere cannot be turned into a name. Returns up to 24 members per page.

ParameterTypeMeaning
username*stringThe member whose list to read.
typestringWhich list to return. Anything other than "following" means followers.
pageintegerZero-based page. Each page holds up to 24 members.

Example

curl 'https://www.teuko.com/api/follows?username=teukolove'

Errors: 400 — No username was supplied. · 404 — No member has that username.