> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperspell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folder Sync

> Control which folders are synced with per-folder policies

Folder sync gives your users granular control over which folders from their connected cloud storage are synced, skipped, or sent to a review queue. This works with Google Drive, Dropbox, and Box integrations.

## Sync Modes

Each folder can be assigned one of three sync modes:

| Mode       | Value    | Behavior                                                 |
| ---------- | -------- | -------------------------------------------------------- |
| **Sync**   | `sync`   | Always sync and index this folder's contents (default)   |
| **Skip**   | `skip`   | Never sync this folder — new content is not indexed      |
| **Manual** | `manual` | New documents land in a review queue for manual approval |

## Folder Discovery

Before setting policies, your UI needs to show the user's folder tree. The folder discovery endpoint returns one level at a time (lazy loading):

```bash theme={null}
curl -X GET "https://api.hyperspell.com/connections/{connection_id}/folders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

To drill into a subfolder, pass `parent_id`:

```bash theme={null}
curl -X GET "https://api.hyperspell.com/connections/{connection_id}/folders?parent_id=folder_abc123" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

Each folder in the response includes its current policy (if one is set):

```json theme={null}
{
  "folders": [
    {
      "provider_folder_id": "folder_abc123",
      "name": "Engineering",
      "parent_folder_id": null,
      "has_children": true,
      "policy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "sync_mode": "sync"
      }
    },
    {
      "provider_folder_id": "folder_def456",
      "name": "Personal",
      "parent_folder_id": null,
      "has_children": false,
      "policy": null
    }
  ]
}
```

A `null` policy means the folder inherits its sync mode from its nearest ancestor with a policy, or defaults to `sync`.

## Setting Folder Policies

Create or update a folder policy on a connection:

```bash theme={null}
curl -X POST "https://api.hyperspell.com/connections/{connection_id}/folder-policies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_folder_id": "folder_abc123",
    "folder_name": "Engineering",
    "parent_folder_id": null,
    "sync_mode": "sync"
  }'
```

<ParamField body="provider_folder_id" type="string" required>
  The folder ID from the source provider (e.g., Google Drive folder ID).
</ParamField>

<ParamField body="folder_name" type="string">
  Display name of the folder. Updated on each request to stay current.
</ParamField>

<ParamField body="folder_path" type="string">
  Display path of the folder. Updated on each request to stay current.
</ParamField>

<ParamField body="parent_folder_id" type="string">
  The parent folder's provider ID. Used for policy inheritance resolution.
</ParamField>

<ParamField body="sync_mode" type="string" required>
  One of `sync`, `skip`, or `manual`.
</ParamField>

If a policy already exists for the same folder and connection, it will be updated (upsert behavior).

### Listing policies

```bash theme={null}
curl -X GET "https://api.hyperspell.com/connections/{connection_id}/folder-policies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

### Deleting a policy

```bash theme={null}
curl -X DELETE "https://api.hyperspell.com/connections/{connection_id}/folder-policies/{policy_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

Deleting a policy causes the folder to inherit from its parent (or default to `sync`).

## Policy Inheritance

Policies resolve hierarchically — the most specific folder wins:

1. Check the folder itself for a policy
2. Walk up the parent chain checking each ancestor
3. If no policy is found, default to `sync`

For example, if `/Engineering` is set to `sync` and `/Engineering/Drafts` is set to `skip`, files in `/Engineering` will sync but files in `/Engineering/Drafts` will not.

## Manual Review Workflow

When a folder is set to `manual`, new documents from that folder land in `pending_review` status instead of being indexed immediately. Your app can then present a review UI.

### List pending resources

Use the existing `/memories/list` endpoint with a `status` filter:

```bash theme={null}
curl -X GET "https://api.hyperspell.com/memories/list?status=pending_review" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

### Approve a resource

Approving moves the resource to `pending` status, which queues it for indexing:

```bash theme={null}
curl -X POST "https://api.hyperspell.com/memories/approve/{source}/{resource_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

Returns:

```json theme={null}
{
  "resource_id": "doc_xyz789",
  "source": "google_drive",
  "status": "pending"
}
```

### Reject a resource

Rejecting moves the resource to `skipped` status — it will not be indexed:

```bash theme={null}
curl -X POST "https://api.hyperspell.com/memories/reject/{source}/{resource_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
```

Returns:

```json theme={null}
{
  "resource_id": "doc_xyz789",
  "source": "google_drive",
  "status": "skipped"
}
```

## Webhook Notifications

When folder sync events occur, Hyperspell fires webhook notifications (if you have a webhook URL configured in your app settings):

| Event                     | Trigger                                            |
| ------------------------- | -------------------------------------------------- |
| `resource-pending-review` | A new document in a `manual` folder needs approval |
| `resource-approved`       | A user approved a pending resource                 |
| `resource-rejected`       | A user rejected a pending resource                 |

These use the same webhook payload format and signature verification as other Hyperspell webhooks. See [Webhooks](/usage/webhooks) for details.

## Policy Change Side-Effects

Changing a folder's sync mode has retroactive effects on existing resources:

| Change                       | Effect                                                      |
| ---------------------------- | ----------------------------------------------------------- |
| Any mode -> `skip`           | Pending review resources are marked as skipped              |
| `manual` -> `sync`           | Pending review resources are auto-approved for indexing     |
| `skip` -> `sync` or `manual` | A resync is triggered to pick up previously skipped content |