Decode Food ID API

Endpoint

Contract

Send mymolecules-api-version with 2026-07-10 to use the documented response contract.

{
  "data": {},
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-07-10"
  }
}

Headers

Request

• x-api-key required - Server-side API key for your integration.
• mymolecules-api-version required 2026-07-10 - Use the latest stable API version: 2026-07-10.
• Content-Type required application/json - Required for JSON request bodies.

Response

• x-request-id required - Request identifier. Log this value when contacting support.
• mymolecules-api-version required 2026-07-10 - The API contract version used for the response.
• x-ratelimit-limit optional - Quota limit for the current key and window when quota data is available.
• x-ratelimit-remaining optional - Remaining requests in the current quota window when quota data is available.
• x-ratelimit-reset optional - ISO timestamp for the current quota window reset when quota data is available.
• retry-after optional - Seconds to wait before retrying when the request is rate-limited or temporarily unavailable.

Inputs

• Structured items[] with food names and optional quantities
• Or unstructured foodText, foodImage or foodVoice

Returns

• 202 queued response with job_id, status_url and meta
• Final decode_food_id after polling
• Structured items used to build the ID

Async pattern

Create the job with POST, then poll the same endpoint with job_id until the status is completed or failed.

• Poll parameter: job_id
• Status values: queued, processing, completed, failed

Error codes

• missing_api_key
• invalid_api_key
• scope_not_allowed
• quota_exceeded
• invalid_json
• invalid_request
• validation_error
• method_not_allowed
• unsupported_api_version
• job_not_found
• backlog_high
• upstream_timeout
• upstream_error
• internal_error

Request details

• Use items for already-structured food input.
• Use foodText, foodImage or foodVoice when the API should structure the food input first.
• Use items for structured input; foods and canonicalFoods are not part of the documented contract.

Response details

• Poll GET /functions/v1/get_decode_food_id?job_id=... until status is completed or failed.
• Completed status responses include result.decode_food_id and result.structured_items.
• The meta object includes retry_count and timestamps when available.

Operational notes

• Requires x-api-key with the edge:get_decode_food_id scope for job creation.
• This utility is asynchronous because unstructured input may require food parsing and matching.
• Store the returned decode_food_id when later Decode or lookup calls need the same food set.

Examples

{
  "foodText": "Greek yogurt with blueberries, walnuts and honey"
}

{
  "data": {
    "job_id": "9a2f41...",
    "status": "queued",
    "status_url": "https://api.mymolecules.de/functions/v1/get_decode_food_id?job_id=9a2f41..."
  },
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-07-10"
  }
}

Code examples

curl -X POST 'https://api.mymolecules.de/functions/v1/get_decode_food_id' \
  -H 'x-api-key: $MYMOLECULES_API_KEY' \
  -H 'mymolecules-api-version: 2026-07-10' \
  -H 'Content-Type: application/json' \
  --data '{  "foodText": "Greek yogurt with blueberries, walnuts and honey"}'