Skip to main content
POST
Create Source

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

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.

Body

application/json

Optional fields marked nullable treat null as omitted.

The normalized request must fit within 262,144 UTF-8 bytes. See Request Size Limits.

name
string
required

Display name.

Required string length: 1 - 200
type
enum<string>
required

Send web for a website crawl, or connector for an online document or online drive provider (set metadata.providerKind). upload and object-storage are for sources Dify fills.

Available options:
connector,
object-storage,
upload,
web
uri
string
required

Crawl root URL for web. connector://<connectionId> for connector, matching what Dify writes.

Required string length: 1 - 4096
connectionId
string<uuid> | null

Connection that supplies the credentials the source reads with. It must belong to this knowledge base and be active. From id of List Source Connections.

metadata
object

Provider settings and your own non-sensitive metadata. Add a unique client_request_id to recognize this source if the creation response is lost. It is returned with the source, but the API does not enforce uniqueness or deduplicate requests.

Set providerKind to the connection's configuration.providerKind, and pick the source type that fits it. Settings that come from the connection may be absent from the source response.

If you build metadata from an existing source's response, leave out fields starting with __knowledgeFs, credentials, and the parameters object. credentialId, when present, refers to a credential Dify holds.

permissionScope
string[]

Leave empty or omit. Only an empty list is accepted.

status
enum<string> | null
default:active

disabled pauses scheduled syncs.

Available options:
active,
disabled,
null

Response

The created source.

connection_id
string | null

Connection the source uses for credentials. Pass it as connectionId when binding another source to the same connection. null when unbound.

created_at
string

Creation time, ISO 8601.

credential_configured
boolean | null

true when the source holds a credential reference of its own. null when it holds none, as with sources bound to a connection.

id
string

Source ID.

knowledge_space_id
string

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

last_synced_at
string | null

Completion time of the latest completed sync (completed or zero_results) or completed import. Set by List Sources only. null elsewhere and when the source has never synced.

metadata
object

Provider settings and server-managed sync or page-selection data. May include provider identifiers and parameters; connection-managed settings need not appear here. Credential-like keys are removed. Do not copy the entire object when creating another source.

name
string

Display name.

permission_scope
string[]

Content scopes required to read this source. An empty list adds no content restriction within the knowledge base. Knowledge base authorization still applies.

status
string

active, syncing, error, or disabled. Most operations return the stored value. List Sources derives it from the latest sync run:

  • failed or canceled run: error
  • completed or zero_results run: active
  • Any live run: syncing

disabled is never overridden.

sync_policy
object | null

The source's sync schedule. Set by List Sources only. null elsewhere and when no schedule exists. Read it on its own with Get Sync Policy and change it with Update Sync Policy.

sync_workflow
object | null

The source's active sync or import run (crawl-import, online-document-import, or online-drive-import), or else its latest sync run. List Sources sets it when a run is active or newer than the source. Update Source sets it when the call started a sync. null otherwise. Crawl previews and imports from them never appear here.

To follow one run, call Get Source Run with its id.

type
string

web (website crawl), connector (online document or online drive), upload, or object-storage.

For a connector source, metadata.providerKind is online-document or online-drive. For a web source it is website.

Dify fills upload and object-storage sources.

updated_at
string

Last change, ISO 8601.

uri
string

Crawl root URL for web sources. connector://<connection_id> for Dify-created connector sources.

version
integer

Source version, increased on every write. Send it as expectedVersion on Update Source, as expectedRevision on Delete Source, and as expectedSourceVersion on Update Sync Policy.