scrapewise_update_matcher_job
Saves the group's product-matching setup (the portal canvas's save): main list (masterData.jobId),
ID column (masterData.targetField), match lines (masterData.matchers; per source
masterData.matchersByScope keyed by run id) and the runs to match (scope).
What a save does — read before calling:
- Classic group: draft=false REPLACES the previous match result (matched rows and jobs deleted) and runs;
draft=true only stores the setup.
- Group on the newer matching engine: the SAME job is updated in place. The owner (Full key or
portal) saves (draft=true) and runs (draft=false) it, like a Scrapewise admin key: text lines,
picture lines (masterData.matchers with imageField / imageScopeField), the ID column and every
per-source setting are the owner's. The old picture switch
(imageMatchingEnabled) is stored off on this engine.
- Photo checks: a group compares photos when it has a picture line. Off: remove the picture line, or
imageMatchingEnabled=false plus clearFields ["imageMatchingEnabled"].
- version: copy it unchanged, as a string, from your last scrapewise_get_matcher_job or save answer
("" when it was "", never null). Required for a newer-engine group's owner; checked whenever
sent. 409 VERSION_CHANGED carries currentVersion: read again, redo your change, send that. Without
version a classic save overwrites (last writer wins).
- draft, requireIdle, afterGroupId, imageConfigManaged are request controls, never stored.
- On a newer-engine group the main list changes through Scrapewise support only (400). The ID column
(masterData.targetField, targetFieldByScope, targetScopeFieldByScope) is the owner's: a change is
saved with the ID_COLUMN_CHANGED warning. Nothing is deleted then: the current results, review
pairs and saved review decisions stay until the next run writes rows under the new ID column
(decisions saved under the old column do not carry over to those rows).
- warnings [{field, code, message}]: ID_COLUMN_CHANGED (above), IGNORED_BY_ENGINE (identityCol
changed on a newer-engine group: saved, ignored by the engine), NO_RUN_ON_DRAFT (afterGroupId on
such a draft: no effect).
identityCol "" = keep the stored one.
- Newer engine: a per-source column (scopeField) goes in masterData.matchersByScope[<runId>]; a
renamed flat line no per-source list carries is 400 FLAT_SCOPE_FIELD_LOST.
- Refused while free or AI-agent matching runs on the group.
- Per-shop picture settings (imageMatchingEnabledByScope, imageLeft/RightColByScope) are kept for
AI-agent keys; imageConfigManaged=false clears them.
- schedule: PUT never clears a schedule (absent or null keeps it); change or clear it via
scrapewise_update_matcher_schedule.
- masterData.reviewMaxByScope / reviewFloorByScope = per-feed review band (score > max -> MATCH,
< floor -> NO), keyed by scope job id, both or neither.
- A held run keeps the previous matches; scrapewise_get_matcher_history says why.
Args:
- id (string, path, required): the group's id.
- idempotency_key (string, query): REQUIRED for AI-agent keys. New value per save; the same
value only to retry it (the retry gets the first answer; nothing runs twice). After a 4xx
nothing was saved: retry with the SAME key.
- body (MatcherJobDTO, required): masterData + scope (FINISHED run ids, one per source, from
scrapewise_get_matcher_scope_jobs or scrapewise_get_scraper_load_history) + draft + version.
requireIdle=true refuses while this group's matching or any of its scrapers runs;
afterGroupId=<group id> refuses while that group is matching (not on a newer-engine draft). Both
are checked at save time. replaceRunning=true (Run only): stop the running run, start again (work
lost). Run only: autoMatches KEEP_ADD|REPLACE, manualMatches KEEP|FRESH (undo FRESH:
scrapewise_update_matcher_fresh_undo).
- customerRef (string, query, optional): admin key in Take Over only: that customer's
customerUniqueRef.
Returns:
The saved MatcherJobDTO (status INITIAL/QUEUED when a run starts, PENDING for a draft; a newer-engine
job keeps its status) with the new version for the next save.
Examples:
- Use when: "match group {id} on EAN against two sources if nothing runs" -> scope, matchers,
requireIdle=true, a fresh idempotency_key.
- Use when: "save this setup without running it" -> draft=true.
- Don't use when: only reading the setup -> scrapewise_get_matcher_job.
Error Handling:
Nothing was changed in each.
- 400 IDEMPOTENCY_KEY_REQUIRED (AI-agent key without idempotency_key); 400 VERSION_REQUIRED (owner of
a newer-engine group sent no version); 400 FIELD_INVALID (bad identityCol, autoMatches or
manualMatches).
- 400 (CustomerError): a scope run of another group, a bad line, column or afterGroupId; a main-list
change on a newer-engine group ("Contact support@scrapewise.ai with group id <id>.").
- 402: the wallet does not cover the run (run servers); the body carries the figures.
- 404: unknown or another customer's group.
- 409 VERSION_CHANGED: changed since your read; read again, redo, send currentVersion.
- 409 OWN_MATCH_RUNNING / SCRAPER_RUN_IN_PROGRESS / OTHER_GROUP_MATCHING: wait, save again with the
SAME idempotency_key.
- 409 IDEMPOTENCY_IN_FLIGHT: the same save is still running; retry shortly.
- 409 ARGS_HASH_MISMATCH: the key was used for a different request; use a new key.
- 409 TAKE_OVER_ACTIVE: end Take Over or send customerRef.
- 429 OWNER_EDIT_RATE_LIMIT: over 10 owner saves of this group in 10 minutes; wait Retry-After
seconds, retry with the SAME idempotency_key.
- 401 Unauthorized; 403 for a read-only key.
- 5xx: the save may have landed; read again before retrying.[runtime hint] This tool returns JSON-as-text — its response shape is dynamic (per-scraper itemsConfig, file binary, etc.) so the MCP outputSchema is omitted. Do not rely on the presence of any specific field in the response; treat the result as a string-or-object blob and parse defensively.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"id": "<id>",
"idempotency_key": "<idempotency_key>",
"body": "<body>"
},
"name": "scrapewise_update_matcher_job"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the group's id. | |
| body | Yes | masterData + scope (FINISHED run ids, one per source, from scrapewise_get_matcher_scope_jobs or scrapewise_get_scraper_load_history) + draft + version. requireIdle=true refuses while this group's matching or any of its scrapers runs; afterGroupId=<group id> refuses while that group is matching (not on a newer-engine draft). Both are checked at save time. | |
| customerRef | No | Admin keys in Take Over only: the customerUniqueRef of the customer the admin works for. Required then; leave it out otherwise. | |
| idempotency_key | Yes | Required for AI-agent keys: a new value per new save, the same value only to retry it. |