generated: '2026-08-12'
method: searched
source: https://platform.fatsecret.com/docs/guides
docs:
  guides: https://platform.fatsecret.com/docs/guides
  authentication: https://platform.fatsecret.com/docs/guides/authentication
  oauth2: https://platform.fatsecret.com/docs/guides/authentication/oauth2
  oauth1_three_legged: https://platform.fatsecret.com/docs/guides/authentication/oauth1/three-legged
  parameters: https://platform.fatsecret.com/docs/guides/parameters
  data_types: https://platform.fatsecret.com/docs/guides/data-types
  storable_data: https://platform.fatsecret.com/docs/guides/storable-data
  localization: https://platform.fatsecret.com/docs/guides/localization
  error_codes: https://platform.fatsecret.com/docs/guides/error-codes
base_url: https://platform.fatsecret.com/rest
style: >-
  REST-ish over a single host. Every capability is a versioned path segment under /rest — the version
  travels with the METHOD, not the API (/foods/search/v5, /food/v4, /recipes/search/v3,
  /food-categories/v2, /food/barcode/find-by-id/v1 all coexist). There is no global API version, so a
  client must track a version per method.
authentication:
  style: bearer token (OAuth 2.0 client_credentials) or request signing (OAuth 1.0a)
  oauth2:
    token_endpoint: https://oauth.fatsecret.com/connect/token
    grant: client_credentials
    header: 'Authorization: Bearer <access_token>'
    token_lifetime: 24 hours (default)
    scoped: true
    note: >-
      "fatsecret requires that OAuth 2.0 tokens be requested through a proxy server" — the provider's
      own guidance, to keep the client secret off the device.
  oauth1:
    profile: 3-legged OAuth 1.0a, used for member (profile-scoped) data
  see: authentication/fatsecret-authentication.yml
idempotency:
  supported: false
  header: null
  note: >-
    No idempotency key of any kind is documented. Write methods (create_food_entry, update_weight,
    commit exercise entries, saved-meal mutations) carry no dedupe contract, so a retried write can
    double-post a diary entry. This is a real gap for agent use, not an omission in this artifact —
    no Idempotency pointer is emitted for fatsecret.
pagination:
  style: offset
  parameters:
    - name: page_number
      description: zero-based page offset
      default: 0
    - name: max_results
      description: results per page
      default: 20
      maximum: 50
  response_fields: [page_number, max_results, total_results]
  note: Applies to foods.search v5 and recipes.search v3; reference lists are unpaginated.
content_negotiation:
  parameter: format
  values: [xml, json]
  default: xml
  note: >-
    The default response is XML, not JSON. Every agent/JSON client must pass format=json explicitly
    on every call — the single most common integration surprise on this API.
  header_negotiation: false
localization:
  parameters:
    - name: region
      description: "ISO country code; filters results by market. Defaults to US."
    - name: language
      description: "Language code; ignored unless region is also specified."
  supported_regions: 200+
  supported_languages: 25
  scope_required: localization
  docs: https://platform.fatsecret.com/docs/guides/localization
field_expansion:
  style: boolean include_* flags on the request
  parameters:
    - include_sub_categories
    - include_food_images
    - include_food_attributes
    - flag_default_serving
  note: include_food_images and include_food_attributes require a Premier edition.
request_tracing:
  request_id_header: null
  note: No correlation/request-id header is documented on requests or responses.
versioning:
  scheme: per-method path segment
  examples: [/foods/search/v5, /food/v4, /recipes/search/v3, /food-brands/v2, /food/barcode/find-by-id/v1]
  see: lifecycle/fatsecret-lifecycle.yml
error_envelope:
  shape: '{"error": {"code": NUMBER, "message": "TEXT"}}'
  transport_status_is_signal: false
  note: >-
    Errors are returned in the body with a vendor numeric code; a failed call is not reliably
    distinguishable by HTTP status. Parse error.code.
  see: errors/fatsecret-error-codes.yml
rate_limit_signaling:
  headers: []
  status_code: null
  signal: error code 11 ("Application request limit reached") and error code 12 (per-profile throttle)
  see: rate-limits/fatsecret-rate-limits.yml
data_retention:
  storable_data: >-
    fatsecret restricts what a client may persist. On foods.search v5 only food_id and serving_id are
    storable; the nutrition payload itself must be re-fetched.
  docs: https://platform.fatsecret.com/docs/guides/storable-data