# 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.

## 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

## Related Documentation

- [Folder Mapping for Logs Objects](https://docs.kloudfuse.com/platform/3.5.0/folder-mapping-for-logs/) - User guide and concepts

- [Managing Folders](https://docs.kloudfuse.com/platform/3.5.0/admin-folders/) - Core folder management

- [Role-Based Access Control](https://docs.kloudfuse.com/platform/3.5.0/rbac/) - Understanding permissions