---
title: "List an app’s direct shares"
method: GET
path: "/api/v1/apps/{appId}/shares"
tags: ["AppShares"]
---

# List an app’s direct shares

`GET /api/v1/apps/{appId}/shares`

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/api/v1/apps/{appId}/shares`
- Auth: HTTP bearer

User-gated (`chrm_user_*` or session); requires `app:share`. Returns stable share ids and display labels without internal account ids or mutation authority.

## Path parameters

- `appId` string, uuid, required

## Response `200`

Direct shares visible to the caller.

- AppSharesListResponse
  - `ok` true, required
  - `shares` object[], required
    - `id` string, uuid, required
    - `grantee` object, required
      - `kind` 'account' | 'email', required
      - `label` string, required
      - `handle` string: The account grantee’s handle, which names their avatar at `/<handle>.png`. Absent for email invitations and accounts without a handle.
      - `badges` NameBadges: The marks Charming shows beside a person’s name, derived from live plans at read time.
        - `pro` boolean, required: True while the person pays for a plan on their own account.
        - `affiliation` object, nullable, required: The paid team the person shows beside their name, or null for none.
          - `name` string, required
          - `logoUrl` string, uri, required
    - `status` 'pending' | 'accepted' | 'invited', required
    - `role` 'collaborator' | 'end-user' | 'viewer', required

## Other responses

- `400`: Invalid app id.
- `401`: Sign-in required.
- `403`: The caller cannot manage shares.
- `404`: App not found.

---

[API](https://skmtc.dev/charm/apis/charming-api.md) · [All operations](https://skmtc.dev/charm/apis/charming-api/llms.txt) · [OpenAPI document](https://skmtc.dev/charm/apis/charming-api/revisions/a9d06c419b3a?raw)