---
title: "Set app visibility"
method: PUT
path: "/apps/{app_id}/visibility"
tags: ["apps"]
---

# Set app visibility

`PUT /apps/{app_id}/visibility`

## Request

- Base URL: `https://api.opal.dev/v1`
- URL: `https://api.opal.dev/v1/apps/{app_id}/visibility`
- Auth: HTTP bearer

Sets the visibility of this app. Preferred over setting
`visibility` / `visibility_group_ids` / `import_visibility` inline on
`POST /apps` or `PATCH /apps/{app_id}` for drift-sensitive callers
(Terraform, GitOps). Semantics are a replace, not a merge:
`visibility_group_ids` is written to exactly what the request sends
(an omitted or empty array clears all groups), and `import_visibility`
is updated only when present.

## Path parameters

- `app_id` string, uuid, required

## Request body

- AppVisibilityInfo: Visibility information for an app. Mirrors `VisibilityInfo` but adds the App-specific `import_visibility`, which governs the default visibility of items imported from the app.
  - `visibility` 'GLOBAL' | 'LIMITED', required: The visibility level of the entity.
  - `visibility_group_ids` string[]: The IDs of groups that can see this app when visibility is `LIMITED`. Must be empty when visibility is `GLOBAL`.
  - `import_visibility` 'GLOBAL' | 'LIMITED': The visibility level of the entity.

## Response `200`

The updated visibility info of this app.

- AppVisibilityInfo: Visibility information for an app. Mirrors `VisibilityInfo` but adds the App-specific `import_visibility`, which governs the default visibility of items imported from the app.
  - `visibility` 'GLOBAL' | 'LIMITED', required: The visibility level of the entity.
  - `visibility_group_ids` string[]: The IDs of groups that can see this app when visibility is `LIMITED`. Must be empty when visibility is `GLOBAL`.
  - `import_visibility` 'GLOBAL' | 'LIMITED': The visibility level of the entity.

## Other responses

- `400`: Invalid request body or app state. Returned for any of: a malformed JSON body, an unknown field, an invalid `visibility` or `import_visibility` enum value, a `visibility_group_ids` entry that does not resolve to a group in the caller's org, a `visibility_group_ids` value that is non-empty while the effective `visibility` is `GLOBAL` (either sent on this request or already stored on the app), or an app whose type does not support visibility writes (only `CUSTOM` and `CUSTOM_CONNECTOR` do).
- `403`: The caller is not authorized to edit this app's visibility.
- `404`: The app was not found.

## Changes

- **2026-11-04** `e7877ea96eab`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/opal/apis/opal-api/changes/apps/:app_id/visibility/put.md)

---

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