API Quickstart

The Piehole API is a REST API that powers the mobile app. You can use it directly to build integrations, scripts, or tools on top of your food log.

Base URL

https://api.piehole.ai

All endpoints are prefixed with /api.

Response format

All responses follow the same shape:

Success:

{ "data": <T> }

Error:

{ "error": "Human-readable error message" }

HTTP status codes are standard: 200 for success, 400 for bad requests, 401 for unauthorized, 404 for not found, 500 for server errors.

Authentication

Piehole uses session-based authentication via Better Auth. Sign up or sign in to get a session cookie, then include it with subsequent requests.

Sign up

curl -c cookies.txt -X POST https://api.piehole.ai/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword",
    "name": "Your Name"
  }'

Sign in

curl -c cookies.txt -X POST https://api.piehole.ai/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword"
  }'

The -c cookies.txt flag saves the session cookie. Use -b cookies.txt in subsequent requests to send it.

Key endpoints

Log a food entry

curl -b cookies.txt -X POST https://api.piehole.ai/api/entries \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Greek yogurt",
    "calories": 100,
    "protein_g": 17,
    "carbs_g": 6,
    "fat_g": 0,
    "date": "2026-03-26"
  }'

Required fields: name, calories, date. Optional fields: protein_g, carbs_g, fat_g, brand, barcode, serving_size, source.

Get today’s summary

curl -b cookies.txt "https://api.piehole.ai/api/summary?date=2026-03-26"

Returns total calories and macros for the day, plus your calorie goal and remaining budget.

Search foods

curl -b cookies.txt "https://api.piehole.ai/api/foods/search?q=chicken+breast"

Returns results from your personal library, USDA foods, and Open Food Facts. Minimum 2 characters.

List entries for a date

curl -b cookies.txt "https://api.piehole.ai/api/entries?date=2026-03-26"

Delete an entry

curl -b cookies.txt -X DELETE "https://api.piehole.ai/api/entries/<id>"

Get calendar data

curl -b cookies.txt "https://api.piehole.ai/api/calendar?from=2026-03-01&to=2026-03-31"

Returns an array of daily summaries — useful for building calendar views or exporting history.

Dates

All dates use ISO 8601 format: YYYY-MM-DD. Always pass the user’s local date, not UTC. The server stores entries by the date you provide.

Health check

curl https://api.piehole.ai/api/health

Returns { "data": { "status": "ok" } }. No auth required.

Full API reference

The complete list of endpoints, request/response schemas, and rate limit details is in docs/api-reference.md in the Piehole GitHub repository.