scrapewise_update_matcher_engine_setup
Replaces the whole engine setup of a group on the newer matching engine with raw (the shape of one
v2-groups.json group entry), and / or switches the newer engine for the group (engineEnabled). The
change is stored as a draft; the matcher checks it strictly within about a minute and only a clean
setup goes live (read it back: status ACTIVE). The group's owner (Full key or portal) changes the fields
whose writer is customer (GET include=fields); picture fields (imageLayer, imageScraperIds, the whole
noCodePath block, columns.image and the image role) and engineEnabled are Scrapewise's: leave them out (a PUT that leaves them out keeps them) or send them unchanged. A Scrapewise
admin key changes everything. To change a few fields use scrapewise_update_matcher_engine_setup_fields
instead; to restore, PUT an old version's raw (refused for the owner when it differs in a picture field).
Args:
- id (string, path, required): the group's id.
- idempotency_key (string, query): REQUIRED for AI-agent keys. A new value for each new save; the same
value only to retry that same save. After a 4xx nothing was saved: you may retry with the SAME key.
- body (required): editVersion (from the last read; required with raw), raw (the whole setup),
requireIdle (default true: refused while the group's matching or one of its scrapers runs). Do not
send engineEnabled (admin/support only): from the owner a value other than the current state is 403
ENGINE_SWITCH_ADMIN_ONLY ("Contact support@scrapewise.ai with group id <id>"); the current state is
a no-op.
- customerRef (string, query, optional): only for a Scrapewise admin key in Take Over.
Returns:
The small setup answer: status PENDING (the draft waits for the check), editVersion, saveWarnings.
VALIDATOR_DOWN = your draft is saved and waits for the check; the active setup is unchanged; do not
resend. A later read with REJECTED = the check refused the draft: the active setup is unchanged; your
next save starts from the active setup, so send your whole change again (an UNKNOWN_KEY refusal may
still go live after a matcher update until you save again).
Examples:
- Use when: "restore version 4 of group {id}" -> GET version=4, then PUT its raw with the current editVersion.
- Use when: "put group {id} on the newer engine" -> body {"engineEnabled": true}.
- Don't use when: you change one source's column -> scrapewise_update_matcher_engine_setup_fields.
Error Handling:
- 400 IDEMPOTENCY_KEY_REQUIRED, ENGINE_SETUP_INVALID (bad column name, explicit null),
UNKNOWN_SCRAPER_ID (a new id that is not a scraper of the group), JOB_NOT_OF_SOURCE (a pinned run of
another scraper or customer), NOT_ON_NEWER_ENGINE, ENGINE_SETUP_TOO_DEEP, PHOTO_LINE_VALUE_MISSING
(photoMode confirm / open while a picture line has no threshold). Nothing was changed.
- 409 VERSION_CHANGED (read again), SETUP_FROM_DB_OFF, NOT_SEEDED (wait a minute),
OWN_MATCH_RUNNING / SCRAPER_RUN_IN_PROGRESS (wait, retry with the SAME key),
ENGINE_DISABLE_NEEDS_EMPTY_MATCH, ENGINE_ENABLE_WAITS_FOR_RETRIGGER, TAKE_OVER_ACTIVE,
IDEMPOTENCY_IN_FLIGHT, ARGS_HASH_MISMATCH, PHOTO_SWITCH_STILL_ON (the owner takes photoMode off
confirm / veto / score while photo checks are on: switch them off in the match setup first).
- 403 FIELD_ADMIN_ONLY / FIELD_NOT_CUSTOMER_WRITABLE (a field the owner may not change),
ENGINE_SWITCH_ADMIN_ONLY (engineEnabled from the owner), NOT_ON_NEWER_ENGINE (the owner's setup for a group not on it); 403 for a read-only key.
- 413 ENGINE_SETUP_TOO_LARGE (over 256 KB); 503 FIELD_LIST_UNKNOWN.
- 429 OWNER_EDIT_RATE_LIMIT: more than 10 owner changes of this group in 10 minutes; wait Retry-After.
- IDEMPOTENCY_IN_FLIGHT (an idempotency conflict): retry after a second.
- 5xx: read again (scrapewise_get_matcher_engine_setup) before retrying.
- 401 Unauthorized; 404 unknown group or another customer's group. Nothing was changed in each refusal.[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_engine_setup"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the group's id. | |
| body | Yes | Replace the whole engine setup of a group (and / or switch the newer engine for it). | |
| 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. |