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