# Folder Mapping API Reference

This page provides API reference documentation for the folder mapping functionality, which allows you to programmatically manage folder associations for logs objects.

|     |     |
| --- | --- |
|  | Folder mapping requires the `EnableFolderMapping` feature flag to be enabled in your Kloudfuse configuration. Contact your system administrator if this feature is not available. |

## GraphQL Mutations

The folder mapping feature provides these GraphQL mutations for managing folder associations:

### Edit Favorite Facet with Folder

Update an existing favorite facet and assign it to a folder:

```graphql
mutation {
  editFavoriteFacet(
    displayName: "error_rate"
    group: "application_metrics"
    editInfo: {
      newDisplayName: "error_rate_updated"
      newFolderUid: "folder-uid-123"
    }
  )
}
```

### Create Favorite Facet in Folder

Create a new favorite facet and assign it to a folder:

```graphql
mutation {
  addFavoriteFacet(
    displayName: "response_time"
    name: "response_time_ms"
    dataType: "number"
    facetGroup: "performance"
    folderUid: "folder-uid-123"
  )
}
```

## HTTP API Endpoints

### Update Folder Mapping

Update the folder mapping for an existing logs object:

```bash
curl -X PATCH http://localhost:8083/folder-mappings \
  -H "Content-Type: application/json" \
  -H "X-Auth-Request-User: user@example.com" \
  -d '{
    "entityType": "favorite_facet",
    "entityName": "response_time::performance",
    "newFolderUid": "new-folder-uid"
  }'
```

### Remove Folder Mapping

Remove the folder mapping for a logs object (object becomes unmapped):

```bash
curl -X DELETE http://localhost:8083/folder-mappings \
  -H "Content-Type: application/json" \
  -H "X-Auth-Request-User: user@example.com" \
  -d '{
    "entityType": "favorite_facet",
    "entityName": "response_time::performance"
  }'
```

## API Parameters

### Common Parameters

| Parameter   | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| `entityType`| string | Type of logs object (`favorite_facet`, `lookup_table`, `scheduled_view`) |
| `entityName`| string | Unique identifier for the logs object               |
| `folderUid` | string | Unique identifier for the target folder            |
| `newFolderUid` | string | New folder UID when updating folder mappings  |

### Response Codes

| Code | Description                       |
|------|-----------------------------------|
| `200`| Successful operation               |
| `400`| Invalid request parameters         |
| `401`| Authentication required            |
| `403`| Insufficient permissions           |
| `404`| Object or folder not found        |
| `500`| Internal server error             |

## Authentication

All API endpoints require proper authentication:

- **GraphQL**: Use your standard GraphQL authentication method
- **HTTP APIs**: Include the `X-Auth-Request-User` header with a valid user identifier