/api/drd/local/sync

GET

Kicks a differential download of the DRD directory into the local replica, sharded across healthy RAIDA servers. Returns immediately with a task_id and poll url (async task pattern). The core also syncs automatically on an interval when drd_sync_enabled=true (conf key drd_sync_interval_minutes, default 60). The local replica may lag the live directory; /api/drd/user/get remains the authoritative per-record read.

http://localhost:8080/api/drd/local/sync

Parameters

Name Type Required Description
full boolean No When true, wipe cursors and re-download everything. Default false (differential resume from stored cursors).

Responses

Success Response (200)

Returns immediately. The sync work runs in the background. Poll the provided url (equivalent to /api/system/tasks?task_id=…) for progress. If a sync is already running, the response is still 200 and carries that running task's id (idempotent kick).

{
    "command": "drd-local-sync",
    "success": true,
    "task_id": "Jul-11-26_03-15-22-pm-a1b2",
    "url": "http://localhost:8080/api/system/tasks?task_id=Jul-11-26_03-15-22-pm-a1b2",
    "full": false
}

Error Responses

500 Internal Server Error

The sync engine could not start a task.

{
    "error": true,
    "message": "Failed to start DRD sync",
    "code": 500
}

Examples

cURL Example

# Differential sync
curl -X GET "http://localhost:8080/api/drd/local/sync"

# Full re-download
curl -X GET "http://localhost:8080/api/drd/local/sync?full=true"

JavaScript Example

async function kickDrdSync(full = false) {
    const q = full ? '?full=true' : '';
    const kick = await fetch(`http://localhost:8080/api/drd/local/sync${q}`)
        .then(r => r.json());
    if (!kick.success) throw new Error(kick.message);

    // Poll until the task finishes
    while (true) {
        const poll = await fetch(kick.url).then(r => r.json());
        const status = poll.payload?.status ?? poll.status;
        if (status === 'success' || status === 'error' || status === 'failed') {
            return poll;
        }
        await new Promise(r => setTimeout(r, 2000));
    }
}

kickDrdSync().then(() => console.log('DRD replica updated'));

Python Example

import time
import requests

base = 'http://localhost:8080'
kick = requests.get(f'{base}/api/drd/local/sync', params={'full': 'false'}).json()
if not kick.get('success'):
    raise SystemExit(kick.get('message'))

poll_url = kick['url']
while True:
    poll = requests.get(poll_url).json()
    status = (poll.get('payload') or {}).get('status') or poll.get('status')
    if status in ('success', 'error', 'failed'):
        print('done:', status)
        break
    time.sleep(2)

Notes

  • Background auto-sync: when drd_sync_enabled=true, the core runs a cycle every drd_sync_interval_minutes minutes (default 60) without a REST call.
  • Kicking while a sync is already running returns the existing running task id — safe to call repeatedly from a dashboard mount.
  • Use /api/drd/local/status for replica health (record counts, shard cursors, sync_running) without starting a new cycle.
  • After sync, search via /api/drd/local/search. For a single live record, prefer /api/drd/user/get.