> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Reusable ModuleX patterns that combine the Assistant, AI Composer, workflows, knowledge, and integrations to solve real problems. Each recipe shows what it combines, when to reach for it, and where to go next.

export const MediaEmbed = ({id, type = 'screenshot', caption = '', ext, ratio = '16 / 9'}) => {
  const isVideo = type === 'video' || type === 'app_video';
  const resolvedExt = ext || (isVideo ? 'mp4' : type === 'screenshot' ? 'webp' : 'svg');
  const src = 'https://media.modulex.dev/' + id + '.' + resolvedExt;
  const [status, setStatus] = useState('loading');
  const [isDev, setIsDev] = useState(false);
  const [inView, setInView] = useState(false);
  const boxRef = useRef(null);
  useEffect(() => {
    if (typeof window === 'undefined') return;
    const h = window.location.hostname;
    setIsDev(h === 'localhost' || h === '127.0.0.1' || h.endsWith('.mintlify.app'));
  }, []);
  useEffect(() => {
    if (inView) return;
    if (typeof IntersectionObserver === 'undefined') {
      setInView(true);
      return;
    }
    const el = boxRef.current;
    if (!el) return;
    const io = new IntersectionObserver(entries => {
      if (entries.some(e => e.isIntersecting)) {
        setInView(true);
        io.disconnect();
      }
    }, {
      rootMargin: '300px'
    });
    io.observe(el);
    return () => io.disconnect();
  }, [inView]);
  if (status === 'missing') {
    if (!isDev) return null;
    return <div style={{
      display: 'flex',
      flexDirection: 'column',
      justifyContent: 'center',
      gap: '0.4rem',
      padding: '1rem 1.25rem',
      margin: '1.25rem 0',
      width: '100%',
      aspectRatio: ratio,
      boxSizing: 'border-box',
      border: '1px dashed rgba(128,128,128,0.45)',
      borderRadius: '0.75rem',
      background: 'rgba(128,128,128,0.06)',
      color: 'currentColor',
      fontSize: '0.85rem',
      lineHeight: 1.45
    }}>
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '0.5rem',
      opacity: 0.75
    }}>
          <span aria-hidden="true">🎬</span>
          <code style={{
      fontSize: '0.75rem'
    }}>{id}</code>
          <span style={{
      fontSize: '0.65rem',
      textTransform: 'uppercase',
      letterSpacing: '0.04em',
      padding: '0.1rem 0.4rem',
      borderRadius: '0.4rem',
      background: 'rgba(128,128,128,0.18)'
    }}>
            {type}
          </span>
        </div>
        <div style={{
      opacity: 0.9
    }}>{caption || 'Media not uploaded yet.'}</div>
        <div style={{
      fontSize: '0.7rem',
      opacity: 0.5
    }}>
          Upload to R2 as <code>{id}.{resolvedExt}</code> — preview only, hidden in production.
        </div>
      </div>;
  }
  const mediaStyle = {
    display: status === 'loaded' ? 'block' : 'none',
    width: '100%',
    height: 'auto',
    borderRadius: '0.75rem'
  };
  const media = isVideo ? <video src={inView ? src : undefined} autoPlay loop muted playsInline preload="metadata" onLoadedData={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} /> : <img src={inView ? src : undefined} alt={caption} onLoad={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} />;
  return <figure style={{
    margin: '1.25rem 0'
  }}>
      <div ref={boxRef} style={status === 'loaded' ? {
    width: '100%'
  } : {
    width: '100%',
    aspectRatio: ratio,
    borderRadius: '0.75rem',
    background: 'rgba(128,128,128,0.06)'
  }}>
        {media}
      </div>
      {status === 'loaded' && caption ? <figcaption style={{
    marginTop: '0.5rem',
    textAlign: 'center',
    fontSize: '0.85rem',
    opacity: 0.7
  }}>
          {caption}
        </figcaption> : null}
    </figure>;
};

A recipe is a proven combination of ModuleX features that solves one real problem. Each one below names the pieces it stitches together — the [Assistant](/concepts/assistant), the [AI Composer](/concepts/ai-composer), a [workflow](/concepts/workflows-and-runs), your [knowledge](/concepts/knowledge-rag), and your [integrations](/integrations/overview) — tells you when to reach for it, and points to the guide or example that walks it end to end.

Use this page as a menu. Skim the cards, find the pattern closest to what you are trying to do, and follow the links into the step-by-step guides. For a single Assistant task carried out from prompt to result, see [Assistant examples](/assistant/examples). For a workflow run start to finish, see [run a workflow](/guides/run-a-workflow).

<MediaEmbed id="MX-MEDIA-4360" type="image" caption={"A recipe map showing the five core ModuleX building blocks (Assistant, AI Composer, workflow, knowledge, integrations) and lines connecting them into the recipes on this page."} />

## Pick a recipe

<CardGroup cols={2}>
  <Card title="Ask-and-act with the Assistant" icon="wand-sparkles" href="#ask-and-act-with-the-assistant">
    One plain-language request, several connected tools, a result. Best for one-off tasks across your services.
  </Card>

  <Card title="Prompt to running workflow" icon="bot-message-square" href="#prompt-to-a-running-workflow">
    Describe an automation in English, let the Composer build it on the canvas, then run it on demand or on a schedule.
  </Card>

  <Card title="Answer from your own documents" icon="book-open-text" href="#answer-from-your-own-documents">
    Ground the Assistant or a workflow in your knowledge bases so answers come from your content, not the open web.
  </Card>

  <Card title="Scheduled automation" icon="clock" href="#scheduled-automation">
    Run a workflow automatically on a cron schedule, or trigger it from your own code over the API.
  </Card>

  <Card title="Approve before acting" icon="shield-check" href="#approve-before-acting">
    Let an agent or workflow gather context and draft, then pause for a human to approve the one step that changes something.
  </Card>

  <Card title="Co-build with your team" icon="users" href="#co-build-with-your-team">
    Two or more people edit the same workflow on one canvas in realtime, with the Composer helping alongside.
  </Card>
</CardGroup>

## How to read each recipe

Every recipe follows the same shape, so once you have read one you can skim the rest.

<CardGroup cols={3}>
  <Card title="What it combines" icon="puzzle">
    The ModuleX features the recipe stitches together — the parts you already know from the [feature map](/power-using/feature-map).
  </Card>

  <Card title="When to use it" icon="target">
    The kind of problem this pattern is the right fit for, and when a different recipe would serve you better.
  </Card>

  <Card title="Where to go next" icon="arrow-right">
    The guide, example, or concept page that walks the pattern end to end.
  </Card>
</CardGroup>

***

## Ask-and-act with the Assistant

The simplest recipe. You type one request in plain language and the [Assistant](/concepts/assistant) does it — reading from your connected services, deciding the next step, and calling one tool at a time until the task is done.

**What it combines:** the [Assistant](/assistant/overview) and your [connected integrations](/integrations/overview). No workflow, no canvas, no setup beyond connecting the services you want it to use.

**When to use it:** a one-off task that does not need to run again. "Summarize the newest issues in this repo," "draft a reply to the latest support email," "pull these numbers and tell me what stands out." If you find yourself asking for the same thing repeatedly, graduate to the next recipe and turn it into a workflow.

<Steps>
  <Step title="Connect the services it needs">
    The Assistant can only use tools you have connected. If a request needs a service you have not added, it asks you to connect it right inside the chat — see [connect an integration](/guides/connect-an-integration).
  </Step>

  <Step title="Ask in plain language">
    Send one message that names what to find and what to do with it. One message starts one [turn](/assistant/how-it-works).
  </Step>

  <Step title="Watch it work">
    The Assistant [streams its progress live](/assistant/streaming): which tool it is calling, what it found, and what it plans next. If a step would change or send something, it pauses for your approval first (see [approve before acting](#approve-before-acting)).
  </Step>
</Steps>

<Card title="Where to go next" icon="arrow-right" href="/assistant/examples">
  Four Assistant tasks worked end to end — research and summarize, inbox triage, draft and send, and a multi-tool task.
</Card>

***

## Prompt to a running workflow

When a task is worth repeating, turn it into a [workflow](/concepts/workflows-and-runs). The fastest way to build one is to describe it in plain English and let the [AI Composer](/concepts/ai-composer) generate an editable workflow graph on the canvas — then you refine it and run it as often as you like.

**What it combines:** the [AI Composer](/workflow-builder/composer) to build, the [workflow builder](/workflow-builder/overview) canvas to refine, and [integrations](/integrations/overview) or [LLM nodes](/workflow-builder/nodes/overview) to do the work.

**When to use it:** any task you will run more than once, or that has more than a couple of steps, or that you want to trigger on a schedule or from code later. Unlike a one-off Assistant request, a workflow is saved, versioned, and reusable.

<Steps>
  <Step title="Describe the automation">
    Tell the Composer what you want in plain language. It turns your description into a complete, editable workflow graph — nodes, connections, and all.
  </Step>

  <Step title="Refine on the canvas">
    Adjust the generated graph: swap a model, add a [tool node](/workflow-builder/nodes/tool), branch with a [conditional](/workflow-builder/nodes/conditional), or keep chatting with the Composer to make changes for you.
  </Step>

  <Step title="Run it">
    Run the workflow from the builder and watch the live result, or call it from chat, the API, or an SDK. See [run a workflow](/guides/run-a-workflow).
  </Step>
</Steps>

<Card title="Where to go next" icon="arrow-right" href="/guides/build-with-composer">
  Build a workflow with Composer — from a plain-English prompt to a running workflow, step by step.
</Card>

***

## Answer from your own documents

Make the Assistant or a workflow answer from your content — policies, product docs, past tickets — instead of guessing. ModuleX retrieves the relevant passages from your [knowledge bases](/concepts/knowledge-rag) and grounds the answer in them.

**What it combines:** a [knowledge base](/platform/knowledge/overview) (managed or your own vector store) plus either the [Assistant](/assistant/overview) or a [knowledge node](/workflow-builder/nodes/knowledge) inside a workflow.

**When to use it:** any question where the right answer lives in your own documents. Support replies that must match your policies, internal Q\&A over a handbook, or a workflow step that needs company context before it drafts. Reach for this whenever a generic model answer is not good enough because it does not know your specifics.

<Steps>
  <Step title="Build a knowledge base">
    Create a knowledge base and upload your documents. ModuleX parses, chunks, and indexes them for retrieval — see [build a RAG knowledge base](/guides/build-a-knowledge-base).
  </Step>

  <Step title="Point a question at it">
    Ask the Assistant something like "Summarize what our onboarding guide says about SSO," or drop a [knowledge node](/workflow-builder/nodes/knowledge) into a workflow to retrieve context for a later step.
  </Step>

  <Step title="Get a grounded answer">
    The answer comes from your documents, with the retrieved context behind it. For chat-style use, see [chat with your knowledge](/platform/chat/knowledge-chat).
  </Step>
</Steps>

<Note>
  Searching managed knowledge (the ModuleX-hosted vector store) uses a small amount of credit per retrieval. Bringing your own vector store is not metered in credits. See [credits and metering](/billing/credits).
</Note>

<Card title="Where to go next" icon="arrow-right" href="/guides/build-a-knowledge-base">
  Create a knowledge base, ingest documents, and query it.
</Card>

***

## Scheduled automation

Once a workflow does the right thing, you rarely want to press Run by hand. This recipe makes it happen on its own — on a clock, or triggered by your own systems.

**What it combines:** a saved [workflow](/concepts/workflows-and-runs) plus either a [schedule](/workflow-builder/execution/schedule) or a call to the [run API](/workflow-builder/execution/api-endpoint).

**When to use it:** recurring jobs (a daily digest, a weekly report, an overnight sync) belong on a schedule. Event-driven jobs (run this when an order is placed, when a form is submitted) belong on an API trigger from the system that knows about the event.

<Tabs>
  <Tab title="On a schedule">
    Attach a cron schedule to a workflow and ModuleX runs it for you. A daily summary, a Monday-morning report, an hourly check — all set up once and left alone.

    Schedules and other automated runs require an organization **owner** or **admin** role. See [organizations, roles & membership](/concepts/organizations-roles).

    <Card title="Where to go next" icon="arrow-right" href="/guides/schedule-a-workflow">
      Schedule a workflow to run automatically on a cron schedule.
    </Card>
  </Tab>

  <Tab title="From your own code">
    Trigger a workflow from anywhere with one authenticated call. Every request carries `Authorization: Bearer mx_live_…` plus your `X-Organization-ID`. The call returns a `run_id` you can then stream over [SSE](/realtime/sse-streaming).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.modulex.dev/workflows/run \
        -H "Authorization: Bearer mx_live_xxx" \
        -H "X-Organization-ID: 11111111-1111-1111-1111-111111111111" \
        -H "Content-Type: application/json" \
        -d '{"workflow_id": "wf_123", "input": {"topic": "weekly digest"}}'
      # → {"status": "running", "run_id": "6a7b...", "thread_id": "550e..."}
      ```

      ```python Python theme={null}
      from modulex import Modulex

      client = Modulex(
          api_key="mx_live_xxx",
          organization_id="11111111-1111-1111-1111-111111111111",
      )

      run = await client.executions.run(
          workflow_id="wf_123",
          input={"topic": "weekly digest"},
      )
      print(run.run_id)
      ```

      ```javascript JavaScript theme={null}
      import { Modulex } from "modulex-js";

      const client = new Modulex({
        apiKey: "mx_live_xxx",
        organizationId: "11111111-1111-1111-1111-111111111111",
      });

      const run = await client.executions.run({
        workflowId: "wf_123",
        input: { topic: "weekly digest" },
      });
      console.log(run.runId);
      ```
    </CodeGroup>

    A run on a charged surface can be turned away by the [billing gate](/billing/usage-gating) with a `402`, `403`, or `429` response before any work starts — handle that in your trigger. See [run a workflow](/guides/run-a-workflow) for the full walkthrough.
  </Tab>
</Tabs>

***

## Approve before acting

The safest way to let automation touch the real world: have it gather context and prepare the change, then stop and wait for a person to say yes. ModuleX calls this [human-in-the-loop](/assistant/human-in-the-loop).

**What it combines:** an approval pause — the [Assistant](/assistant/overview) stopping before a sensitive action, or an [interrupt node](/workflow-builder/nodes/interrupt) inside a workflow — plus whatever tools do the reading and the writing.

**When to use it:** any time a step sends a message, creates or deletes a record, charges money, or otherwise changes something you would not want done without a look first. Combine it with [ask-and-act](#ask-and-act-with-the-assistant) for one-off tasks, or with a [workflow](#prompt-to-a-running-workflow) for repeatable ones.

<Steps>
  <Step title="Let it prepare">
    The agent or workflow reads what it needs and drafts the change — a reply, a ticket, an update — without committing it yet.
  </Step>

  <Step title="Pause for a person">
    Before the step that writes, it pauses and shows exactly what it is about to do on an approval card. Only the person who started the turn can answer.
  </Step>

  <Step title="Approve, edit, or decline">
    Approve to let it proceed, reply with a change to have it revise and ask again, or decline to stop. Nothing risky happens until you approve.
  </Step>
</Steps>

<Warning>
  The Assistant always pauses before a sensitive action — a draft is never sent and a record is never created until you approve it. In a workflow, you add this pause yourself with an [interrupt node](/workflow-builder/nodes/interrupt). See [human-in-the-loop](/assistant/human-in-the-loop) for the question and approval kinds.
</Warning>

<Card title="Where to go next" icon="arrow-right" href="/assistant/examples">
  See the "draft and send" example for the canonical pause-before-acting pattern.
</Card>

***

## Co-build with your team

Workflows are not a solo activity. Several people can edit the same canvas at the same time, see each other's cursors and selections, and let the Composer make changes alongside everyone — all in realtime.

**What it combines:** [realtime co-editing](/platform/collaboration/canvas) on the canvas plus the [AI Composer](/workflow-builder/composer) editing the same workflow.

**When to use it:** building or reviewing a workflow as a team, walking a teammate through an automation, or pairing with the Composer while a colleague refines another part of the graph. Edits sync live, with presence and node locks so two people do not fight over the same node.

<Steps>
  <Step title="Open the same workflow">
    Invite a teammate and open the workflow on the canvas. You both see who is present and where they are working.
  </Step>

  <Step title="Edit together">
    Changes appear for everyone as they happen. Node locks keep two people from editing the exact same node at once.
  </Step>

  <Step title="Let the Composer help">
    Ask the Composer to make a change and it edits the live workflow; the update syncs to every collaborator on the canvas. This works over the Socket.io collaboration channel — see [realtime & collaboration model](/concepts/realtime-model).
  </Step>
</Steps>

<Card title="Where to go next" icon="arrow-right" href="/guides/realtime-collaboration">
  Invite a teammate and co-edit a workflow live.
</Card>

***

## Combine recipes

The best results come from chaining recipes. A few patterns worth knowing:

<AccordionGroup>
  <Accordion title="Grounded, scheduled digest" icon="newspaper">
    Build a workflow with the [Composer](/guides/build-with-composer), give it a [knowledge node](/workflow-builder/nodes/knowledge) so it pulls from your own documents, then put it on a [schedule](/guides/schedule-a-workflow). Result: a recurring digest written from your content, with no one pressing Run.
  </Accordion>

  <Accordion title="Triage then act, with a checkpoint" icon="list-checks">
    Start with [ask-and-act](#ask-and-act-with-the-assistant) to sort an inbox, then ask the Assistant to take action on the top items. The [approve-before-acting](#approve-before-acting) pause kicks in automatically the moment a step would change something.
  </Accordion>

  <Accordion title="One-off proven, then promoted" icon="trending-up">
    Solve a problem once with the [Assistant](/assistant/examples). When you find yourself asking for the same thing again, hand the prompt to the [Composer](/concepts/ai-composer) to turn it into a reusable, schedulable workflow.
  </Accordion>
</AccordionGroup>

## Keep going

<CardGroup cols={2}>
  <Card title="Feature map" icon="map" href="/power-using/feature-map">
    Every ModuleX feature, what it does, and where to use it — the building blocks behind these recipes.
  </Card>

  <Card title="Optimization" icon="gauge" href="/power-using/optimization">
    Tune your workflows and usage for speed, reliability, and cost.
  </Card>

  <Card title="Assistant examples" icon="messages-square" href="/assistant/examples">
    Four Assistant tasks worked end to end, ready to copy and adapt.
  </Card>

  <Card title="Run a workflow" icon="play" href="/guides/run-a-workflow">
    Authenticate, run a workflow, and stream the result in three languages.
  </Card>
</CardGroup>