Endpoint

POST/functions/v1/decode_sensory

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

foodText, foodImage or foodVoice
sensoryOutput for the requested sensory view
Optional food_output_language for localized display food names

Returns

202 queued response with job_id and status_url
Completed food_detected or no_food_detected result
Per-food and/or whole-meal sensory interpretation

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

Provide at least one of foodText, foodImage or foodVoice.
sensoryOutput is optional and must be per_food, whole_meal or per_food_and_whole_meal when provided.
food_output_language localizes additive display fields; canonical food names and sensory keys remain English.
foodImage and foodVoice must be base64 data URLs; text input is capped for concise meal descriptions.

Response details

Poll GET /functions/v1/decode_sensory?job_id=... until status is completed or failed.
The completed result follows the requested sensoryOutput mode.
Every completed result has type: food_detected or type: no_food_detected.
food_detected always includes items and sensory; whole_meal intentionally returns items: [] because it does not structure ingredients.
per_food example: result contains type: food_detected, non-empty items and sensory.per_food only.
whole_meal example: result contains type: food_detected, items: [] and sensory.whole_meal only.
per_food_and_whole_meal example: result contains type: food_detected, non-empty items and both sensory.per_food and sensory.whole_meal.
no_food_detected returns items: [], sensory: null and error: null as a completed domain result.
Per-food profiles include food, quantity, unit, display and canonical representations.
Queued or processing jobs return result: null and error: null.

Operational notes

Requires x-api-key with the edge:decode_sensory scope.
POST usage is counted and rate-limit headers are returned when quota data is available.
Unsupported fields are rejected, so keep request bodies limited to the documented fields.

Examples

Request JSON

{
  "foodText": "Tomato soup with basil and olive oil",
  "food_output_language": "English",
  "sensoryOutput": "per_food_and_whole_meal"
}

Response JSON

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

Code examples

curl -X POST 'https://api.mymolecules.de/functions/v1/decode_sensory' \
  -H 'x-api-key: $MYMOLECULES_API_KEY' \
  -H 'mymolecules-api-version: 2026-07-10' \
  -H 'Content-Type: application/json' \
  --data '{  "foodText": "Tomato soup with basil and olive oil",  "food_output_language": "English",  "sensoryOutput": "per_food_and_whole_meal"}'

Try in playground