Connector sync

A connector is "online" when the server has received a heartbeat from it within the last 5 minutes. "Unknown" between 5 and 30 minutes. "Offline" past 30 minutes.

If your connector flips offline unexpectedly, work through these checks.

Symptom

Decision tree

Connector status = offline?
  ├─ Heartbeat call returning 200?
  │  ├─ no  → see [Auth errors](/troubleshooting/auth-errors)
  │  └─ yes → connector process is silently dropping; check process logs
  └─ Status sync delay; refresh after 2 min

Sync job stuck in "running"?
  ├─ Job > 30 min? → likely worker throttle; see [Ingest failures](/troubleshooting/ingest-failures)
  └─ Job < 30 min? → wait; large catalogs take time

Data stale despite "online"?
  ├─ Was the delta cursor reset?
  └─ Are document changes reaching the connector at all?

Check 1: heartbeat works end-to-end

From the host running the connector:

curl -i -X POST https://app.aacsearch.com/api/connectors/<connectorId>/heartbeat \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json"

Expect:

HTTP/1.1 200 OK
{ "status": "ok", "timestamp": "2026-05-11T12:00:00.000Z" }

If 401, see Auth errors. If 200 but the dashboard still shows offline, wait 2 minutes — the dashboard caches lastUsedAt for performance.

Check 2: handshake successful

Every connector should call handshake on startup. Re-run it manually:

curl -X POST https://app.aacsearch.com/api/connectors/handshake \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json" \
  -d '{ "moduleVersion": "1.0.0", "platform": "prestashop" }'

Expect a 200 with projectId, indexSlug, connector metadata. The projectId returned here is what you pass as :projectId in subsequent sync calls.

If the response says the connector is disabled or not_found, re-enable it from Connectors → the connector → Settings.

Check 3: sync job lifecycle

A sync job goes through:

pending → running → completed (or failed)

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/sync-jobs \
  -H "Authorization: Bearer aa_admin_..."

Job rows include status, documentsTotal, documentsProcessed, error, startedAt, completedAt.

Check 4: full vs delta mode

Different connectors support different modes. The handshake response declares which:

{
	"connector": {
		"id": "prestashop",
		"syncModes": ["full", "delta"]
	}
}

If your connector only supports full and you call sync/delta, the request returns 400 sync_mode_not_supported. Switch to sync/full (slower but always works).

For high-frequency change tracking, sync/delta is the right choice — it sends only documents changed since the last cursor.

Check 5: delta cursor stuck

sync/delta is driven by a cursor stored in the connector. If the cursor is wrong (e.g., reset to a far-future timestamp), nothing new will be picked up.

Reset the cursor from the connector's own admin UI (each CMS module has a "force full re-sync" button), or call sync/full once to backfill.

# Reset and re-baseline
curl -X POST https://app.aacsearch.com/api/projects/<projectId>/sync/full \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json" \
  -d '{ "products": [...] }'

After a successful sync/full, the connector's local cursor should advance to "now".

Check 6: network reachability

If the host running the connector is in a private network, it must be able to reach https://app.aacsearch.com outbound on port 443. Check:

curl -v https://app.aacsearch.com/api/health
# expect HTTP/1.1 200 OK

If this fails, the firewall or proxy is blocking egress. Allowlist app.aacsearch.com.

Check 7: connector token scope

A connector token must have scope connector_write. If you minted a ss_search_* key by mistake and tried to use it as a connector token, every connector call will return 403 forbidden.

// Server-side, with admin key
const keys = await admin.listKeys();
const yours = keys.find((k) => k.id === "key_...");
console.log(yours.scopes); // must include "connector_write"

Mint the right kind from Search → API Keys → Create key → type "Connector". See API keys.

Common job errors

Fix matrix

Diagnostics packet

Related

• Connector API lifecycle — full endpoint reference
• Connector onboarding
• Ingest failures
• Auth errors