> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Organizations

An **organization** is a tenant inside one of your accounts. It is the boundary that everything else lives in: workspaces, documents (and their folders), and tools all belong to an organization.

```
Account  (X-Account-Id)
└── Organization
    ├── Workspaces      — chat/RAG environments + integrations
    ├── Documents       — uploaded files, organized in folders
    └── Tools           — reusable HTTP actions
```

## What an organization owns

* **Workspaces** — the chat/RAG environments end users interact with. See [Workspaces](/documentation/core-concepts/workspaces).
* **Documents & folders** — files uploaded once at the org level and shared across every workspace in the org. See [Documents & knowledge base](/documentation/core-concepts/documents).
* **Tools** — HTTP actions defined once and attached to any workspace in the org. See [Tools](/documentation/core-concepts/tools).

> **Info**
>
> Documents and tools are **org-owned and shared**. You upload a document or define a tool once per organization, then opt individual workspaces in (by embedding the document or attaching the tool). You do not re-upload a file for each workspace.

## Addressing and scoping

An organization is addressed by its `id` (a UUID) in the URL — for example `GET /v1/organizations/{orgId}`. Every organization call also requires the `X-Account-Id` header of the account that owns it. An org id that does not belong to the account in the header resolves to `404`.

* List an account's orgs: `GET /v1/organizations`
* Read one org: `GET /v1/organizations/{orgId}`

The org detail returns its parent account context (`accountId`, `accountName`) and `counts` of its workspaces and tools. The collections themselves have their own endpoints — details carry counts, not inlined lists.

## Lifecycle

| Action | Endpoint                           | Notes                                                                       |
| ------ | ---------------------------------- | --------------------------------------------------------------------------- |
| Create | `POST /v1/organizations`           | `name` must be 4–80 characters. Names do not need to be unique.             |
| Rename | `PATCH /v1/organizations/{orgId}`  |                                                                             |
| Delete | `DELETE /v1/organizations/{orgId}` | Removes the organization and the resources under it. This cannot be undone. |

> **Warning**
>
> Deleting an organization is destructive and irreversible — its workspaces, documents, and tools go with it. Delete with care.