---
title: "Mint an expiring share-link for one file"
method: POST
path: "/api/files/grant"
tags: ["files"]
---

# Mint an expiring share-link for one file

`POST /api/files/grant`

## Request

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

Clerk session or agt_ token with `files:write` (live tier re-checked). Only the file's uploader or an operator may share it. Returns a signed download link bound to this one file id; `subject` is a free-text audit label for who the link is for and is NOT authenticated. `ttl_seconds` defaults to 7 days and is capped at 30.

## Request body

- FileGrantRequest
  - `file_id` string, required
  - `subject` string: Free-text audit label for who the link is for. NOT authenticated — anyone holding the link can use it.
  - `ttl_seconds` integer: Lifetime of the link. Defaults to 7 days, capped at 30.

## Response `200`

Signed share-link.

- FileGrantResponse
  - `ok` boolean, required
  - `file_id` string, required
  - `filename` string, required
  - `subject` string
  - `token` string, required: The signed grant. Treat it as a bearer credential for this one file.
  - `link` string, required: Ready-to-send download URL carrying the grant.
  - `expires_at` string, date-time, required
  - `via` 'clerk' | 'agent'

## Other responses

- `400`: Invalid JSON.
- `401`: No auth.
- `403`: Not the uploader and not an operator.
- `404`: file_id names no file.
- `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)