Skip to main content

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