PATCH sync mode

PATCH adds and updates entities. Unlike DIFF, PATCH never deletes — anything not included in your upload is left alone.

This is the mode for layering data onto entities that already exist in the graph, whether they came from a managed integration or a different sync job. A PATCH upload is additive: properties you include are written, properties you don't include are untouched.

When to use PATCH

• You are enriching existing entities, not replacing a dataset.
• You don't have (or don't want to compute) the full set of entities — only the ones you have new data for.
• You only need to change entity properties; PATCH does not accept relationships.
• The properties you're setting do not need to survive a managed-integration re-sync. If they do, use OVERRIDE instead.

Example use cases

PATCH is the right mode in two situations: you're refreshing data on managed-integration entities faster than that integration's own DIFF cycle (and you accept that each integration run will reset to the integration's truth), or you're updating entities in a custom dataset that no managed integration owns. If you need values to survive a managed integration's next sync, use OVERRIDE instead.

Higher-frequency updates between managed-integration runs

Your AWS integration runs once an hour. Between runs, an internal process polls CloudWatch every five minutes and refreshes a lastErrorCount property on aws_lambda_function entities so dashboards stay closer to real-time.

• Scope: lambda-error-counts
• Mode: PATCH
• Why PATCH: You only need the value to live between integration runs. Each AWS sync re-asserts AWS's own state for these entities, and the next CloudWatch push refreshes lastErrorCount again. OVERRIDE would be wrong here because you do not want the value to persist across integration syncs.

POST /persister/synchronization/jobs
{
  "source": "api",
  "syncMode": "PATCH",
  "scope": "lambda-error-counts"
}

{
  "entities": [
    { "_id": "lambda-fn-123", "lastErrorCount": 4, "lastSampledAt": "2026-04-28T14:05:00Z" },
    { "_id": "lambda-fn-456", "lastErrorCount": 0, "lastSampledAt": "2026-04-28T14:05:00Z" }
  ]
}

Updating a custom dataset you already pushed

You maintain a Person dataset in JupiterOne by pushing a DIFF from your HRIS each night. During the day, a separate process updates a lastGoogleLoginAt property on those Persons hourly from the Google Workspace audit log.

• Scope: google-login-activity
• Mode: PATCH
• Why PATCH: No managed integration owns these entities; the only writers are your two custom syncs. PATCH lets the hourly update touch only lastGoogleLoginAt without disturbing anything the nightly DIFF set, and there's no integration DIFF to worry about resetting your values.

Required entity fields

PATCH lets you target by either _id or _key:

• When scope is defined: either _key or _id is required.
• When scope is not defined: _id is required.

_id is unambiguous globally; _key requires the scope context to resolve.

You do not need to include _type or _class on a PATCH upload — those are only required when the entity is being created.

Relationships are not allowed

PATCH rejects relationships:

Relationships are not allowed in PATCH jobs

If you need to add relationships, use DIFF (when you own both entities and the scope) or CROSS_SCOPE (when the from and to entities live in different scopes).

PATCH vs OVERRIDE vs the entity mutation API

PATCH, OVERRIDE, and the GraphQL updateEntity mutation can all write properties onto an existing entity, but they answer different questions about persistence:

Tool	Property survives the next managed-integration sync?	Best for
PATCH sync mode	No. PATCH writes the value onto the entity but does not register a persistent override. The next integration sync replaces the entity wholesale, and any PATCH-set property the integration doesn't itself assert is lost.	High-frequency refreshes of entities you own, or short-lived enrichments on managed entities that you actively re-PATCH.
OVERRIDE sync mode	Yes. OVERRIDE records the property as a persistent override; it is reapplied after every integration sync.	Bulk overrides across many managed entities (up to 10,000 per sync job) under a stable scope.
updateEntity GraphQL mutation	Yes. Properties set via updateEntity are recorded as persistent overrides on the target entity and survive every future integration sync.	One-off edits to a single entity, or scripts that touch a small number of entities and don't need to be grouped under a scope.

Pick PATCH only when "wiped by the next integration run" is acceptable — usually because you're going to re-PATCH on a tight cadence, or because no managed integration owns the entity. If you need the value to last, use OVERRIDE for batches and updateEntity for one-offs.

Example: PATCH sync job

POST /persister/synchronization/jobs

{
  "source": "api",
  "syncMode": "PATCH",
  "scope": "google-login-activity"
}

POST /persister/synchronization/jobs/{jobId}/upload

{
  "entities": [
    { "_id": "person-123", "lastGoogleLoginAt": "2026-04-28T14:00:00Z" },
    { "_id": "person-456", "lastGoogleLoginAt": "2026-04-28T13:42:00Z" }
  ]
}

POST /persister/synchronization/jobs/{jobId}/finalize

After finalize, the two persons have updated lastGoogleLoginAt. No other persons were affected. No entities or relationships were deleted.

Operational notes

• PATCH is non-destructive. Re-running PATCH with no entities is a no-op.
• Setting a property to null clears it for the targeted entity.
• Stale values aren't cleaned up. If you stop sending a property for an entity, the previous value stays on the entity. To remove it, send the entity with that property set to null.
• PATCH does not protect properties from managed integrations. A PATCH-set value lives on the entity until the source integration's next sync, at which point the entity is rewritten and any PATCH-set property the integration itself doesn't assert is lost. For values that need to survive every integration run, use OVERRIDE (sync-job batches) or the updateEntity GraphQL mutation (one-offs).

Common errors

Error	Cause	Fix
Relationships are not allowed in PATCH jobs	Uploaded relationships to a PATCH job.	Use DIFF or CROSS_SCOPE for relationships.
Required either _id or _key	Neither identifier present.	Include _id (preferred) or _key.
Property not visible after finalize	Property starts with _.	Custom property names cannot begin with _.

See the API reference for the complete error table.