---
title: "/showcases/:showcaseId/share-links/:shareLinkId"
method: PATCH
path: "/v1/showcases/{showcaseId}/share-links/{shareLinkId}"
tags: ["Showcases"]
---

# /showcases/:showcaseId/share-links/:shareLinkId

`PATCH /v1/showcases/{showcaseId}/share-links/{shareLinkId}`

## Request

- Base URL: `api.air.inc` (relative, and the document’s source URL is not known)
- URL: `api.air.inc/v1/showcases/{showcaseId}/share-links/{shareLinkId}`
- Auth: one of:
  - API key in header `x-api-key` and API key in header `x-air-workspace-id`
  - HTTP bearer and API key in header `x-air-workspace-id`
- TypeScript: <https://skmtc.dev/air/apis/air-api/docs/v1/showcases/:showcaseId/share-links/:shareLinkId/patch.ts> (a function with typed inputs; its response is checked against the schema)

Change the settings of a showcase's share link.

Works like `PATCH /v1/boards/{boardId}/share-links/{shareLinkId}`. Only the settings you send change. Everything else on the link, including its password, stays as it is. Send `password: null` or `expiresAt: null` to remove them.

Returns an empty body on success. Use `GET /v1/showcases/{showcaseId}` to read the link's settings.

Requires the `share_links.write` and `showcases.read` OAuth scopes.

## Request body

- ShareLinkSettings: Share link settings you can set. Omitted settings are not changed. `password`, `expiresAt`, `requireAccount`, `comments` and `customFields` depend on your workspace's plan. Paid plans include them by default, also during the 30-day grace period after a paid plan expires. Turning one on that your plan does not include returns `422` with `type: ADDON_DISABLED`, `extra.addonKey: shareLinks`, and `extra.settings` listing the rejected settings (`password`, `expiration`, `requireAccount`, `comments`, `customFields`). Nothing in the request is applied. A link keeps the settings it already has, whatever the plan. Sending a value the link already has, changing a password or expiration date the link already has, and turning a setting off always work. Moving `comments` or `customFields` up a level counts as turning it on: from `hidden` to any other value, or from `read_only` to `allowed` or `editable`. Settings a new link takes from your workspace defaults or from a board above it do not count.
  - `active` boolean: Whether the link works. A disabled link keeps its settings and can be enabled again.
  - `allowDownload` boolean: Whether visitors can download the original files
  - `password` string, nullable: Password visitors must enter to open the link. `null` removes it. Never returned; read `hasPassword` instead.
  - `expiresAt` string, date-time, nullable: When the link stops working. Must be in the future. `null` removes the expiration.
  - `requireAccount` boolean: Whether visitors must sign in to Air to open the link
  - `comments` 'hidden' | 'read_only' | 'allowed': What visitors can do with comments. `allowed` lets them add comments, which writes to your workspace.
  - `customFields` 'hidden' | 'read_only' | 'editable': What visitors can do with custom field values. `editable` lets them change values, which writes to your workspace.

## Response `204`

Share link updated successfully

## Other responses

- `400`: Invalid request body, including a `null` value where it is not allowed, or an `expiresAt` that is not in the future
- `403`: You do not have permission to edit this showcase's share link, or the link lets visitors do something you can't, such as download the original
- `404`: Showcase not found, or the share link is not this showcase's link
- `422`: The request turns on a share link setting your workspace's plan does not include (`ADDON_DISABLED`). `extra.addonKey` is `shareLinks` and `extra.settings` lists them.

## Changes

- **2026-11-03** `8e6005b272a1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/air/apis/air-api/changes/v1/showcases/:showcaseId/share-links/:shareLinkId/patch.md)

---

[API](https://skmtc.dev/air/apis/air-api.md) - [All operations](https://skmtc.dev/air/apis/air-api/llms.txt) - [OpenAPI document](https://skmtc.dev/air/apis/air-api/revisions/8e6005b272a1?raw)