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

inputs[] with one or more text, image or audio entries
Each input requires type and data; label and mime_type are optional

Returns

Synchronous 200 response with status completed
result.answer_text with the recommendation
Structured failed response for validation or upstream errors

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 inputs[] with typed text, image or audio entries. Top-level input_type, data and audio_format are not part of the documented contract.
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 or decision context in a text input.

Response details

No polling is required for Decide.
Successful responses always contain status: completed, result.answer_text and error: 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 concrete nutrition decisions between explicit options.

Examples

Request JSON

{
  "inputs": [
    {
      "type": "text",
      "label": "meal options",
      "data": "Option A: oatmeal with berries. Option B: croissant and jam."
    },
    {
      "type": "text",
      "label": "decision context",
      "data": "Prefer steady energy"
    }
  ]
}

Response JSON

{
  "data": {
    "status": "completed",
    "result": {
      "answer_text": "Choose option A. It 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 '{  "inputs": [    {      "type": "text",      "label": "meal options",      "data": "Option A: oatmeal with berries. Option B: croissant and jam."    },    {      "type": "text",      "label": "decision context",      "data": "Prefer steady energy"    }  ]}'

Try in playground