Endpoint

POST/functions/v1/design

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

type: recipe or meal_plan
Optional request_text for a free-form request or additional context
For meal plans, plan_days and meals_per_day
Optional preference, sensory, condition, compound and energy constraints

Returns

202 queued response with job_id and status_url
Completed recipe or meal_plan result after polling
Optional nutrient analysis and images when requested

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
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

One hybrid request can combine request_text with explicit fields such as recipe_count, diet, condition, compound_filters, daily_energy_kcal_min and daily_energy_kcal_max.
compound_filters items require compound or compound_id plus operator, threshold and unit; scope can be portion or day.
image_delivery can be base64, signed_url or none. Omit it when images are not needed.

Response details

Poll GET /functions/v1/design?job_id=... until status is completed or failed.
Recipe jobs return result.recipe; meal-plan jobs return result.meal_plan.
Queued and processing responses include retry_after_seconds in meta when available.

Operational notes

Requires x-api-key with the edge:design scope.
POST usage is counted and rate-limit headers are returned when quota data is available.
Condition-based requests may require gender so nutrition rules can be selected correctly.

Examples

Request JSON

{
  "type": "recipe",
  "request_text": "High-protein Mediterranean breakfast, gentle on digestion",
  "recipe_count": 1,
  "language": "English"
}

Response JSON

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

Code examples

curl -X POST 'https://api.mymolecules.de/functions/v1/design' \
  -H "x-api-key: $MYMOLECULES_API_KEY" \
  -H 'mymolecules-api-version: 2026-07-10' \
  -H 'Content-Type: application/json' \
  --data '{  "type": "recipe",  "request_text": "High-protein Mediterranean breakfast, gentle on digestion",  "recipe_count": 1,  "language": "English"}'

Try in playground