Folder Sync

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):

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"
  }'

string

required

The folder ID from the source provider (e.g., Google Drive folder ID).

string

Display name of the folder. Updated on each request to stay current.

string

Display path of the folder. Updated on each request to stay current.

string

The parent folder’s provider ID. Used for policy inheritance resolution.

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:

Check the folder itself for a policy
Walk up the parent chain checking each ancestor
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):

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

Get Started

Usage

Advanced Usage

Resources

Sync Modes

Folder Discovery

Setting Folder Policies

Listing policies

Deleting a policy

Policy Inheritance

Manual Review Workflow

List pending resources

Approve a resource

Reject a resource

Webhook Notifications

Policy Change Side-Effects

​Sync Modes

​Folder Discovery

​Setting Folder Policies

​Listing policies

​Deleting a policy

​Policy Inheritance

​Manual Review Workflow

​List pending resources

​Approve a resource

​Reject a resource

​Webhook Notifications

​Policy Change Side-Effects

Sync Modes

Folder Discovery

Setting Folder Policies

Listing policies

Deleting a policy

Policy Inheritance

Manual Review Workflow

List pending resources

Approve a resource

Reject a resource

Webhook Notifications

Policy Change Side-Effects