---
title: "Share a folder with people or teams"
description: "Gives people (by email) and teams access to everything in the folder that isn't private, now and later."
canonical_url: https://docs.markdrop.in/api/folders/share-a-folder-with-people-or-teams
last_updated: 2026-11-20
site: "Markdrop Docs"
index: https://docs.markdrop.in/llms.txt
---

# Share a folder with people or teams

`POST https://api.markdrop.in/api/v1/workspaces/{workspace_id}/folders/{folder_id}/access/share`

Gives people (by email) and teams access to everything in the folder that isn't private, now and later. Each person newly given access gets one email and one notification for the whole folder, never one per item.

- **Authentication:** API token required: `Authorization: Bearer mdk_…`.
- **Rate limit:** 30 per minute per IP address.
- **Guide:** [Folder access](https://docs.markdrop.in/workspaces/folder-access)

## Path parameters

- `workspace_id` (string, required): The workspace's id, from the address of its settings page (`markdrop.in/settings/workspaces/<workspace-id>`) or from [List workspaces](https://docs.markdrop.in/api/workspaces/list-workspaces).
- `folder_id` (string, required): The folder's id, from [List folders](https://docs.markdrop.in/api/folders/list-folders).

## Request body

`application/json`, required.

- `emails` (array of string): Up to 50 items.
- `team_ids` (array of string): Team ids, slugs or names. Up to 20 items.
- `role` ("viewer" | "editor"): Default `"viewer"`.
- `notify` (boolean): Default `true`.
- `message` (string): Up to 500 characters.
- `restrict` (boolean): Also restrict the folder to its people and teams (true), or lift the restriction (false). Absent: unchanged.

## Responses

- `200`: OK.
- `401`: No token, or the token is revoked or mistyped.
- `422`: The request didn't validate. `detail` lists each problem, with where it is (`loc`) and why (`msg`).
- `429`: Too many requests from your IP address. Wait the seconds in `Retry-After`.

## Examples

**curl**

```bash
curl -X POST https://api.markdrop.in/api/v1/workspaces/WORKSPACE_ID/folders/FOLDER_ID/access/share \
  -H "Authorization: Bearer $MARKDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "emails": [
         "sam@example.com"
       ],
       "team_ids": [
         "sales"
       ],
       "role": "viewer",
       "notify": true
     }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.markdrop.in/api/v1/workspaces/WORKSPACE_ID/folders/FOLDER_ID/access/share", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MARKDROP_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "emails": [
      "sam@example.com"
    ],
    "team_ids": [
      "sales"
    ],
    "role": "viewer",
    "notify": true
  }),
});
const data = await res.json();
```

**Python**

```python
import os

import requests

r = requests.post(
    "https://api.markdrop.in/api/v1/workspaces/WORKSPACE_ID/folders/FOLDER_ID/access/share",
    headers={"Authorization": f"Bearer {os.environ['MARKDROP_TOKEN']}"},
    json={
        "emails": ["sam@example.com"],
        "team_ids": ["sales"],
        "role": "viewer",
        "notify": True,
    },
)
r.raise_for_status()
print(r.json())
```
