Interested in joining a scientific study?Learn more

API documentation

Build with the MyMolecules API surface.

Public reference for the current partner APIs. The docs are visible without login; the playground requires an approved MyMolecules website account.

For Companies Open playground

Getting started

One account, public docs, approved playground access.

The API documentation is public so product and engineering teams can understand the capabilities before registering. Interactive calls go through Supabase Auth and the MyMolecules proxy functions after admin approval.

V1 access modelNo self-service API key dashboard yet. Website access is approved by an admin, then the playground uses the user session to call the proxy functions.

Authentication

Use Supabase Auth for the playground.

Public docs do not need a session. Playground calls require a Supabase user whose mymolecules_website profile is approved. The browser only receives publishable Supabase configuration; service-role keys stay inside Edge Functions.

Authorization: Bearer <supabase_access_token>
apikey: <supabase_publishable_key>
Content-Type: application/json

Async jobs

Most heavy workflows return a job or run id.

Decode, Decode Sensory, Design, Decode Symptoms, Detect, Discover and Draft can return queued work. Poll the proxy with job_id or run_id until the response reaches a final status.

{
  "job_id": "8a93f4...",
  "status": "queued",
  "status_url": "https://.../functions/v1/decode_proxy?job_id=8a93f4..."
}

decode_proxy

Decode API

Decode turns everyday food input into structured food items, quantities, reusable Decode Food IDs and molecular nutrition output. It is the base layer for products that need to understand what a person ate beyond calories and macros.

Inputs

Natural language meal descriptions, food images or voice input
Structured food items with names and quantities
Existing decode_food_id values for repeat analysis

Returns

Recognized foods and estimated quantities
Reusable decode_food_id references
Molecular analysis with compounds, values, units and references

Request JSON

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

Response JSON

{
  "job_id": "8a93f4...",
  "status": "queued",
  "status_url": "https://.../functions/v1/decode_proxy?job_id=8a93f4..."
}

Try in playground Back to For Companies

decode_sensory_proxy

Decode Sensory API

Decode Sensory adds a sensory layer to food understanding. It can describe taste, aroma, texture and whole-meal sensory impressions from the current supported fields.

Inputs

foodText, foodImage or foodVoice
sensoryOutput for the requested sensory view

Returns

Per-food sensory interpretation
Whole-meal sensory summaries
Structured sensory terms for product logic

Request JSON

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

Response JSON

{
  "job_id": "49ad2c...",
  "status": "queued",
  "status_url": "https://.../functions/v1/decode_sensory_proxy?job_id=49ad2c..."
}

Try in playground Back to For Companies

design_proxy

Design API

Design turns nutrition goals, restrictions, sensory preferences and molecular constraints into usable recipes or meal plans. It can work from structured fields or from a simple text request.

Inputs

Recipe or meal-plan type
Unstructured request_text or structured preferences
Diet, taste, restriction, compound and energy constraints

Returns

Recipes with ingredients and steps
Meal plans with days and meals
Generation status and retry metadata

Request JSON

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

Response JSON

{
  "job_id": "d72f91...",
  "status": "queued",
  "status_url": "https://.../functions/v1/design_proxy?job_id=d72f91..."
}

Try in playground Back to For Companies

decode_symptoms_proxy

Decode Symptoms API

Decode Symptoms structures free-text, image or voice symptom reports into consistent symptom events with labels, intensity and timing context.

Inputs

symptomText, symptomImage or symptomVoice
Optional timing fields such as timezone and reported_time

Returns

Structured symptom labels
Intensity and duration fields where available
Timing metadata and clarification status

Request JSON

{
  "symptomText": "Felt bloated and tired about two hours after dinner",
  "timezone": "Europe/Berlin"
}

Response JSON

{
  "job_id": "cb08a1...",
  "status": "queued",
  "status_url": "https://.../functions/v1/decode_symptoms_proxy?job_id=cb08a1..."
}

Try in playground Back to For Companies

detect_proxy

Detect API

Detect analyzes a user-specific time window to look for plausible relationships between nutrition events, symptoms and contextual health signals.

Inputs

question_text
User context and optional analysis time window
Existing food and symptom history

Returns

Async analysis status
Pattern candidates
Evidence summaries and follow-up opportunities

Request JSON

{
  "question_text": "What in my recent food logs may be linked to bloating?",
  "timezone": "Europe/Berlin",
  "context": {
    "lookback_days": 14
  }
}

Response JSON

{
  "job_id": "a19cb5...",
  "status": "queued",
  "status_url": "https://.../functions/v1/detect_proxy?job_id=a19cb5..."
}

Try in playground Back to For Companies

discover_proxy

Discover API

Discover is the conversation layer. It can interpret a user message, decide which tools are needed, coordinate Decode, Decode Symptoms, Detect, Design or Draft and return a public assistant response.

Inputs

text
client_message_id
Optional conversation_id
Optional attachments for image, audio or PDF context

Returns

assistant_message
run_id and status_url
Artifact references such as recipes or analysis results

Request JSON

{
  "text": "I felt bloated after dinner yesterday. Can you help me understand what might matter?",
  "client_message_id": "client-msg-001"
}

Response JSON

{
  "run_id": "0d78a2...",
  "status": "processing",
  "status_url": "https://.../functions/v1/discover_proxy?run_id=0d78a2...",
  "assistant_message": {
    "role": "assistant",
    "text": "I am checking the recent context."
  }
}

Try in playground Back to For Companies

draft_proxy

Draft API

Draft takes an existing recipe or meal idea and creates controlled substitutions or edits while respecting preferences, restrictions and sensory goals.

Inputs

input_mode structured or unstructured
request_text or edit_instructions
Recipe title, ingredients and steps

Returns

Recipe diffs and substitutions
Warnings and validation feedback
Async job status when queued

Request JSON

{
  "input_mode": "unstructured",
  "request_text": "Make this tomato pasta higher protein and lactose-free.",
  "recipe_title": "Tomato pasta",
  "ingredients": ["pasta", "tomato sauce", "parmesan"],
  "steps": ["Cook pasta", "Warm sauce", "Serve with parmesan"]
}

Response JSON

{
  "job_id": "f13e52...",
  "status": "queued",
  "status_url": "https://.../functions/v1/draft_proxy?job_id=f13e52..."
}

Try in playground Back to For Companies

decide_proxy

Decide API

Decide evaluates explicit food, meal, drink or ingredient options using text, image or audio inputs and optional user context.

Inputs

inputs[] with type text, image or audio
Optional user_context such as diet, language or avoided foods

Returns

A concise answer_text recommendation
Completed status or validation errors

Request JSON

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

Response JSON

{
  "status": "completed",
  "result": {
    "answer_text": "Choose option A. It is more likely to provide steady energy."
  },
  "error": null
}

Try in playground Back to For Companies