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.

POST /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/workflow-imports

cURL

online_document

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

202

success

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

Authorization · string · header · required

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

Idempotency-Key · string · required

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.

Required string length: 8 - 255

Path Parameters

knowledge_base_id · string<uuid> · required

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

source_id · string<uuid> · required

Source ID. From List Sources.

Body

application/json

The normalized request must fit within 4,194,304 UTF-8 bytes. See Request Size Limits.

Online Document Pages

Online Drive Files

items · object[] · required

Pages to import, from List Source Pages.

Required array length: 1 - 200 elements

Show child attributes

kind · enum<string> · required

For a source whose metadata.providerKind is online-document.

Available options: online-document-import

Response

202

application/json

The run, with kind as sent, state: queued, and progress_total set to the number of items.

canceled_at · string | null

When the run was canceled. null unless state is canceled.

checkpoint · string

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.

completed_at · string | null

When the run ended (completed, zero_results, failed, or canceled), ISO 8601. null while it runs.

created_at · string

Creation time, ISO 8601.

cursor · string | null

Provider cursor the run resumes from. null when the run has not paged.

execution_attempts · integer

Times a worker has picked up the run, including after Retry Source Run, which does not reset it.

failure · object | null

Error details when state is failed. stage is the run's checkpoint at the failure, and traceId is the run ID. null otherwise.

Show child attributes

id · string

Run ID. Pass it to Get Source Run, Cancel Source Run, or Retry Source Run.

kind · string

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.

knowledge_space_id · string

Internal ID of the knowledge base. Not the knowledge base ID in the path.

last_error_code · string | null

failure.code when state is failed. null otherwise.

max_execution_attempts · integer

Limit on execution_attempts. Once it is reached, Retry Source Run answers 409.

progress_completed · integer

Items finished, including unchanged items a sync checked.

progress_failed · integer

Always 0 for source runs: a failing item fails the whole run.

progress_skipped · integer

Always 0 for source runs.

progress_total · integer | null

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.

source_id · string | null

Source the run belongs to.

state · string

Progress of the run.

Live states:

• queued: waiting for a worker
• crawling: a crawl preview is fetching pages
• preview_ready: a crawl preview is waiting for Import Selected Pages or Cancel Source Run
• importing: importing and indexing items
• syncing: refreshing the source's documents

Terminal states:

• completed: every item was imported or refreshed, indexed, and made active
• zero_results: a crawl preview found no pages
• failed: see failure
• canceled

After failed or canceled, Retry Source Run runs it again, and Sync Source starts a new sync.

updated_at · string

Last change, ISO 8601.