---
title: "Mint an expiring share-link for a whole folder subtree"
method: POST
path: "/api/folders/grant"
tags: ["files"]
---

# Mint an expiring share-link for a whole folder subtree

`POST /api/folders/grant`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/folders/grant`
- Auth: HTTP bearer

Clerk session or agt_ token with `files:write` (live tier re-checked). Owner or operator only. One link admits a non-member to the folder, every subfolder under it, and every file inside — resolve it with GET /api/folders/shared?grant=<token>. `ttl_seconds` defaults to 7 days.

## Request body

- FolderGrantRequest
  - `folder_id` string, required
  - `subject` string: Free-text audit label. NOT authenticated.
  - `ttl_seconds` integer: Defaults to 7 days.

## Response `200`

Signed folder share-link.

- FolderGrantResponse
  - `ok` boolean, required
  - `folder_id` string, required
  - `name` string, required
  - `token` string, required: The signed grant. Admits to this folder and its whole subtree.
  - `link` string, required: Human-facing share URL.
  - `view_url` string: Same as `link`; provided for clarity.
  - `expires_at` string, date-time, required

## Other responses

- `400`: Invalid JSON.
- `401`: No auth.
- `403`: Not the owner and not an operator.
- `404`: folder_id names no folder.
- `500`: Grant signing failed.
- `503`: Sharing not configured (FILES_GRANT_SECRET missing).

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)