Imports

Raw Markdown for agents: imports.md. MCP: read_guide("imports").

Import sources keep a Space folder in sync with an external location (a OneDrive or SharePoint folder, a Google Drive folder, a mailbox) without an agent: the platform lists the location, imports new files as documents, keeps a backlog of what is still pending and records every decision.

Use imports.sources.create when the user wants documents to arrive automatically and repeatedly. Use a single provider import operation (for example integrations.gdrive.files.import) when the user wants one file now.

Before creating a source:

1. Find the connection with integrations.connections.list; the provider must list sources in integrations.catalog.get.
2. Browse the location with the provider's list operation (drives.list, files.list) to find the scope ids the source needs (scope_fields in the catalog entry). Pass the human names of the chosen ids as scope_labels so the source can show them.
3. Check that the Space grant (integrations.grants.list) allows both the list and the import operation of that source; recursive or folder-mirroring sources need a grant without a fixed folder constraint.
4. imports.sources.preview samples the start point with the intended policy and reports how many files would be imported or skipped; show that to the user before creating.
5. Pick the target folder with documents.folders.list, optionally a schedule (rule or cron, at most every 15 minutes, check it with workflows.schedule.preview; omit it for a source that only runs on demand) and a policy: recurse, max_depth, mirror_folders (recreate the source's folders under the target), MIME and name filters, max_item_bytes, on_change (skip keeps the first import, replace updates the document in place, import_as_new adds a numbered copy).

A run scans the location and then drains the whole backlog under the provider's rate limit; imports.runs.start runs a source now, imports.sources.get shows the backlog (items, progress, scan.complete) and the active run with its wait_reason. imports.items.list shows what was imported, skipped or failed; imports.items.retry_many queues failed or policy-skipped items again (by id or for the whole source) and can start a run. imports.sources.pause and imports.sources.resume control a source. A paused source shows pause_reason_code (for example grant_invalid or credits_exhausted); fix the cause, then resume. Only the connection owner can change or run a source.