---
title: "/showcases"
method: GET
path: "/v1/showcases"
tags: ["Showcases"]
---

# /showcases

`GET /v1/showcases`

## Request

- Base URL: `api.air.inc` (relative, and the document’s source URL is not known)
- URL: `api.air.inc/v1/showcases`
- 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/get.ts> (a function with typed inputs; its response is checked against the schema)

List the showcases you can see, each with its share link.

If your role can view every showcase in the workspace, all of them are listed. Otherwise only the showcases you own are listed.

A showcase's sub-pages are not listed separately. A showcase deleted in the Air app is not listed, and every route that takes its id, including the `showcaseId` filter on `GET /v1/assets` and `GET /v1/boards`, returns `404` for it.

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

## Query parameters

- `search` string
- `status` 'active' | 'inactive' | 'expired'
- `limit` integer
- `cursor` string

## Response `200`

Showcases listed successfully

- object
  - `data` Showcase[]
    - `id` string, required: The showcase ID
    - `name` string, required
    - `description` string, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `stats` object, required: How many items the showcase holds
      - `assetCount` integer, required
      - `fileCount` integer, required
      - `boardCount` integer, required
    - `shareLink` ShareLink, required
      - `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
  - `pagination` object
    - `hasMore` boolean
    - `cursor` string, nullable
  - `total` integer

## Other responses

- `400`: An unknown `status`, an empty `search`, a `limit` that is not a positive integer, or a cursor this endpoint did not issue

## Changes

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

[Operation history](https://skmtc.dev/air/apis/air-api/changes/v1/showcases/get.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)