--- title: "/assets/:assetId/share-links" method: POST path: "/v1/assets/{assetId}/share-links" tags: ["Share Links"] --- # /assets/:assetId/share-links `POST /v1/assets/{assetId}/share-links` ## Request - Base URL: `api.air.inc` (relative, and the document’s source URL is not known) - URL: `api.air.inc/v1/assets/{assetId}/share-links` - 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: (a function with typed inputs; its response is checked against the schema) Create a share link for an asset. Use `followsDefaultVersion: true` for a link that always shows the asset's current version, or `versionId` to pin the link to one version. Any field not listed in the request body is ignored. Settings you leave out follow your workspace's share link defaults. A new link is active unless you send `active: false`. `password`, `expiresAt`, `requireAccount`, `comments` and `customFields` depend on your workspace's plan; see the request body for what returns `422`. Returns `409 Conflict` if the asset already has a link of the same kind, even a disabled one. A version has one pinned link whatever its `showAllVersions` setting. Older links created from inside a board don't count, so the asset can end up with more than one link that follows its current version. Use `GET /v1/assets/{assetId}/share-links` to find the existing link, and `PATCH` to change it. Returns `403` if the link's settings, including the ones taken from your workspace defaults, would let visitors do something you can't do yourself. Requires the `share_links.write` and `assets.read` OAuth scopes. ## Request body - union: Specify exactly one of `followsDefaultVersion` or `versionId` - object: 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. - `followsDefaultVersion` true, required: Create a link that always shows the asset's current version. Only `true` is accepted. - `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. - `showAllVersions` boolean: Whether visitors can browse the asset's other versions - object: 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. - `versionId` string, uuid, required: Pin the link to this version of the asset. Don't send `followsDefaultVersion` with it. - `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. - `showAllVersions` boolean: Whether visitors can browse the asset's other versions ## Response `201` Share link created successfully - AssetShareLink - `id` string, required: The share link ID. It is also the last part of `url`. - `url` string, uri, required: The public share link to give to people. It is not an Air app link and not a CDN link. - `active` boolean, required: Whether the link is enabled. Disabled links are still listed. - `hasPassword` boolean, required: Whether visitors must enter a password to open the link. The password itself is never returned. - `expiresAt` string, date-time, nullable, required: When the link stops working, or null if it never expires - `requireAccount` boolean, required: Whether visitors must sign in to Air to open the link - `allowDownload` boolean, required: Whether visitors can download the original files - `comments` 'hidden' | 'read_only' | 'allowed', required: What visitors can do with comments. `hidden`: they can't see comments. `read_only`: they can see comments but not add them. `allowed`: they can see and add comments, which writes to your workspace. - `customFields` 'hidden' | 'read_only' | 'editable', required: What visitors can do with custom field values. `hidden`: they can't see them. `read_only`: they can see them. `editable`: they can change them, which writes to your workspace. This controls what visitors are allowed to do, not whether the Air share page shows its info panel. - `createdAt` string, date-time, required - `followsDefaultVersion` boolean, required: When true, the link always shows the asset's current version. When false, the link is pinned to `versionId`. - `showAllVersions` boolean, required: Whether visitors can browse the asset's other versions - `versionId` string: Present when `followsDefaultVersion` is false. The asset version the link is pinned to. ## Other responses - `400`: Invalid request body: neither or both of `followsDefaultVersion` and `versionId`, `followsDefaultVersion` other than `true`, a `null` value where it is not allowed, or an `expiresAt` that is not in the future - `403`: You do not have permission to create share links for this asset, or the link would let visitors do something you can't, such as download the original - `404`: Asset not found, or `Version not found` when `versionId` is not a version of this asset - `409`: The asset already has a link that follows its current version, or a link pinned to this version (`SHARE_LINK_ALREADY_EXISTS`) - `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/assets/:assetId/share-links/post.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)