Import Source Items
Imports online document pages or online drive files into a connector source and returns the run. Poll Get Source Run with its id until state is completed, failed, or canceled.
The items replace the source’s documents: once they are imported, documents of the source’s items not in items are deleted. Send every item you want the source to keep.
After a source’s first completed import, an import can name only items from that import. A new item fails the run with SOURCE_OPERATION_FAILED, which retrying does not fix: add new items to the source in Dify.
The source must be a connector source, and kind must match its metadata.providerKind. A source runs one sync, preview, or import at a time, so wait for its active run to end first.
For the browse-and-import flow, see Import Online Documents and Drive Files.
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/workflow-imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"items": [
{
"lastEditedTime": "2026-09-01T12:00:00.000Z",
"name": "Onboarding",
"pageId": "3f9a1c2b-7d4e-4f5a-8b6c-9d0e1f2a3b4c",
"providerItemId": "[\"ws_01HZYQ8K3M\",\"3f9a1c2b-7d4e-4f5a-8b6c-9d0e1f2a3b4c\"]",
"type": "page",
"workspaceId": "ws_01HZYQ8K3M"
},
{
"lastEditedTime": "2026-08-20T09:30:00.000Z",
"name": "Runbooks",
"pageId": "5c1b2d3e-8f4a-4b6c-9d7e-0f1a2b3c4d5e",
"providerItemId": "[\"ws_01HZYQ8K3M\",\"5c1b2d3e-8f4a-4b6c-9d7e-0f1a2b3c4d5e\"]",
"type": "database",
"workspaceId": "ws_01HZYQ8K3M"
}
],
"kind": "online-document-import"
}
'{
"canceled_at": null,
"checkpoint": "queued",
"completed_at": null,
"created_at": "2026-10-20T10:00:00Z",
"cursor": null,
"execution_attempts": 0,
"failure": null,
"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
"kind": "online-document-import",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_error_code": null,
"max_execution_attempts": 5,
"progress_completed": 0,
"progress_failed": 0,
"progress_skipped": 0,
"progress_total": 2,
"source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"state": "queued",
"updated_at": "2026-10-20T10:00:00Z"
}Authorizations
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Headers
Repeating the same key and request from the same API key returns the original run in its current state. Use a new key for each import you start. Reusing the key on this source and kind with different items returns 409. Use printable ASCII characters without leading or trailing whitespace.
8 - 255Body
The normalized request must fit within 4,194,304 UTF-8 bytes. See Request Size Limits.
- Online Document Pages
- Online Drive Files
Pages to import, from List Source Pages.
1 - 200 elementsShow child attributes
Show child attributes
Response
The run, with kind as sent, state: queued, and progress_total set to the number of items.
Last step the run reached: queued, provider-read, preview-staged, selection-frozen, materialized, cleanup-staging, or source-committed. Retry Source Run starts the run over whatever its checkpoint.
Times a worker has picked up the run, including after Retry Source Run, which does not reset it.
Run ID. Pass it to Get Source Run, Cancel Source Run, or Retry Source Run.
What the run does:
sync: started by Sync Source, Update Source, a schedule, or Dify.crawl-preview: started by Preview Website Crawl. It keeps this kind while Import Selected Pages imports from it.crawl-import: started by Import Website Pages.online-document-import,online-drive-import: started by Import Source Items.
Dify also starts previews and imports when a source is added or edited there.
Limit on execution_attempts. Once it is reached, Retry Source Run answers 409.
Items the run expects to process: the pages or items an import requested, the pages a crawl preview has staged so far, or the source's items once a sync has listed them. null until known.
While an Import Website Pages run crawls its URLs, progress_completed and progress_total both count the pages crawled so far. Once every URL is crawled, they restart at 0 of the number of URLs.
Progress of the run.
Live states:
queued: waiting for a workercrawling: a crawl preview is fetching pagespreview_ready: a crawl preview is waiting for Import Selected Pages or Cancel Source Runimporting: importing and indexing itemssyncing: refreshing the source's documents
Terminal states:
completed: every item was imported or refreshed, indexed, and made activezero_results: a crawl preview found no pagesfailed: seefailurecanceled
After failed or canceled, Retry Source Run runs it again, and Sync Source starts a new sync.
Was this page helpful?
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/workflow-imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"items": [
{
"lastEditedTime": "2026-09-01T12:00:00.000Z",
"name": "Onboarding",
"pageId": "3f9a1c2b-7d4e-4f5a-8b6c-9d0e1f2a3b4c",
"providerItemId": "[\"ws_01HZYQ8K3M\",\"3f9a1c2b-7d4e-4f5a-8b6c-9d0e1f2a3b4c\"]",
"type": "page",
"workspaceId": "ws_01HZYQ8K3M"
},
{
"lastEditedTime": "2026-08-20T09:30:00.000Z",
"name": "Runbooks",
"pageId": "5c1b2d3e-8f4a-4b6c-9d7e-0f1a2b3c4d5e",
"providerItemId": "[\"ws_01HZYQ8K3M\",\"5c1b2d3e-8f4a-4b6c-9d7e-0f1a2b3c4d5e\"]",
"type": "database",
"workspaceId": "ws_01HZYQ8K3M"
}
],
"kind": "online-document-import"
}
'{
"canceled_at": null,
"checkpoint": "queued",
"completed_at": null,
"created_at": "2026-10-20T10:00:00Z",
"cursor": null,
"execution_attempts": 0,
"failure": null,
"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
"kind": "online-document-import",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_error_code": null,
"max_execution_attempts": 5,
"progress_completed": 0,
"progress_failed": 0,
"progress_skipped": 0,
"progress_total": 2,
"source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"state": "queued",
"updated_at": "2026-10-20T10:00:00Z"
}