Forkbit

https://forkbit.io/docs
Admin
Forkbit is a developer-first nutrition data API that returns clean, normalized food and nutrition...
Tokens:10,540
Snippets:94
Trust Score:2.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Forkbit SDK

Source: https://forkbit.io/docs/quickstart

Install the official Forkbit JavaScript SDK via npm.

```bash
npm install @forkbit/js
```

--------------------------------

### Install Forkbit MCP Server

Source: https://forkbit.io/docs/mcp-server

Execute this command in your terminal to run the MCP server.

```bash
npx -y @forkbit/mcp
```

--------------------------------

### Analyze Recipe Response Example

Source: https://forkbit.io/docs/recipe-analysis

The response includes matched ingredient details, total nutritional values, and per-serving calculations.

```json
{
    "data": {
      "ingredients": [
        { "input": "200g chicken breast", "status": "matched", "foodId": "3f2a1b9c-...",
          "foodName": "Chicken breast, grilled", "assumedServing": "200 g", "confidence": 0.96,
          "nutrition": { "calories": 330, "proteinG": 62, "carbsG": 0, "fatG": 7.2 } },
        { "input": "1 tbsp olive oil", "status": "matched", "foodId": "a9b8c7d6-...",
          "foodName": "Olive oil", "assumedServing": "14 g", "confidence": 0.99,
          "nutrition": { "calories": 119, "proteinG": 0, "carbsG": 0, "fatG": 13.5 } },
        { "input": "150g broccoli", "status": "matched", "foodId": "c3d4e5f6-...",
          "foodName": "Broccoli, raw", "assumedServing": "150 g", "confidence": 0.97,
          "nutrition": { "calories": 51, "proteinG": 4.2, "carbsG": 10.2, "fatG": 0.5 } }
      ],
      "totals": { "calories": 500, "proteinG": 66.2, "carbsG": 10.2, "fatG": 21.2 },
      "perServing": { "calories": 125, "proteinG": 16.5, "carbsG": 2.55, "fatG": 5.3 }
    },
    "meta": { "servings": 4, "ingredientCount": 3, "matchedCount": 3, "unmatchedCount": 0, "status": "full_match" }
  }
```

--------------------------------

### Example response for /v1/parse

Source: https://forkbit.io/docs/parse

The API returns a structured object containing matched food items, their nutritional data, and confidence scores.

```json
{
    "data": {
      "matched": [
        {
          "input": "2 grilled chicken breasts",
          "foodId": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
          "foodName": "Chicken breast, grilled",
          "assumedServing": "340 g",
          "confidence": 0.91,
          "nutrition": { "calories": 561, "proteinG": 105.4, "carbsG": 0, "fatG": 12.2 },
          "alternatives": []
        },
        {
          "input": "a handful of almonds",
          "foodId": "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a",
          "foodName": "Almonds",
          "assumedServing": "28 g",
          "confidence": 0.74,
          "nutrition": { "calories": 164, "proteinG": 6.0, "carbsG": 6.1, "fatG": 14.2 },
          "alternatives": []
        }
      ],
      "unmatched": []
    },
    "meta": { "matchedCount": 2, "unmatchedCount": 0, "status": "full_match" }
  }
```

--------------------------------

### Batch Lookup Example Response

Source: https://forkbit.io/docs/batch-lookup

The response returns an array of food objects corresponding to the input IDs. Missing or invalid IDs are represented as null in the array.

```json
{
    "data": [
      {
        "id": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Chicken breast, grilled",
        "category": { "slug": "poultry", "name": "Poultry" },
        "energyKcal": 165,
        "proteinG": 31.0,
        "fatG": 3.6,
        "carbsG": 0
      },
      {
        "id": "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Almonds",
        "category": { "slug": "nuts_seeds", "name": "Nuts & Seeds" },
        "energyKcal": 579,
        "proteinG": 21.2,
        "fatG": 49.9,
        "carbsG": 21.6
      },
      null
    ]
  }
```

--------------------------------

### GET /v1/foods/{id}

Source: https://forkbit.io/docs

Retrieves the full nutrient profile for a specific food item by its ID.

```APIDOC
## GET /v1/foods/{id}

### Description
Retrieves the full nutrient profile for a specific food item by its ID.

### Method
GET

### Endpoint
https://api.forkbit.io/v1/foods/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the food item.
```

--------------------------------

### GET /v1/foods/search

Source: https://forkbit.io/docs

Performs a fast search for food items based on human-driven queries.

```APIDOC
## GET /v1/foods/search

### Description
Performs a fast search for food items based on human-driven queries.

### Method
GET

### Endpoint
https://api.forkbit.io/v1/foods/search
```

--------------------------------

### GET /v1/foods/search

Source: https://forkbit.io/docs/filtering

Search for foods with optional category filtering and pagination.

```APIDOC
## GET /v1/foods/search

### Description
Search for food items and optionally restrict results to a specific category. Pagination is supported via page and limit parameters.

### Method
GET

### Endpoint
/v1/foods/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.
- **category** (string) - Optional - Restricts results to a single category slug (e.g., vegetables, fruits, dairy_eggs, poultry).
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of results to return per page.

### Request Example
curl "https://api.forkbit.io/v1/foods/search?q=cheddar&category=dairy_eggs" \
    -H "X-API-Key: fkb_live_xxxxxxxxxxxx"
```

--------------------------------

### GET /v1/foods/{id}

Source: https://forkbit.io/docs/food-detail

Retrieves the full available nutrient profile for a single food item using its unique identifier.

```APIDOC
## GET /v1/foods/{id}

### Description
Returns the full available nutrient profile for a single food. Intended for detail views, comparison tools, and apps that need data beyond the core macros.

### Method
GET

### Endpoint
/v1/foods/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique UUID of the food item.

### Request Example
curl https://api.forkbit.io/v1/foods/3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a -H "X-API-Key: fkb_live_xxxxxxxxxxxx"

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the food.
- **name** (string) - The common name of the food.
- **canonicalName** (string) - The official canonical name.
- **processingTier** (string) - The processing level of the food.
- **category** (object) - The category information including slug and name.
- **dataset** (string) - The source dataset.
- **providerId** (string) - The provider-specific ID.
- **nutrientCompleteness** (string) - The completeness status of the nutrient data.
- **energyKcal** (number) - Energy content in kcal.
- **proteinG** (number) - Protein content in grams.
- **fatG** (number) - Fat content in grams.
- **carbsG** (number) - Carbohydrate content in grams.
- **fiberG** (number) - Fiber content in grams.
- **sugarG** (number) - Sugar content in grams.
- **sodiumMg** (number) - Sodium content in milligrams.
- **scientificName** (string|null) - The scientific name if available.
- **publishedAt** (string) - Publication date.
- **updatedAt** (string) - Last update date.
- **nutrients** (array) - List of detailed nutrient objects.
- **portions** (array) - List of available serving size portions.

#### Response Example
{
    "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,
    "scientificName": null,
    "publishedAt": "2026-04-01",
    "updatedAt": "2026-04-12",
    "nutrients": [
      { "id": "5c6d7e8f-...", "code": "208", "name": "Energy", "unit": "KCAL", "amount": 165, "sourceNutrientCode": "208" },
      { "id": "5c6d7e90-...", "code": "203", "name": "Protein", "unit": "G", "amount": 31.0, "sourceNutrientCode": "203" }
    ],
    "portions": [
      { "id": "8a9b0c1d-...", "name": "100 g", "gramWeight": 100, "isDefault": true },
      { "id": "8a9b0c1e-...", "name": "1 medium breast", "gramWeight": 174, "isDefault": false }
    ]
}
```

--------------------------------

### GET /v1/foods/search

Source: https://forkbit.io/docs/foods-search

Performs a semantic search for food items based on a query string, supporting typos and synonyms.

```APIDOC
## GET /v1/foods/search

### Description
A fast search endpoint for human-driven queries such as search boxes, autocomplete, and food pickers. It uses semantic search over vector embeddings to tolerate typos and synonyms.

### Method
GET

### Endpoint
/v1/foods/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search term.
- **limit** (number) - Optional - Max results to return. Default 20, max 100.
- **page** (number) - Optional - 1-indexed page number. Default 1.
- **category** (string) - Optional - One of 18 fixed Forkbit category slugs (e.g., fruits, vegetables, meat, poultry).

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

### Response
#### Success Response (200)
- **data** (array) - List of food items matching the query.
- **meta** (object) - Metadata including total results, current page, and match type.

#### Response Example
{
    "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" }
  }
```

--------------------------------

### Initialize and Use Forkbit SDK

Source: https://forkbit.io/docs/sdks

Initialize the client with an API key and perform a search query.

```typescript
import { Forkbit } from "@forkbit/js";

const forkbit = new Forkbit({ apiKey: process.env.FORKBIT_API_KEY! });

const { data } = await forkbit.foods.search("banana");
console.log(data[0].name);
```

--------------------------------

### Initialize Forkbit Client

Source: https://forkbit.io/docs/quickstart

Configure the Forkbit client using an API key from environment variables.

```typescript
import { Forkbit } from "@forkbit/js";

export const forkbit = new Forkbit({
  apiKey: process.env.FORKBIT_API_KEY!,
});
```

--------------------------------

### POST /v1/recipes/analyze

Source: https://forkbit.io/docs

Calculates recipe totals and per-serving macros.

```APIDOC
## POST /v1/recipes/analyze

### Description
Calculates recipe totals and per-serving macros.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/recipes/analyze
```

--------------------------------

### Configure Claude Desktop for Forkbit

Source: https://forkbit.io/docs/mcp-server

Add this configuration to your Claude Desktop settings file to enable the Forkbit MCP server.

```json
{
  "mcpServers": {
    "forkbit": {
      "command": "npx",
      "args": ["-y", "@forkbit/mcp"],
      "env": { "FORKBIT_API_KEY": "fkb_live_xxxxxxxxxxxx" }
    }
  }
}
```

--------------------------------

### POST /v1/parse

Source: https://forkbit.io/docs

Converts natural language food descriptions into structured nutrition data.

```APIDOC
## POST /v1/parse

### Description
Converts natural language food descriptions into structured nutrition data.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/parse
```

--------------------------------

### POST /v1/parse

Source: https://forkbit.io/docs/introduction

Parses natural language food descriptions into structured nutrition data.

```APIDOC
## POST /v1/parse

### Description
Parses natural language food descriptions into structured nutrition data.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/parse
```

--------------------------------

### POST /v1/recipes/analyze

Source: https://forkbit.io/docs/introduction

Analyzes recipes to calculate totals and per-serving macros.

```APIDOC
## POST /v1/recipes/analyze

### Description
Analyzes recipes to calculate totals and per-serving macros.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/recipes/analyze
```

--------------------------------

### Parse Nutrition and Analyze Recipes

Source: https://forkbit.io/docs/sdks

Parse natural language nutrition strings or analyze recipe ingredients.

```typescript
const { data: meal } = await forkbit.parse.nutrition("2 eggs and a slice of toast with butter");

const { data: recipe } = await forkbit.recipes.analyze({
  servings: 4,
  ingredients: ["200g chicken breast", "1 tbsp olive oil"],
});
```

--------------------------------

### analyze_recipe

Source: https://forkbit.io/docs/mcp-server

Calculate total and per-serving nutrition for a recipe.

```APIDOC
## analyze_recipe(servings, ingredients)

### Description
Totals and per-serving nutrition for a full recipe. Prefer parse_nutrition for independent items that do not need recipe totals.

### Parameters
- **servings** (integer) - Required - The number of servings in the recipe.
- **ingredients** (array) - Required - A list of ingredient strings.
```

--------------------------------

### POST /v1/foods/batch

Source: https://forkbit.io/docs

Looks up up to 50 food items in a single request.

```APIDOC
## POST /v1/foods/batch

### Description
Looks up up to 50 food items in a single request.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/foods/batch
```

--------------------------------

### POST /v1/foods/batch

Source: https://forkbit.io/docs/introduction

Looks up nutrition data for up to 50 foods in a single request.

```APIDOC
## POST /v1/foods/batch

### Description
Looks up nutrition data for up to 50 foods in a single request.

### Method
POST

### Endpoint
https://api.forkbit.io/v1/foods/batch
```

--------------------------------

### Request body for /v1/parse

Source: https://forkbit.io/docs/parse

Submit a natural language string containing food items and quantities to the /v1/parse endpoint.

```json
{
    "text": "2 grilled chicken breasts with olive oil and a handful of almonds"
  }
```

--------------------------------

### POST /v1/parse

Source: https://forkbit.io/docs/parse

Accepts a free-text food description and returns nutrition data already calculated for the described quantity.

```APIDOC
## POST /v1/parse

### Description
Accepts a free-text food description and returns nutrition data already calculated for the described quantity. Designed for AI agents, voice input, and conversational food logging.

### Method
POST

### Endpoint
/v1/parse

### Request Body
- **text** (string) - Required - The natural language food description to parse.

### Request Example
{
  "text": "2 grilled chicken breasts with olive oil and a handful of almonds"
}

### Response
#### Success Response (200)
- **data** (object) - Contains matched and unmatched food fragments.
- **meta** (object) - Contains summary information including matchedCount, unmatchedCount, and status.

#### Response Example
{
  "data": {
    "matched": [
      {
        "input": "2 grilled chicken breasts",
        "foodId": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
        "foodName": "Chicken breast, grilled",
        "assumedServing": "340 g",
        "confidence": 0.91,
        "nutrition": { "calories": 561, "proteinG": 105.4, "carbsG": 0, "fatG": 12.2 },
        "alternatives": []
      }
    ],
    "unmatched": []
  },
  "meta": { "matchedCount": 1, "unmatchedCount": 0, "status": "full_match" }
}
```

--------------------------------

### Analyze Recipe Request Body

Source: https://forkbit.io/docs/recipe-analysis

The request body requires a servings integer and an array of ingredient strings. Each ingredient string is parsed independently.

```json
{
    "servings": 4,
    "ingredients": [
      "200g chicken breast",
      "1 tbsp olive oil",
      "150g broccoli"
    ]
  }
```

--------------------------------

### Authentication Header

Source: https://forkbit.io/docs/authentication

All requests to the Forkbit API must include the X-API-Key header to authenticate.

```APIDOC
## Authentication

### Description
The Forkbit API uses API keys for authentication. Every request must include your API key in the `X-API-Key` header.

### Headers
- **X-API-Key** (string) - Required - Your unique API key prefixed with `fkb_live_`.
```

--------------------------------

### Retrieve food details via cURL

Source: https://forkbit.io/docs/food-detail

Use this request to fetch the full nutrient profile for a specific food item. Requires a valid API key in the X-API-Key header.

```bash
curl https://api.forkbit.io/v1/foods/3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a \
    -H "X-API-Key: fkb_live_xxxxxxxxxxxx"
```

--------------------------------

### parse_nutrition

Source: https://forkbit.io/docs/mcp-server

Parse free-text meal descriptions into matched foods with nutrition data.

```APIDOC
## parse_nutrition(text)

### Description
Parse a free-text meal description into matched foods with nutrition. LLM-backed.

### Parameters
- **text** (string) - Required - The free-text description of the meal.
```

--------------------------------

### Authenticate a request with cURL

Source: https://forkbit.io/docs/authentication

Include the API key in the X-API-Key header to authenticate requests.

```bash
curl https://api.forkbit.io/v1/foods/search?q=oatmeal \
  -H "X-API-Key: fkb_live_xxxxxxxxxxxxxxxx"
```

--------------------------------

### POST /v1/recipes/analyze

Source: https://forkbit.io/docs/recipe-analysis

Analyzes a list of ingredients to return total and per-serving nutritional information. Each ingredient line is parsed and matched independently.

```APIDOC
## POST /v1/recipes/analyze

### Description
Accepts a list of ingredients and returns the total nutrition breakdown for the whole recipe, plus per-serving values. Uses the parse engine per ingredient line, so each line is matched and scored independently.

### Method
POST

### Endpoint
/v1/recipes/analyze

### Request Body
- **servings** (integer) - Required - Number of servings (1-100).
- **ingredients** (array of strings) - Required - List of ingredient lines (1-50 lines, each under 200 characters).

### Request Example
{
    "servings": 4,
    "ingredients": [
      "200g chicken breast",
      "1 tbsp olive oil",
      "150g broccoli"
    ]
  }

### Response
#### Success Response (200)
- **data** (object) - Contains ingredients, totals, and perServing nutrition data.
- **meta** (object) - Contains metadata including servings, ingredient counts, and status.

#### Response Example
{
    "data": {
      "ingredients": [
        { "input": "200g chicken breast", "status": "matched", "foodId": "3f2a1b9c-...",
          "foodName": "Chicken breast, grilled", "assumedServing": "200 g", "confidence": 0.96,
          "nutrition": { "calories": 330, "proteinG": 62, "carbsG": 0, "fatG": 7.2 } },
        { "input": "1 tbsp olive oil", "status": "matched", "foodId": "a9b8c7d6-...",
          "foodName": "Olive oil", "assumedServing": "14 g", "confidence": 0.99,
          "nutrition": { "calories": 119, "proteinG": 0, "carbsG": 0, "fatG": 13.5 } },
        { "input": "150g broccoli", "status": "matched", "foodId": "c3d4e5f6-...",
          "foodName": "Broccoli, raw", "assumedServing": "150 g", "confidence": 0.97,
          "nutrition": { "calories": 51, "proteinG": 4.2, "carbsG": 10.2, "fatG": 0.5 } }
      ],
      "totals": { "calories": 500, "proteinG": 66.2, "carbsG": 10.2, "fatG": 21.2 },
      "perServing": { "calories": 125, "proteinG": 16.5, "carbsG": 2.55, "fatG": 5.3 }
    },
    "meta": { "servings": 4, "ingredientCount": 3, "matchedCount": 3, "unmatchedCount": 0, "status": "full_match" }
  }
```

--------------------------------

### Search for food items using cURL

Source: https://forkbit.io/docs/foods-search

Perform a semantic search for food items by providing a query string and an API key.

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

--------------------------------

### Forkbit TypeScript SDK

Source: https://forkbit.io/docs/sdks

The official TypeScript SDK provides a typed interface for interacting with Forkbit services.

```APIDOC
## TypeScript SDK Usage

### Installation
`npm install @forkbit/js`

### Initialization
```typescript
import { Forkbit } from "@forkbit/js";
const forkbit = new Forkbit({ apiKey: process.env.FORKBIT_API_KEY! });
```

### Available Methods
- `forkbit.foods.search(query: string, options?: { limit: number })`
- `forkbit.foods.get(id: string)`
- `forkbit.foods.batch(ids: string[])`
- `forkbit.parse.nutrition(text: string)`
- `forkbit.recipes.analyze(params: { servings: number, ingredients: string[] })`
```

--------------------------------

### POST /v1/foods/batch

Source: https://forkbit.io/docs/batch-lookup

Look up multiple foods in a single request. This endpoint is designed to eliminate the N+1 problem when resolving lists of food items.

```APIDOC
## POST /v1/foods/batch

### Description
Look up multiple foods in a single request. Eliminates the N+1 problem for apps resolving a grocery list, a meal's ingredients, or a day's food log.

### Method
POST

### Endpoint
/v1/foods/batch

### Request Body
- **ids** (array of strings) - Required - A list of food UUIDs to retrieve. Maximum 50 IDs per request.

### Request Example
{
    "ids": ["3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a", "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a", "c3d4e5f6-1234-4b8b-9e0a-6b7c8d9e0f1a"]
}

### Response
#### Success Response (200)
- **data** (array) - An array of food objects or null values, returned in the same order as the input IDs.

#### Response Example
{
    "data": [
      {
        "id": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Chicken breast, grilled",
        "category": { "slug": "poultry", "name": "Poultry" },
        "energyKcal": 165,
        "proteinG": 31.0,
        "fatG": 3.6,
        "carbsG": 0
      },
      {
        "id": "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Almonds",
        "category": { "slug": "nuts_seeds", "name": "Nuts & Seeds" },
        "energyKcal": 579,
        "proteinG": 21.2,
        "fatG": 49.9,
        "carbsG": 21.6
      },
      null
    ]
}

### Errors
- **422 VALIDATION_ERROR**: ids is empty, has more than 50 items, or contains a value that isn't a valid UUID.
```

--------------------------------

### batch_get_foods

Source: https://forkbit.io/docs/mcp-server

Retrieve full detail for multiple food items in a single call.

```APIDOC
## batch_get_foods(ids)

### Description
Full detail for up to 50 ids in one call. Use this instead of calling get_food in a loop.

### Parameters
- **ids** (array) - Required - A list of food identifiers.
```

--------------------------------

### search_foods

Source: https://forkbit.io/docs/mcp-server

Search for foods by name. Returns lightweight summaries.

```APIDOC
## search_foods(query, page?, limit?, category?)

### Description
Search by food name. Returns lightweight summaries. Use get_food or batch_get_foods for full nutrient detail.

### Parameters
- **query** (string) - Required - The search term for the food.
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of results to return.
- **category** (string) - Optional - The food category to filter by.
```

--------------------------------

### Parse Free-Text Meals

Source: https://forkbit.io/docs/quickstart

Extract nutritional information from natural language meal descriptions.

```typescript
const { data } = await forkbit.parse.nutrition("2 eggs and a slice of sourdough");

for (const item of data.matched) {
  console.log(item.foodName, item.nutrition.calories);
}
// Egg, whole 144
// Sourdough bread 120
```

--------------------------------

### View Credit Status Headers

Source: https://forkbit.io/docs/rate-limits

Headers returned in every API response indicating current credit consumption and reset time.

```http
X-Credits-Consumed: 10
X-Credits-Remaining: 48990
X-Credits-Reset: 2026-07-01T00:00:00Z
```

--------------------------------

### get_food

Source: https://forkbit.io/docs/mcp-server

Retrieve full nutrient and portion detail for a single food item.

```APIDOC
## get_food(id)

### Description
Full nutrient and portion detail for one food by id.

### Parameters
- **id** (string) - Required - The unique identifier for the food item.
```

--------------------------------

### View Rate Limit Status Headers

Source: https://forkbit.io/docs/rate-limits

Headers returned in every API response indicating current request rate limits and the Unix timestamp for the next window reset.

```http
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1751328000
```

--------------------------------

### Search for Food Items

Source: https://forkbit.io/docs/quickstart

Query the database for specific food items with a defined result limit.

```typescript
const { data } = await forkbit.foods.search("chicken breast", { limit: 5 });

console.log(data[0]);
// { id: "3f2a1b9c-...", name: "Chicken breast, grilled",
//   category: { slug: "poultry", name: "Poultry" },
//   energyKcal: 165, proteinG: 31, carbsG: 0, fatG: 3.6 }
```

--------------------------------

### Batch Lookup Request Body

Source: https://forkbit.io/docs/batch-lookup

The request body requires an array of UUID strings under the 'ids' key. A maximum of 50 IDs is permitted per request.

```json
{
    "ids": ["3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a", "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a", "c3d4e5f6-1234-4b8b-9e0a-6b7c8d9e0f1a"]
  }
```

--------------------------------

### Food detail response structure

Source: https://forkbit.io/docs/food-detail

The JSON response contains the food's metadata, core macros, a full list of nutrients, and available serving portions.

```json
{
    "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,
    "scientificName": null,
    "publishedAt": "2026-04-01",
    "updatedAt": "2026-04-12",
    "nutrients": [
      { "id": "5c6d7e8f-...", "code": "208", "name": "Energy", "unit": "KCAL", "amount": 165, "sourceNutrientCode": "208" },
      { "id": "5c6d7e90-...", "code": "203", "name": "Protein", "unit": "G", "amount": 31.0, "sourceNutrientCode": "203" }
    ],
    "portions": [
      { "id": "8a9b0c1d-...", "name": "100 g", "gramWeight": 100, "isDefault": true },
      { "id": "8a9b0c1e-...", "name": "1 medium breast", "gramWeight": 174, "isDefault": false }
    ]
  }
```

--------------------------------

### Perform Food Operations

Source: https://forkbit.io/docs/sdks

Search for foods, retrieve specific food details, or perform batch lookups.

```typescript
const { data, meta } = await forkbit.foods.search("chicken breast", { limit: 10 });
const { data: food } = await forkbit.foods.get(data[0].id);
const { data: foods } = await forkbit.foods.batch([food.id]);
```

--------------------------------

### Error Response Format

Source: https://forkbit.io/docs/error-handling

Every error response follows a consistent structure, allowing for reliable programmatic handling via the error code.

```APIDOC
## Error Envelope

### Description
All API errors return a standard JSON object containing details about the failure.

### Response
- **error** (object) - The error container
  - **code** (string) - A machine-readable error code (e.g., NOT_FOUND)
  - **message** (string) - A human-readable description of the error
  - **statusCode** (integer) - The HTTP status code
  - **timestamp** (string) - ISO 8601 timestamp of the error
  - **path** (string) - The request path that triggered the error

### Response Example
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No food found with ID 'abc-123'.",
    "statusCode": 404,
    "timestamp": "2026-05-15T10:30:00Z",
    "path": "/v1/foods/abc-123"
  }
}
```

--------------------------------

### Food search response structure

Source: https://forkbit.io/docs/foods-search

The JSON response returned by the search endpoint, containing food item details and metadata.

```json
{
    "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" }
  }
```

--------------------------------

### Filter food search by category

Source: https://forkbit.io/docs/filtering

Use the category query parameter to restrict search results to a specific category slug.

```curl
curl "https://api.forkbit.io/v1/foods/search?q=cheddar&category=dairy_eggs" \
    -H "X-API-Key: fkb_live_xxxxxxxxxxxx"
```

--------------------------------

### Standard Error Envelope

Source: https://forkbit.io/docs/error-handling

The structure of the error response returned by all API endpoints.

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No food found with ID 'abc-123'.",
    "statusCode": 404,
    "timestamp": "2026-05-15T10:30:00Z",
    "path": "/v1/foods/abc-123"
  }
}
```
Tokens:
Raw