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

# Shared and org-visible chats

> How chats become visible to your whole organization, who can see what, and how teams collaborate around shared conversations in ModuleX.

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

Every chat in ModuleX lives inside an organization. By default a chat is visible to everyone in that organization, so your team can read the same conversations, pick up where a teammate left off, and keep a shared record of what the Assistant and your workflows produced. When you need privacy, you can keep a chat to yourself instead.

This page explains how chat visibility works, who can see and change what, and how your team collaborates around the chats you share. For the simpler "just me vs. my org" toggle, see [Private and org chat](/platform/chat/private-org-chat).

<Note>
  Chat visibility is per chat, not per message. A chat is either visible to your whole organization or kept private to you — there is no per-message sharing.
</Note>

<MediaEmbed id="MX-MEDIA-3430" type="app_video" caption={"Two teammates working with the same org-visible chat."} />

## How chat visibility works

Each chat carries a single visibility setting. There are two states, and the difference is who in your organization can open the chat.

<CardGroup cols={2}>
  <Card title="Org-visible (shared)" icon="users">
    The default. Every member of the organization can find the chat in their sidebar, open it, and read the whole transcript. This is what lets your team collaborate.
  </Card>

  <Card title="Private" icon="lock">
    Only the person who created the chat can see it. It never appears for other members, even those with higher roles. Use this for drafts and personal work.
  </Card>
</CardGroup>

When you list your chats, you see the union of two sets:

<Steps>
  <Step title="Every shared chat in your organization">
    All org-visible chats appear for you, no matter who created them.
  </Step>

  <Step title="Your own private chats">
    Private chats appear only for their creator — so your private chats show up for you and for no one else.
  </Step>
</Steps>

The result: a shared chat is a true team artifact, while a private chat stays personal until you choose to share it.

<Frame caption="Org-visible chats are listed for everyone in the organization; private chats are listed only for their creator.">
  <MediaEmbed id="MX-MEDIA-3431" type="image" caption={"Visibility diagram for shared vs. private chats."} />
</Frame>

## Sharing a chat

Sharing is simply a matter of visibility. A chat starts as org-visible by default, so most of the time your team can already see it. If a chat is private, you make it shared by turning privacy off.

<Steps>
  <Step title="Open the chat you want to share">
    Find it in your chat history and open it. Only the creator of a private chat can change its visibility, so open a chat you created.
  </Step>

  <Step title="Turn privacy off">
    Switch the chat from private to org-visible. From that moment, every member of your organization can open it and read the full transcript.
  </Step>

  <Step title="Tell your teammates where to look">
    The chat now shows up in everyone's sidebar in your organization. Teammates can open it, read along, and continue the conversation with the [Assistant](/concepts/assistant).
  </Step>
</Steps>

<Warning>
  Only the **creator** of a private chat can change its visibility or its title. If a chat was created by someone else and kept private, you will not see it at all — and there is no way to request access from inside the chat. Ask the creator to make it org-visible.
</Warning>

To make a chat private again, the creator turns privacy back on. It immediately disappears from every other member's sidebar.

<Note>
  Switching a chat to private does not delete the messages your teammates already read — it just stops the chat from appearing for anyone other than you going forward.
</Note>

## Org visibility in practice

Org-visible chats are how a team builds shared context. Because the transcript includes the Assistant's reasoning, the tools it called, and any workflow output captured in the conversation, a shared chat doubles as a record of work.

<CardGroup cols={2}>
  <Card title="Hand off in progress" icon="arrow-right-left">
    Start a conversation, then let a teammate open the same chat and continue it. The full history travels with the chat.
  </Card>

  <Card title="Review what ran" icon="receipt">
    A chat keeps the messages produced when a workflow ran from it, so the team can see what happened without re-running anything. See [Run a workflow from chat](/platform/chat/workflow-run).
  </Card>

  <Card title="Share an answer" icon="share">
    Got a useful answer from your [knowledge bases](/platform/chat/knowledge-chat)? Keep the chat org-visible so others can read the same sourced answer.
  </Card>

  <Card title="Keep drafts personal" icon="pencil">
    Experiment privately, then share only the chats worth keeping. Private chats never leak into the shared list.
  </Card>
</CardGroup>

### What everyone in the org can do with a shared chat

<AccordionGroup>
  <Accordion title="Read the full transcript" icon="book-open">
    Any member can open an org-visible chat and read every message, including the Assistant's tool calls and outputs.
  </Accordion>

  <Accordion title="Continue the conversation" icon="message-circle-plus">
    Members can send new messages in a shared chat and keep it moving. The chat stays the same conversation thread throughout.
  </Accordion>

  <Accordion title="Organize it for themselves" icon="folder">
    Each member can file a shared chat into their own folders. Your folder labels are yours alone and never change how the chat looks for anyone else — see [Folders are personal](#folders-are-personal-to-you) below.
  </Accordion>

  <Accordion title="Delete a shared chat" icon="trash-2">
    For an org-visible chat, any member can delete it. Deleting a shared chat removes it for the whole organization, so coordinate before you do. A private chat can only be deleted by its creator.
  </Accordion>
</AccordionGroup>

<Note>
  Renaming and changing visibility behave differently from the actions above. The **title** and the **private/org-visible** setting of a private chat can only be changed by its creator. For an org-visible chat, members can rename and delete, but turning a chat back to private is still a creator-only action.
</Note>

## Folders are personal to you

Folders help you organize your chat history, and they are scoped to you. When you file a chat into a folder such as `pinned`, `work`, or `archived`, that assignment applies only to your view. A teammate looking at the same shared chat sees it in their own folder layout — by default the `chats` folder — not in yours.

<CardGroup cols={2}>
  <Card title="Your labels, your view" icon="user">
    Filing a shared chat into a folder changes nothing for other members. Everyone organizes the same shared chats independently.
  </Card>

  <Card title="No team-wide folders" icon="folder-tree">
    There is no shared folder structure across the organization. Folders are a personal convenience, not a team taxonomy.
  </Card>
</CardGroup>

For the full rundown of organizing chats, see [History and folders](/platform/chat/history-folders).

## Roles: who can collaborate on chats

Access to chats is governed by your role in the organization. ModuleX organizations have two roles, and both are recognized for working with chats.

<CardGroup cols={2}>
  <Card title="Owner" icon="crown">
    Full control of the organization, including billing and membership. Owners can use and collaborate on chats like admins.
  </Card>

  <Card title="Admin" icon="shield">
    Day-to-day administration and full use of ModuleX, including chats, the Assistant, and workflows.
  </Card>
</CardGroup>

<Warning>
  ModuleX organizations recognize only the **owner** and **admin** roles for chat collaboration. The older `member` role is retired — it is no longer a current role, and using chats (along with the [Assistant](/concepts/assistant) and the AI Composer) requires owner or admin. You may still see `member` referenced on older invitations or legacy records, but treat owner and admin as the live roles. See [Organizations, roles and membership](/concepts/organizations-roles) and [Roles and permissions](/security/roles-permissions).
</Warning>

Within those roles, two finer-grained rules still apply to individual chats, independent of role:

<Steps>
  <Step title="Creator-only privacy and renaming on private chats">
    Only the creator of a private chat can rename it or change whether it is private. Role does not override this — an owner cannot rename another person's private chat, because they cannot see it.
  </Step>

  <Step title="Org-visible chats are open to the org">
    Once a chat is org-visible, any member of the organization (owner or admin) can read it, continue it, file it into their own folders, and delete it.
  </Step>
</Steps>

## Where chats come from

You never create a chat by itself. A chat is created for you the first time you send a message — to the [Assistant](/concepts/assistant), when [running a workflow from chat](/platform/chat/workflow-run), or when [chatting with your knowledge](/platform/chat/knowledge-chat). The chat then holds that conversation, and its visibility settings decide who on your team can see it.

Because of this, sharing is something you do to an existing conversation: you start chatting, then decide whether to keep the chat to yourself or open it to your organization.

## Working with chat visibility from the API

Most teams manage chat sharing right in the app. If you automate around chats, you can also read chats and change a chat's visibility, title, or folder over the API. Every request authenticates with an [API key](/api-reference/authentication) and names the organization with the `X-Organization-ID` header. These operations require the **owner** or **admin** role.

<Note>
  Chats are created by running the Assistant or a workflow, not by a manual create call — there is no endpoint to create an empty chat. See [Known limitations](/reference/known-limitations).
</Note>

List the chats you can see (every org-visible chat in the organization, plus your own private chats):

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.modulex.dev/chats \
    -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "X-Organization-ID: org_xxxxxxxxxxxxxxxx"
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.get(
      "https://api.modulex.dev/chats",
      headers={
          "Authorization": "Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
          "X-Organization-ID": "org_xxxxxxxxxxxxxxxx",
      },
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.modulex.dev/chats", {
    headers: {
      Authorization: "Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
      "X-Organization-ID": "org_xxxxxxxxxxxxxxxx",
    },
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  console.log(await resp.json());
  ```
</CodeGroup>

The response groups chats by your personal folders. Each chat carries an `is_private` flag — `false` means org-visible (shared), `true` means private to its creator.

To share a private chat with your organization, turn privacy off by setting `is_private` to `false`. The same call can rename a chat or file it into one of your folders. Remember that changing privacy or the title of a private chat is creator-only.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X PATCH https://api.modulex.dev/chats/0a1b2c3d-1111-2222-3333-444455556666 \
    -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "X-Organization-ID: org_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"is_private": false, "folder": "team"}'
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.patch(
      "https://api.modulex.dev/chats/0a1b2c3d-1111-2222-3333-444455556666",
      headers={
          "Authorization": "Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
          "X-Organization-ID": "org_xxxxxxxxxxxxxxxx",
          "Content-Type": "application/json",
      },
      json={"is_private": False, "folder": "team"},
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch(
    "https://api.modulex.dev/chats/0a1b2c3d-1111-2222-3333-444455556666",
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
        "X-Organization-ID": "org_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ is_private: false, folder: "team" }),
    },
  );
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  console.log(await resp.json());
  ```
</CodeGroup>

<Note>
  The `folder` value sets your personal folder for that chat — it does not change how the chat is filed for anyone else. Setting `is_private` is the part that affects the whole team.
</Note>

If you try to act on a chat you cannot see — for example, a private chat created by someone else — the API responds as if the chat does not exist rather than telling you it is off-limits. For the full list of error shapes, see [Errors and status codes](/api-reference/errors).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I share a chat with only some people in my organization?">
    No. A chat is either visible to your whole organization or private to you. There is no per-person or per-group sharing. If you need to limit who sees a conversation, keep it private and copy out the parts you want to share.
  </Accordion>

  <Accordion title="Will my private chats ever show up for teammates?">
    No. Private chats are listed only for their creator. Even owners and admins do not see another member's private chats.
  </Accordion>

  <Accordion title="If I make a shared chat private again, does that hide messages people already saw?">
    It removes the chat from everyone else's sidebar going forward, but it cannot un-share what teammates have already read. Treat sharing as something people may have seen.
  </Accordion>

  <Accordion title="Who can delete a shared chat?">
    Any member of the organization can delete an org-visible chat, and it is removed for everyone. A private chat can be deleted only by its creator. Coordinate before deleting a shared chat your team relies on.
  </Accordion>

  <Accordion title="Do my folders affect my teammates?">
    No. Folders are personal. Filing a shared chat into a folder only changes your own view.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Private and org chat" icon="toggle-left" href="/platform/chat/private-org-chat">
    The quick toggle between a personal chat and an organization-visible one.
  </Card>

  <Card title="Organizations, roles and membership" icon="building" href="/concepts/organizations-roles">
    How organizations work and what owner and admin roles can do.
  </Card>

  <Card title="History and folders" icon="folder-clock" href="/platform/chat/history-folders">
    Organize your own chat history with folders that are private to you.
  </Card>

  <Card title="Canvas collaboration" icon="users-round" href="/platform/collaboration/canvas">
    Collaborate in realtime on a workflow canvas with your team.
  </Card>
</CardGroup>