# Favorite Facets API Reference

## Table of Contents

- [List Favorite Facets](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-list)
- [List Favorite Facet Groups](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-list-groups)
- [Add a Favorite Facet](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-add)
- [Edit a Favorite Facet](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-edit)
- [Remove a Favorite Facet](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-remove)
- [Remove a Favorite Facet Group](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#facets-remove-group)
- [Error Handling](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#error-handling)
- [See Also](https://docs.kloudfuse.com/platform/4.1.0/reference/api/facets/#see-also)

Favorite facets are managed through the GraphQL endpoint at `/query`.  
All operations use `POST` with a JSON body containing a `query` key (for reads) or `mutation` key (for writes).

Replace `<your-instance>` with your Kloudfuse hostname and `<sa-token>` with a valid Service Account token.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{"query": "..."}'
```

## List Favorite Facets

Returns facets matching an optional search string, with optional group filter and pagination.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{
       "query": "query { getFavoriteFacets(contains: \"\", limit: 100) { name dataType group displayName source folderUid } }"
     }'
```

Parameters (all optional):

| Parameter | Type   | Description                                           |
|-----------|--------|-------------------------------------------------------|
| `contains`| string | Filter by display name substring. Default: `""` (all). |
| `group`   | string | Filter to a specific facet group.                     |
| `cursor`  | string | Pagination cursor from a previous response.            |
| `limit`   | int    | Maximum results to return.                             |

Response

```json
{
  "data": {
    "getFavoriteFacets": [
      {
        "name": "resource_name",
        "dataType": "STRING",
        "group": "Infrastructure",
        "displayName": "resource_name",
        "source": "",
        "folderUid": "ffec62bbr7v28d"
      }
    ]
  }
}
```

## List Favorite Facet Groups

Returns all group names that contain at least one favorite facet.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{"query": "query { getFavoriteFacetGroups(limit: 1000) }"}'
```

Response

```json
{
  "data": {
    "getFavoriteFacetGroups": [
      "Infrastructure",
      "Application",
      "Recents"
    ]
  }
}
```

## Add a Favorite Facet

Creates a new favorite facet, optionally assigning it to a folder.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{
       "query": "mutation($datatype: String!, $displayName: String!, $facet: String!, $facetGroup: String!, $source: String, $folderUid: String) { addFavoriteFacet(source: $source, facet: $facet, facetGroup: $facetGroup, displayName: $displayName, datatype: $datatype, folderUid: $folderUid) }",
       "variables": {
         "datatype": "STRING",
         "displayName": "service_name",
         "facet": "service_name",
         "facetGroup": "Infrastructure",
         "source": "",
         "folderUid": "ffec62bbr7v28d"
       }
     }'
```

Variables:

| Variable   | Type     | Required | Description                                    |
|------------|----------|----------|------------------------------------------------|
| `facet`    | string   | Yes      | The raw field name in the telemetry data.     |
| `displayName`| string | Yes      | Human-readable label shown in the UI.        |
| `datatype` | string   | Yes      | Data type: `STRING`, `NUMBER`, or `BOOLEAN`.  |
| `facetGroup`| string  | Yes      | Group the facet appears under in the UI.      |
| `source`   | string   | No       | Source identifier (leave empty for log facets).
| `folderUid`| string   | No       | Folder to assign the facet to. Omit for root. |

Response

```json
{
  "data": {
    "addFavoriteFacet": true
  }
}
```

## Edit a Favorite Facet

Renames a facet, moves it to a different group, or reassigns it to a different folder.
Identify the facet by its current `displayName` and `facetGroup`.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{
       "query": "mutation($displayName: String!, $facetGroup: String!, $newFacetGroup: String!, $newDisplayName: String!, $folderUid: String) { editFavoriteFacet(display_name: $displayName, facetGroup: $facetGroup, editInfo: {newGroup: $newFacetGroup, newDisplayName: $newDisplayName, newFolderUid: $folderUid}) }",
       "variables": {
         "displayName": "service_name",
         "facetGroup": "Infrastructure",
         "newFacetGroup": "Application",
         "newDisplayName": "app_service_name",
         "folderUid": "bfec62n4wfpq8e"
       }
     }'
```

Response

```json
{
  "data": {
    "editFavoriteFacet": true
  }
}
```

## Remove a Favorite Facet

Deletes a specific facet identified by its display name and group.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{
       "query": "mutation { removeFavoriteFacet(display_name: \"app_service_name\", facetGroup: \"Application\") }"
     }'
```

Response

```json
{
  "data": {
    "removeFavoriteFacet": true
  }
}
```

## Remove a Favorite Facet Group

Deletes an entire facet group and all facets within it.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/query" \
     -d '{
       "query": "mutation { removeFacetGroup(facetGroup: \"Application\") }"
     }'
```

Response

```json
{
  "data": {
    "removeFacetGroup": true
  }
}
```

## Error Handling

GraphQL errors are returned with HTTP 200 in an `errors` array:

```json
{
  "errors": [
    {
      "message": "facet group not found",
      "path": ["removeFacetGroup"]
    }
  ]
}
```