Skip to main content
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:
ModeValueBehavior
SyncsyncAlways sync and index this folder’s contents (default)
SkipskipNever sync this folder — new content is not indexed
ManualmanualNew 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): 
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: 
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): 
{
  "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: 
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"
  }'
​
provider_folder_id
string
required
The folder ID from the source provider (e.g., Google Drive folder ID).
​
folder_name
string
Display name of the folder. Updated on each request to stay current.
​
folder_path
string
Display path of the folder. Updated on each request to stay current.
​
parent_folder_id
string
The parent folder’s provider ID. Used for policy inheritance resolution.
​
sync_mode
string
required
One of sync, skip, or manual.
If a policy already exists for the same folder and connection, it will be updated (upsert behavior).

​
Listing policies

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

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: 
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: 
curl -X POST "https://api.hyperspell.com/memories/approve/{source}/{resource_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
Returns: 
{
  "resource_id": "doc_xyz789",
  "source": "google_drive",
  "status": "pending"
}

​
Reject a resource

Rejecting moves the resource to skipped status — it will not be indexed: 
curl -X POST "https://api.hyperspell.com/memories/reject/{source}/{resource_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-As-User: $USER_ID"
Returns: 
{
  "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):
EventTrigger
resource-pending-reviewA new document in a manual folder needs approval
resource-approvedA user approved a pending resource
resource-rejectedA user rejected a pending resource
These use the same webhook payload format and signature verification as other Hyperspell webhooks. See Webhooks for details.

​
Policy Change Side-Effects

Changing a folder’s sync mode has retroactive effects on existing resources:
ChangeEffect
Any mode -> skipPending review resources are marked as skipped
manual -> syncPending review resources are auto-approved for indexing
skip -> sync or manualA resync is triggered to pick up previously skipped content