scrapewise_create_customer_schema
Upsert a JSON-Schema document owned by the authenticated customer. Customer
schemas constrain LLM output for AI-driven scrapers (`AI_CONF` mode): the
scraper feeds the schema to the LLM and the LLM is required to return data
matching that shape. Customer schemas exist alongside the global ones but are
only visible to their owning customer (`customerRef` is set automatically
from the auth principal — the caller cannot forge another customer's schema).
Upsert semantics differ by type. Non-CUSTOM: if `body.id` is set and matches an
existing customer-owned schema, it's updated in place; otherwise a new schema is
created. **CUSTOM is different: there is no update-in-place.** Every PUT for a
CUSTOM schema creates a brand-new immutable version — `body.id` is ignored for
CUSTOM (only `body.groupId` matters); `body.version` is always ignored for CUSTOM
too (the server atomically reserves the next version number). A scraper attached to
a CUSTOM schema's group always tracks that group's current latest version
automatically (live-latest binding) — you never need to re-attach a scraper after
adding a version. CUSTOM versions are immutable and cannot be deleted
(scrapewise_delete_customer_schema throws for them); version forward here instead.
The response always carries the persisted id (use it to attach to a scraper).
Args:
- body (SchemaDTO, required): the schema definition.
- id (string, optional): existing schema id; absent = create new. Ignored
for CUSTOM — use `groupId` instead to add a version to an existing group.
- version (int, required by the DTO shape, but ignored for CUSTOM): schema
version number for change tracking. For CUSTOM the server always computes
the next version itself; send any value.
- type (SchemaType, required): one of the SchemaType enum values
(PRODUCT, REVIEW, ARTICLE, CUSTOM, etc.)
- content (SchemaContent, required): the JSON-Schema document itself —
`properties` map, `required` array, etc. For CUSTOM, validated server-side
before anything is persisted: non-blank description, at least one field, no
blank/duplicate/reserved-keyword field names, ≤200 fields, ≤50 KB content —
violations return 400 with every failing field named in one message.
- description (string, optional for other types, REQUIRED non-blank for
CUSTOM): human-readable purpose, surfaced to the agent when a scraper
references this schema
- templateId / templateName (string, optional): if forked from a
BEBO-1406 template, the template provenance
- domainPatterns (list of strings, optional): domains this schema
is intended for (used by the auto-suggest UI; agent can ignore)
- groupId (string, optional, CUSTOM-only): omit to start a brand-new
CUSTOM schema group; supply an existing group's id (from a prior response,
or from scrapewise_list_custom_schema_groups) to add a new version to that
group instead. Ignored for non-CUSTOM types.
CUSTOM content: fields are `{"type":["string","null"],"description":"..."}` in
`items.properties`; order matters. `items.required`: Tells the AI this field should
always be filled in. Rows are kept even if it is empty. None marked ⇒ all fields asked
for (null when missing); unknown/duplicate names ignored. The fields decide what is
extracted: every matching item on the page, one or many. Omit `products.description`
to use the default "Extract every item on the page that matches these fields, as a
flat array. If only one item matches, return one. Use null for any missing fields.";
any other text is "custom instructions", kept as written. Same content as a built-in
schema ⇒ same result.
Returns:
`SchemaDTO` — the persisted schema (this specific new version, for CUSTOM) with
its assigned `id`. Use the `id` in subsequent scraper-create calls to attach this
schema to an AI_CONF scraper. For CUSTOM, also carries `groupId` — save it if you
plan to add further versions to this same group later. Note the response's
`version` is the server-assigned version for CUSTOM, not necessarily what you sent.
Examples:
- Use when: "create a product schema with fields title, price, sku" → build
content + call this op
- Use when: "update my 'reviews' schema to add author field" (non-CUSTOM) →
fetch via scrapewise_list_customer_schema, edit content, re-PUT with the same id
- Use when: "add a version to my existing custom schema" → call
scrapewise_list_custom_schema_groups to find the `groupId`, then PUT with that
`groupId` set (omit `id`) — this always creates a new version, never edits one
- Don't use when: a global (admin-managed) schema would cover the case →
global schemas are not exposed via the MCP surface; ask the operator to
surface or fork one rather than duplicating it as a customer schema
- Don't use when: you only want to read existing schemas →
scrapewise_list_customer_schema is read-only and cheaper
Error Handling:
- 400 if `content` violates JSON-Schema syntax or required fields missing, or
(CUSTOM) fails the field-level content validation described above.
- 401 Unauthorized if no Firebase JWT or API key.
- 500 INTERNAL with `correlationId` if persistence fails.[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": {
"body": "<body>"
},
"name": "scrapewise_create_customer_schema"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | the schema definition. |