# Overview (/docs/reference/api/apps)



Apps [#apps]

Members can list apps. Installation and removal require an organization administrator. Apps belong to a cluster.

Apps are installed per cluster, and clusters start with no apps installed. App management requires an authenticated user session or OAuth access token; cluster API keys cannot manage apps.

GET `/v1/apps` [#get-v1apps]

List the available apps and their installation state. Any member of the organization can list apps. Pass the organization and cluster names in the query string:

```text
GET /v1/apps?organization=acme&cluster=production
```

```json
{
  "apps": [
    { "id": "opentelemetry", "name": "OpenTelemetry", "installed": true },
    { "id": "prometheus", "name": "Prometheus", "installed": false }
  ]
}
```

This endpoint reads platform metadata only, so it remains available while the cluster is provisioning, paused, stopped, or otherwise unavailable.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes             |
| -------------- | -------- | ------ | -------- | ----------------- |
| `organization` | query    | string | Yes      | Organization name |
| `cluster`      | query    | string | Yes      | Cluster name      |

Request:

```bash
# List available apps and their installation state for a cluster.
curl -X GET "https://api.rawtree.com/v1/apps?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "apps": [
    {
      "id": "opentelemetry",
      "name": "OpenTelemetry",
      "installed": true
    },
    {
      "id": "prometheus",
      "name": "Prometheus",
      "installed": false
    },
    {
      "id": "splunk",
      "name": "Splunk",
      "installed": false
    },
    {
      "id": "datahub",
      "name": "DataHub",
      "installed": false
    }
  ]
}
```

Errors: `400`, `401`, `403`, `404`. See [API errors](/docs/reference/errors).

PUT `/v1/apps/{app_id}` [#put-v1appsapp_id]

Install an app. Organization admin access is required. The request has no body and is idempotent:

```text
PUT /v1/apps/prometheus?organization=acme&cluster=production
```

```json
{ "id": "prometheus", "name": "Prometheus", "installed": true }
```

Installation enables the app's native endpoints; it does not change the cluster lifecycle state or guarantee that the cluster is ready.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes             |
| -------------- | -------- | ------ | -------- | ----------------- |
| `organization` | query    | string | Yes      | Organization name |
| `cluster`      | query    | string | Yes      | Cluster name      |

Request:

```bash
# Install an app into a cluster.
curl -X PUT "https://api.rawtree.com/v1/apps/opentelemetry?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "id": "opentelemetry",
  "name": "OpenTelemetry",
  "installed": true
}
```

Errors: `400`, `401`, `403`, `404`. See [API errors](/docs/reference/errors).

DELETE `/v1/apps/{app_id}` [#delete-v1appsapp_id]

Uninstall an app. Organization admin access is required. The request has no body and is idempotent:

```text
DELETE /v1/apps/prometheus?organization=acme&cluster=production
```

```json
{ "id": "prometheus", "name": "Prometheus", "installed": false }
```

Uninstallation disables the app's native endpoints; it does not change the cluster lifecycle state. The Apps catalog remains available while the cluster is stopped.

The following sections document the APIs and protocols implemented by each app.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes             |
| -------------- | -------- | ------ | -------- | ----------------- |
| `organization` | query    | string | Yes      | Organization name |
| `cluster`      | query    | string | Yes      | Cluster name      |

Request:

```bash
# Uninstall an app from a cluster.
curl -X DELETE "https://api.rawtree.com/v1/apps/opentelemetry?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "id": "opentelemetry",
  "name": "OpenTelemetry",
  "installed": false
}
```

Errors: `400`, `401`, `403`, `404`. See [API errors](/docs/reference/errors).