API: connectors and sync

Connectors define remote or local log sources that Log Lens fetches and indexes. All actions are selected with the api query parameter (see API conventions).

Connector CRUD - ?api=connectors

Method	Action	Response
GET	List all connectors	{ "data": [...] }
POST	Create	created connector, 201
PATCH / PUT	Update (id in body or query)	updated connector
DELETE	Delete (id in body or query)	{ "id", "deleted": true }

Body fields:

Field	Rules
name	1-100 chars, unique
type	local or ssh
module_id	existing module id, or null
enabled	boolean, defaults true
config	object (see below)

local config: directory (must be a readable directory), recursive (boolean, default true).

ssh config: host, user, port (default 22), key_path, known_hosts_file, and paths - 1-100 absolute paths or single-level globs. Paths may not contain .., control characters, or **. SSH runs with BatchMode=yes and StrictHostKeyChecking=yes.

Test - ?api=connector-test (POST)

Body { "id": N }. Connects and lists sources. Returns { "ok": true, "message": "..." }.

Preview - ?api=connector-preview (POST)

Body { "id": N } previews one connector; omit id to preview all enabled connectors, which returns results and errors arrays. A single preview returns connector_id, connector_name, a snapshot hash, per-file plans (path, identity, size, modified_at, action, bytes_to_fetch, will_sync), and a summary with files, files_to_sync, already_current, bytes_to_fetch, and actions counts (new, append, unchanged, rotation, rename, reconcile, already_ingested, index_local). Disabled connectors error. See sync preview and snapshots.

Sync - ?api=connector-sync (POST)

Body { "id": N, "snapshot": "..." } queues one connector; omit id with { "snapshots": { "3": "..." } } to queue all enabled connectors. Pass the snapshot from preview - if the remote file set or calculated action plan changed, the background run is rejected. The worker executes only the confirmed actionable files. Each connector locks; a concurrent sync errors with "This connector is already synchronizing."

The endpoint responds with HTTP 202 and { "accepted": true, "worker_started": true, "run_ids": [N] }. A detached CLI worker performs the transfer outside the HTTP request. On systems where a worker cannot be launched automatically, worker_started is false, a warning is returned, and the run remains queued for the next scheduled CLI or Artisan sync command.

Runs - ?api=connector-runs (GET)

limit query (default 25, clamped 1-100). Returns run history newest-first with status (queued, running, success, failed), files_discovered, files_completed, files_updated, bytes_total, bytes_fetched, events_indexed, current_file, message, started_at, updated_at, finished_at, plus connector_name and connector_type. files_discovered counts actionable files in the confirmed run rather than every unchanged remote file. Progress is persisted after every fetched chunk and completed actionable file.

Tuning keys

sync.php_binary (optional absolute PHP CLI path), sync.shell_binary (optional POSIX shell path), sync.chunk_size (8388608), sync.prefix_hash_bytes (1048576), sync.max_discovered_files (10000), ssh.default_port (22), ssh.connect_timeout (10).

See also: The SSH connector and Ingest logs from a local directory.