Endpoint

POST/functions/v1/decide

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

Required request_text with the complete decision question
Optional options[] with 2 to 10 entries; each requires type and data
Optional images[] with 1 to 5 image URLs or data URLs in free-text mode only

Returns

Synchronous 200 response with status completed
result.outcome, options, selected_option and reasoning
Structured failed response for validation or upstream errors

Error codes

missing_api_key
invalid_api_key
scope_not_allowed
quota_exceeded
rate_limited
invalid_json
invalid_request
invalid_request_shape
too_many_options
input_too_large
user_context_not_allowed
detect_signals_not_allowed
validation_error
method_not_allowed
unsupported_api_version
job_not_found
backlog_high
service_unavailable
upstream_timeout
upstream_error
internal_error

Request details

Omit options for free-text mode. You may attach up to five images with images[] in this mode. When options are provided, only those options are compared in their original order; images[] cannot be combined with options; null and empty arrays are invalid.
Text data must be non-empty; image data should be an image URL or supported image data URL; audio data should include mime_type when ambiguous.
Put current preferences, conditions and decision context in request_text. Internal user_context is not accepted from public callers.

Response details

No polling is required for Decide.
Both modes use the same result schema. options contains consecutive 1-based IDs and readable labels. selected_option references one of these IDs for outcome selected; otherwise it is null.
Failed responses contain status: failed, result: null and an error object.

Operational notes

Requires x-api-key with the edge:decide scope.
Usage is counted and rate-limit headers are returned when quota data is available.
The API is scoped to nutrition decisions. Missing information is described in reasoning with outcome needs_information; incompatible choices use no_valid_option.

Examples

Request JSON

{
  "request_text": "Oatmeal with berries or croissant and jam: which is better for steady energy?"
}

Response JSON

{
  "data": {
    "status": "completed",
    "result": {
      "outcome": "selected",
      "options": [{"id": 1, "label": "Oatmeal with berries"}, {"id": 2, "label": "Croissant and jam"}],
      "selected_option": 1,
      "reasoning": "Oatmeal is more likely to provide steady energy."
    },
    "error": null
  },
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-07-10"
  }
}

Code examples

curl -X POST 'https://api.mymolecules.de/functions/v1/decide' \
  -H "x-api-key: $MYMOLECULES_API_KEY" \
  -H 'mymolecules-api-version: 2026-07-10' \
  -H 'Content-Type: application/json' \
  --data '{  "request_text": "Oatmeal with berries or croissant and jam: which is better for steady energy?"}'

Try in playground