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

Start safely

  1. Sign in and open Profile → API access. Confirm your password to create an expiring journal:read token. This scope also permits food previews.
  2. Store the one-time secret securely. Send it only in an Authorization: Bearer header over HTTPS. Never put it in a URL, source code, screenshots, or logs.
  3. 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

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.