Bitefull API

A REST API for recipes, meal planning, shopping lists, and pantry management.

Discover and author recipes, generate weekly meal plans around dietary goals, turn plans into de-duplicated shopping lists, and track pantry inventory. JSON over HTTPS.

Base URL & versioning

Every endpoint lives under a versioned prefix:

https://api.kyox.io/bitefull/v1

The version is part of the path. Breaking changes ship under a new version (/v2) while older versions keep working. The interactive reference is at /bitefull/v1/docs.

Authentication

Bitefull uses two layers. An API key identifies the calling app or account and is required on every request. A user token (JWT) identifies an end-user and is required only on user-scoped routes.

API key

Send your key in the X-API-Key header on every request. Keys gate access to the API and are how usage is metered per account.

X-API-Key: bk_live_<your-key>

Manage keys at /api-keys (create, list, revoke). A key's secret is shown once at creation — store it securely; it can't be retrieved again. Requests without a valid key return 401.

User token

Register or log in to receive a short-lived access token and a rotating refresh token. Send the access token alongside your API key on authenticated routes:

X-API-Key: bk_live_<your-key>
Authorization: Bearer <accessToken>

Access tokens expire after 15 minutes. Exchange a refresh token at POST /auth/refresh for a new pair. Refresh tokens rotate on every use — reusing an old one revokes the whole session family.

Quick start

# Register a user (API key required on every call)
curl -X POST https://api.kyox.io/bitefull/v1/auth/register \
  -H "X-API-Key: bk_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","username":"chef","password":"Secret123"}'

# Call a user-scoped route with both credentials
curl https://api.kyox.io/bitefull/v1/auth/me \
  -H "X-API-Key: bk_live_<your-key>" \
  -H "Authorization: Bearer <accessToken>"

Roles: USER, PREMIUM, ADMIN — used for authorization and rate-limit tiers.

Errors

Errors use standard HTTP status codes and a consistent JSON envelope:

{
  "statusCode": 401,
  "error": "UnauthorizedException",
  "message": "Invalid credentials",
  "path": "/bitefull/v1/auth/login",
  "timestamp": "2026-06-01T12:00:00.000Z"
}

Rate limits

Limits scale with your tier, counted per rolling 60-second window:

Exceeding the limit returns 429 Too Many Requests.

API Keys

Issue and manage the keys that gate API access. These routes require a user token; the very first key is minted server-side.

Create a key

POST /api-keys
{ "name": "Acme production", "expiresInDays": 365 }

The response includes key exactly once — store it now. Optionally set rateLimitPerMin to override the tier limit for a paid plan.

Auth

Example response

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "k3jf9...",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Recipes

Search

Combine free-text with structured filters. All parameters are optional:

curl "https://api.kyox.io/bitefull/v1/recipes/search?q=salmon&diet=PESCATARIAN&maxTime=40"

Filtering lives on /recipes/search. The plain GET /recipes list only paginates — it ignores cuisine, diet, tags and the other filters.

Browse & categories

GET /recipes/categories returns the facets for building browse menus and home sections. Each entry is { value, count } (meal types also include a label), plus a filterParam map naming the /recipes/search parameter that applies each facet:

curl "https://api.kyox.io/bitefull/v1/recipes/categories"
curl "https://api.kyox.io/bitefull/v1/recipes/search?cuisine=Thai&tags=dinner&sort=rating"

Create a recipe

POST /recipes
{
  "title": "Grilled Chicken Bowl",
  "servings": 2,
  "prepTime": 10, "cookTime": 20,
  "difficulty": "EASY",
  "cuisine": "American",
  "diets": ["DAIRY_FREE"],
  "tags": ["high-protein"],
  "ingredients": [
    { "name": "chicken breast", "quantity": 300, "unit": "GRAM" },
    { "name": "white rice", "quantity": 200, "unit": "GRAM" }
  ],
  "instructions": [
    { "step": 1, "text": "Cook the rice." },
    { "step": 2, "text": "Grill the chicken." }
  ],
  "publish": true
}

Per-serving nutrition (calories, protein, carbs, fat, fiber, sodium) is computed automatically from ingredient data.

Engagement

Meal plans

Generate a plan

The generator fills each day and slot with recipes that satisfy dietary restrictions, hit a daily calorie band, prefer your cuisines and pantry-covered recipes, and avoid repeats. Unspecified options fall back to your saved preferences.

POST /meal-plans/generate
{
  "startDate": "2026-06-08",
  "days": 7,
  "slots": ["BREAKFAST", "LUNCH", "DINNER"],
  "diets": ["VEGAN"],
  "dailyCalorieGoal": 1800,
  "cuisines": ["Mediterranean"],
  "usePantry": true
}

Shopping lists

Generate from a meal plan

Collects every ingredient across the chosen recipes (or a whole meal plan), normalizes units, aggregates duplicates, and subtracts what your pantry already covers.

POST /shopping-lists/generate
{ "mealPlanId": "8bc883fc-...", "subtractPantry": true }

Pantry

POST /pantry
{ "ingredientName": "olive oil", "quantity": 500, "unit": "GRAM", "expirationDate": "2026-12-01" }

Users

Dietary preferences set here (diets, allergens, preferred cuisines, daily calorie goal) become the defaults for search, recommendations, and meal-plan generation.