BUILD WITH YOUR JOURNAL
API documentation.
An authenticated, read-only API for your own Pegboard tools. Documentation is public; your journal is not.
Contract version 1.1.0 · OpenAPI 3.1.0
OpenAPI JSON ↗Full integration guide (Markdown) ↗
Start safely
- Sign in and open Profile → API access. Confirm your password to create an expiring
journal:readtoken. This scope also permits food previews. - Store the one-time secret securely. Send it only in an
Authorization: Bearerheader over HTTPS. Never put it in a URL, source code, screenshots, or logs. - Revoke lost tokens in API access. Browser cookies do not authenticate the API. Native sign-in/session renewal is not implemented; personal tokens are not a substitute for that flow.
Base URL: https://pegboardnutrition.com/api/v1
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $PEGBOARD_API_TOKEN" \
--header "Accept: application/json" \
"https://pegboardnutrition.com/api/v1/journal?date=2026-11-18"
Load the environment variable securely. This page has no token-entry field or “try it” console, and makes no authenticated API requests.
Contracts that matter
- Private journal/body reads are owner-scoped. Responses are
no-store; no broad CORS access is enabled. Existing membership enforcement applies where configured. - IDs and decimal nutrition, portion weights, and body values are strings. Preserve original units and manual calories. Only presentation should round scoreboard values.
- History pagination defaults to 30, at most 100 per page; pages are bounded to 1–10,000. Concurrent edits can shift offset pages.
- Food library results are shared, reviewed USDA source records, at most 12 suggestions or 60 search matches—not journal entries or a paginated complete catalog.
- Barcode results are community-supplied Open Food Facts previews. Check the label and unit warnings. Lookups never save a meal or food entry.
- The shared API limit is 120 requests/minute/IP; barcode lookup also has a 30/minute/IP limit. Respect
Retry-Afterand back off on temporary failures. - There are no write, photo, billing, or account-deletion API endpoints in this contract. Do not infer support from the website's capabilities.
Endpoints
GET /me
Read minimal account settings.
Authentication: Bearer, scope journal:read.
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Profile"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /journal
Read six meal slots and precise daily totals without creating records.
Authentication: Bearer, scope journal:read.
Parameters
date· query · optional-
Defaults to the current calendar date in the owner's saved time zone, or UTC.
{ "type": "string", "format": "date" }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Journal"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /macro_goal
Read targets, or null if none are saved.
Authentication: Bearer, scope journal:read.
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"$ref": "#/components/schemas/Targets"
},
{
"type": "null"
}
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /food_logs
List owned records ordered by logged_on descending, then ID descending.
Authentication: Bearer, scope journal:read.
Parameters
page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } per_page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } logged_on· query · optional-
{ "type": "string", "format": "date" }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Food"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /food_logs/{id}
Read one owned food entry.
Authentication: Bearer, scope journal:read.
Parameters
id· path · required-
{ "type": "string", "pattern": "^[0-9]+$" }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Food"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /weight_entries
List owned records ordered by logged_on descending, then ID descending.
Authentication: Bearer, scope journal:read.
Parameters
page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } per_page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Weight"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /weight_entries/{id}
Read one owned weight entry in pounds.
Authentication: Bearer, scope journal:read.
Parameters
id· path · required-
{ "type": "string", "pattern": "^[0-9]+$" }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Weight"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /body_measurements
List owned records ordered by logged_on descending, then ID descending.
Authentication: Bearer, scope journal:read.
Parameters
page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } per_page· query · optional-
{ "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Measurement"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /body_measurements/{id}
Read one owned body measurement in its original unit.
Authentication: Bearer, scope journal:read.
Parameters
id· path · required-
{ "type": "string", "pattern": "^[0-9]+$" }
Responses
200 · Owner-scoped result.
Exact media type, headers, and schema:
{
"description": "Owner-scoped result.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Measurement"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /food_library
Search reviewed USDA foods; journal:read required. Empty query returns 12 suggestions, nonempty query at most 60 matches, not a paginated complete catalog.
Authentication: Bearer, scope journal:read.
Parameters
q· query · optional-
Prefix tokens, case insensitive. One-character searches return no matches.
{ "type": "string", "maxLength": 100 }
Responses
200 · Read-only food preview; never creates journal entries.
Exact media type, headers, and schema:
{
"description": "Read-only food preview; never creates journal entries.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"maxItems": 60,
"items": {
"$ref": "#/components/schemas/ReferenceFood"
}
},
"metadata": {
"type": "object",
"properties": {
"catalog_version": {
"type": "integer"
},
"source": {
"type": "string"
},
"source_verified_on": {
"type": "string",
"format": "date"
},
"total_count": {
"type": "integer",
"minimum": 0
},
"returned_count": {
"type": "integer",
"minimum": 0,
"maximum": 60
}
},
"required": [
"catalog_version",
"source",
"source_verified_on",
"total_count",
"returned_count"
],
"additionalProperties": false
}
},
"required": [
"data",
"metadata"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · Record does not exist or is not owned by this account.
Exact media type, headers, and schema:
{
"description": "Record does not exist or is not owned by this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
GET /barcode_lookup
Look up one Open Food Facts preview; journal:read required. Additional limit: 30/minute/IP.
Authentication: Bearer, scope journal:read.
Parameters
barcode· query · required-
ASCII digits only, preserving leading zeros. No URL or image is accepted.
{ "type": "string", "pattern": "^(?:[0-9]{8}|[0-9]{12,14})$" }
Responses
200 · Read-only food preview; never creates journal entries.
Exact media type, headers, and schema:
{
"description": "Read-only food preview; never creates journal entries.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/BarcodeProduct"
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
}
400 · Invalid date or pagination parameter.
Exact media type, headers, and schema:
{
"description": "Invalid date or pagination parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
401 · Missing, unknown, expired, or revoked bearer token.
Exact media type, headers, and schema:
{
"description": "Missing, unknown, expired, or revoked bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
}
402 · Membership required when the existing rollout policy is enforced.
Exact media type, headers, and schema:
{
"description": "Membership required when the existing rollout policy is enforced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
403 · Token does not allow journal reads.
Exact media type, headers, and schema:
{
"description": "Token does not allow journal reads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
404 · product_not_found: barcode absent from Open Food Facts.
Exact media type, headers, and schema:
{
"description": "product_not_found: barcode absent from Open Food Facts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
422 · incomplete_nutrition: enter the label manually.
Exact media type, headers, and schema:
{
"description": "incomplete_nutrition: enter the label manually.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
429 · Shared per-IP API rate limit exceeded.
Exact media type, headers, and schema:
{
"description": "Shared per-IP API rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
503 · food_database_unavailable: transient upstream failure; retry with backoff.
Exact media type, headers, and schema:
{
"description": "food_database_unavailable: transient upstream failure; retry with backoff.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"const": "60"
}
}
}
}
Shared schemas
Response references such as #/components/schemas/Food use these definitions. For full validation or code generation, download the OpenAPI JSON above.
Error
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}Profile
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"username": {
"type": "string"
},
"time_zone": {
"type": "string"
},
"measurement_unit": {
"type": "string",
"enum": [
"in",
"cm"
]
},
"scope": {
"type": "string",
"const": "journal:read"
}
},
"required": [
"id",
"username",
"time_zone",
"measurement_unit",
"scope"
],
"additionalProperties": false
}Totals
{
"type": "object",
"properties": {
"protein": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"carbs": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"fat": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"calories": {
"type": "integer"
}
},
"required": [
"protein",
"carbs",
"fat",
"calories"
],
"additionalProperties": false
}Food
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"logged_on": {
"type": "string",
"format": "date"
},
"name": {
"type": [
"string",
"null"
]
},
"meal_position": {
"type": "integer",
"minimum": 1,
"maximum": 6
},
"protein": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"carbs": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"fat": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"calories": {
"type": "integer"
},
"calculated_calories": {
"type": "integer"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"logged_on",
"name",
"meal_position",
"protein",
"carbs",
"fat",
"calories",
"calculated_calories",
"updated_at"
],
"additionalProperties": false
}Weight
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"logged_on": {
"type": "string",
"format": "date"
},
"weight": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"unit": {
"type": "string",
"const": "lb"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"logged_on",
"weight",
"unit",
"updated_at"
],
"additionalProperties": false
}Measurement
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"logged_on": {
"type": "string",
"format": "date"
},
"unit": {
"type": "string",
"enum": [
"in",
"cm"
]
},
"neck": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"chest": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"bicep": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"waist": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"hips": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"thigh": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"calves": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
"description": "Exact decimal string; parse with decimal arithmetic, not binary floating point."
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"logged_on",
"unit",
"neck",
"chest",
"bicep",
"waist",
"hips",
"thigh",
"calves",
"updated_at"
],
"additionalProperties": false
}Targets
{
"type": "object",
"properties": {
"protein": {
"type": "integer"
},
"carbs": {
"type": "integer"
},
"fat": {
"type": "integer"
},
"calories": {
"type": "integer"
}
},
"required": [
"protein",
"carbs",
"fat",
"calories"
],
"additionalProperties": false
}Pagination
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"has_more": {
"type": "boolean"
},
"next_page": {
"type": [
"integer",
"null"
]
}
},
"required": [
"page",
"per_page",
"has_more",
"next_page"
],
"additionalProperties": false
}Journal
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"time_zone": {
"type": "string"
},
"targets": {
"anyOf": [
{
"$ref": "#/components/schemas/Targets"
},
{
"type": "null"
}
]
},
"totals": {
"$ref": "#/components/schemas/Totals"
},
"meals": {
"type": "array",
"minItems": 6,
"maxItems": 6,
"items": {
"type": "object",
"properties": {
"position": {
"type": "integer",
"minimum": 1,
"maximum": 6
},
"name": {
"type": "string"
},
"totals": {
"$ref": "#/components/schemas/Totals"
},
"food_logs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Food"
}
}
},
"required": [
"position",
"name",
"totals",
"food_logs"
],
"additionalProperties": false
}
}
},
"required": [
"date",
"time_zone",
"targets",
"totals",
"meals"
],
"additionalProperties": false
}ReferenceFood
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"group_id": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"emoji": {
"type": "string"
},
"preparation": {
"type": "string"
},
"log_name": {
"type": "string"
},
"detail_name": {
"type": "string"
},
"per_100": {
"type": "object",
"properties": {
"protein": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"carbs": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"fat": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
}
},
"required": [
"protein",
"carbs",
"fat"
],
"additionalProperties": false
},
"unit": {
"type": "string",
"enum": [
"g",
"ml"
]
},
"unit_inferred": {
"type": "boolean"
},
"serving_quantity": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"serving_unit": {
"type": [
"string",
"null"
],
"enum": [
"g",
"ml",
null
]
},
"serving_label": {
"type": "string"
},
"source_url": {
"type": "string",
"format": "uri"
},
"servings": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"grams": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
}
},
"required": [
"id",
"label",
"grams"
],
"additionalProperties": false
}
},
"default_serving_id": {
"type": "string"
},
"portion_note": {
"type": "string"
},
"source_name": {
"type": "string"
},
"source_description": {
"type": "string"
},
"source_verified_on": {
"type": "string",
"format": "date"
}
},
"required": [
"id",
"group_id",
"name",
"emoji",
"preparation",
"log_name",
"detail_name",
"per_100",
"unit",
"unit_inferred",
"serving_quantity",
"serving_unit",
"serving_label",
"source_url",
"servings",
"default_serving_id",
"portion_note",
"source_name",
"source_description",
"source_verified_on"
],
"additionalProperties": false
}BarcodeProduct
{
"type": "object",
"properties": {
"barcode": {
"type": "string",
"pattern": "^(?:[0-9]{8}|[0-9]{12,14})$"
},
"name": {
"type": "string"
},
"per_100": {
"type": "object",
"properties": {
"protein": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"carbs": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"fat": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"calories": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
}
},
"required": [
"protein",
"carbs",
"fat",
"calories"
],
"additionalProperties": false
},
"unit": {
"type": "string",
"enum": [
"g",
"ml"
]
},
"unit_inferred": {
"type": "boolean"
},
"serving_quantity": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"serving_unit": {
"type": [
"string",
"null"
],
"enum": [
"g",
"ml",
null
]
},
"serving_label": {
"type": "string"
},
"source_url": {
"type": "string",
"format": "uri"
},
"calories_derived": {
"type": "boolean"
}
},
"required": [
"barcode",
"name",
"per_100",
"unit",
"unit_inferred",
"serving_quantity",
"serving_unit",
"serving_label",
"source_url",
"calories_derived"
],
"additionalProperties": false
}Keeping this current
This reference renders directly from the same checked-in OpenAPI contract used by automated API response tests. The downloadable guide and JSON are served from their repository sources—not copied to another service. API changes must update the contract, guide, and tests together.