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

# Organization API

> Tags, folders, folder ACL requests, and UTM template management

# Organization API

Organization APIs provide taxonomy and access structure for links.

## Endpoint matrix

### Tags

| Method   | Path              | Purpose                    |
| -------- | ----------------- | -------------------------- |
| `GET`    | `/tags`           | List tags                  |
| `POST`   | `/tags`           | Create tag                 |
| `PATCH`  | `/tags/:id`       | Update tag                 |
| `DELETE` | `/tags/:id`       | Delete tag                 |
| `GET`    | `/tags/:id/links` | List links assigned to tag |

### Folders

| Method   | Path                                              | Purpose                 |
| -------- | ------------------------------------------------- | ----------------------- |
| `GET`    | `/folders`                                        | List folders            |
| `POST`   | `/folders`                                        | Create folder           |
| `PATCH`  | `/folders/:id`                                    | Update folder           |
| `DELETE` | `/folders/:id`                                    | Delete folder           |
| `GET`    | `/folders/:id/users`                              | List folder users/roles |
| `POST`   | `/folders/:id/users`                              | Add folder user         |
| `PATCH`  | `/folders/:id/users/:userId`                      | Update folder user role |
| `DELETE` | `/folders/:id/users/:userId`                      | Remove folder user      |
| `POST`   | `/folders/:id/access-requests`                    | Submit access request   |
| `GET`    | `/folders/:id/access-requests`                    | List pending requests   |
| `POST`   | `/folders/:id/access-requests/:requestId/approve` | Approve request         |
| `POST`   | `/folders/:id/access-requests/:requestId/reject`  | Reject request          |

### UTM templates

| Method   | Path                 | Purpose         |
| -------- | -------------------- | --------------- |
| `GET`    | `/utm-templates`     | List templates  |
| `POST`   | `/utm-templates`     | Create template |
| `PATCH`  | `/utm-templates/:id` | Update template |
| `DELETE` | `/utm-templates/:id` | Delete template |

## Key behavior notes

* Tag names are unique per workspace.
* Folder parent validation prevents invalid self-parent structures.
* Deleting a folder automatically detaches links from that folder (`folderId` becomes `null`).
* Folder role updates/removals are owner-gated at folder level.
* UTM templates are stored as reusable parameter presets.

## Permission model

* Reads require `links:read`.
* Creates typically require `links:create`.
* Mutations generally require `links:update`/`links:delete`.
* Folder user/admin operations require both workspace permission and folder-level access checks.

## Plan limit gates

* tag count
* folder count
* UTM template count

When over limit, create endpoints return limit errors until resources are reduced or plan is upgraded.

## Typical failures

* `404 NOT_FOUND`: folder/tag/template missing
* `409 CONFLICT`: duplicate tag name or duplicate access request
* `403 FORBIDDEN`: insufficient folder-level permission
* `400 BAD_REQUEST`: invalid parent/self-folder assignment

Related docs:

* `/user-guides/manual/growth/tags-folders-utm-reference`
* `/user-guides/manual/workspace/workspaces-and-access`