Endpoints

Food Search

A fast search endpoint for human-driven queries: search boxes, autocomplete, and food pickers. It uses semantic search over vector embeddings, so it tolerates typos, synonyms, and loosely worded queries without needing an exact name match.

GET/v1/foods/search1 credit / request

Query parameters

Param	Type	Description
q	string	Search term. Required.
limit	number	Max results to return. Default 20, max 100.
page	number	1-indexed page number. Default 1.
category	string	One of 18 fixed Forkbit category slugs: `fruits`, `vegetables`, `grains`, `legumes`, `nuts_seeds`, `dairy_eggs`, `meat`, `poultry`, `seafood`, `fats_oils`, `beverages`, `sweets`, `snacks`, `soups_sauces`, `prepared_meals`, `baby_food`, `spices_herbs`, `other`.

Example request

curl

curl "https://api.forkbit.io/v1/foods/search?q=chicken+breast&limit=1" \
    -H "X-API-Key: fkb_live_xxxxxxxxxxxx"

Example response

200 OK

{
    "data": [
      {
        "id": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Chicken breast, grilled",
        "canonicalName": "Chicken, broilers or fryers, breast, meat only, cooked, grilled",
        "processingTier": "whole",
        "category": { "slug": "poultry", "name": "Poultry" },
        "dataset": "usda_foundation",
        "providerId": "171077",
        "nutrientCompleteness": "full",
        "energyKcal": 165,
        "proteinG": 31.0,
        "fatG": 3.6,
        "carbsG": 0,
        "fiberG": 0,
        "sugarG": 0,
        "sodiumMg": 74
      }
    ],
    "meta": { "total": 12, "page": 1, "limit": 1, "hasMore": true, "matchType": "semantic" }
  }

Errors

Status	Code	Cause
422	VALIDATION_ERROR	`q` is missing or empty, `limit` is outside 1-100, or `page` is less than 1.

An unmatched query is not an error, it returns 200 with an empty data array. See Error handling for the common error codes every endpoint can return.