ai.spideriq/publish

Update a blog tag.

Upload a bg-video MP4 (or poster image) to R2 for the marketplace bg-video catalog. Reads the file from the local filesystem, POSTs multipart to /content/bg-videos/upload, server uploads to R2 at `bg-videos/<slug>.<ext>` and returns the public URL. Allowed extensions: mp4 (video), webp/png/jpg/jpeg/gif (poster). 50 MB cap (server-enforced). Unlike component uploads, this tool does NOT touch the catalog row — call `content_create_bg_video` or `content_update_bg_video` afterwards with the returned URL in `video_url` or `poster_url`. Both fields are strict-allowlisted to R2 hosts as of 2026-05-12. Returns: {url, key, size_bytes, content_type}.

Upload a preview thumbnail (PNG/JPG/GIF/WEBP/MP4) for a component. Reads the file from the local filesystem, sniffs the content-type from the extension, POSTs multipart to /content/components/{id}/upload-preview, and the server uploads to R2 + PATCHes preview_thumbnail_url on the row in one round-trip. Allowed extensions: png, jpg, jpeg, gif, webp, mp4. 5 MB cap (server-enforced; for larger animated MP4 use SpiderMedia upload then PATCH preview_thumbnail_url manually). CRO bug-fix bundle (2026-05-08, Antigravity report Bug 2): the API endpoint existed since Marketplace Admin Slice 1 (2026-04-28) but was not exposed through any agent-facing surface — agents using @spideriq/mcp-publish had no way to reach it. Now wired up. Returns: {url, key, size_bytes, content_type, component_id, preview_thumbnail_url}.

Upload a preview image (PNG/JPG/GIF/WebP) for a site template. Reads the file from the local filesystem, POSTs multipart to /content/site-templates/{slug}/upload-preview, server uploads to R2 at `templates/<slug>.<ext>` and returns the public URL. Allowed extensions: png, jpg, jpeg, gif, webp. 5 MB cap. Unlike component uploads, this tool does NOT patch the catalog row — call `content_update_site_template` afterwards with the returned URL in `preview_thumbnail_url` (and optionally `preview_url`). Both fields are strict-allowlisted to R2 + curated preview hosts as of 2026-05-12. Returns: {url, key, size_bytes, content_type}.

Verify DNS for a custom domain (checks CNAME/A record).

Open a URL in a real browser and report what an end-user actually sees. Returns screenshot + DOM info + console errors + failed requests + per-assertion results. USE: verify a content page or form is rendering correctly after a publish operation; catch silent-200-with-broken-content failures that monitoring doesn't see. NOT: don't use for crawling external sites; URL allowlist restricts to spideriq.ai subdomains + tenant verified custom domains. CRITICAL ASSERTION RULE (from learnings_visual_check_assert_on_shadow_hosts.md, codified 2026-05-18): when verifying a form is rendering correctly, ALWAYS assert on `dom.shadow_hosts.includes("spideriq-form")`. DO NOT assert on `body_text_preview` for cross-origin iframe contents — the iframe body is opaque to the parent page's DOM, so field labels and button text are NOT in body_text_preview even when the form is rendering correctly. Same applies to any custom-element shadow-host: assert on its tag name in dom.shadow_hosts, not on body text. WARN: screenshot upload may be degraded if R2 isn't configured; check screenshot_url for null. Engine still works in degraded mode. PITFALLS: - Asserting on body_text_preview for embedded form/booking widgets — will FAIL even on a working form, because the iframe body is cross-origin. - Forgetting to pass viewport='mobile' when checking responsive behavior — defaults to desktop 1440x900. - Hitting non-allowlisted URLs — will return URL_NOT_WHITELISTED envelope. LIMITS: - 30s default / 60s hard-cap timeout per check - 5MB page-size cap - 20 requests/min per client

Create a new project (website) in the current workspace. Returns the new project including its `proj_` id. May return 403 with an upgrade CTA if the workspace is already at its plan's project cap (max_deployed_sites).

Delete a file from your SpiderMedia bucket by storage key.

Import many listings into a category in one transaction. Max 5000 per call. Primary path for IDAP dumps + SpiderMaps job outputs. Each listing accepts the same fields as directory_upsert_listing. Upsert keyed on (category, slug); missing slugs auto-generate from name. Returns {upserted, failed, affected_cities: ["city-slug-1", ...], failures}. Refreshes category counts + city_stats materialized view on success.

Create a directory category. SEO templates accept {category}, {city}, {listing} placeholders. Example: {name: "Plumbers", seo_title_template: "Best {category} in {city} | Acme Directory"}.

Delete a directory category and all its listings (cascade).

Delete a listing by (category_slug, listing_slug). Refreshes city_stats.

Get a single category plus every city that has published listings in it.

Populate a directory category from the tenant's IDAP data (norm_cli_*.businesses). norm_cli_* is the canonical store for every business SpiderIQ has seen for this tenant (SpiderMaps + SpiderSite + SpiderCompanyData + SpiderPeople merged). This reads directly — no scheduler, no sync pipeline, no external call. Agent re-runs this tool whenever they want to refresh the directory. Filters (all optional): category_filter matches the categories[] array, country_code exact (uppercase), city is ILIKE substring, rating_min is inclusive. limit caps at 5000 to align with bulk_upsert. Returns {upserted, failed, source_rows, affected_cities, source_schema, filter, failures?, hint?}. If the tenant has no norm_cli_* schema yet (never ran SpiderMaps), hint explains the workaround.

List every directory category for the current tenant (includes empty ones). Returns {categories: [{id, name, slug, description, listing_count, city_count, seo_title_template, seo_description_template, ...}], total, page, page_size}.

List directory listings. Filter by category, city, status. Use this to verify what an IDAP dump wrote, or to audit a category before publishing changes.

Update category fields. Pass only the fields you want to change.

Create or update a single listing in a category. Upsert keyed on (category, slug). For bulk work (IDAP dumps, SpiderMaps job output), use directory_bulk_upsert_listings instead — it's one call vs N.

Get information about the SpiderIQ API and your connection.

Check if you are authenticated and get current user info.

Get media storage statistics (file counts, storage used, by type).

Get statistics about job queues (pending jobs, consumers, etc.).

Fetch the full markdown content of a SpiderPublish recipe (or rule) from @spideriq/skills. Pass the logical name from list_recipes. Returns the recipe text verbatim — paste-able into the working context, or use as a reference while implementing.

Get processing status for a video (encoding, ready, failed).

Check if the SpiderIQ API is healthy and responsive.

Import file(s) from URL into your SpiderMedia bucket. Supports single URL or batch. Auto-proxies Instagram/Facebook/Twitter CDN URLs.

Fetch live items from a registered content data source — the same door a kind='dynamic' component binds to (Live Data). Sibling of list_data_sources. Use this to PREVIEW what a dynamic component will render, or to discover a source's row shape before wiring a component's `sources`. It returns real, published, tenant-scoped records. v1 sources: posts, authors, categories, tags, changelog. (idap.* collections → 501 Phase 2; a singleton like idap.lead → 422 — those reach /lp/ templates as `lead`.) Filtering: pass `filter` keys matching the source's filterable fields (discover via list_data_sources), e.g. {"tag":"news"} on posts. `sort` is a single field with optional ":asc"/":desc" (or "-field"); `limit` (1-500) + `offset` paginate; `fields` trims the returned keys. Returns { items: [...], total, source_id }. Public read (X-Content-Domain tenant scope).

List the 9 registered content data sources that drive kind='dynamic' components (Phase D). Use this to discover the available source_id values when an agent is configuring a Dynamic block (List, Item Details, etc.). The registry includes: - 4 internal CMS collections: posts, authors, categories, tags - 4 IDAP collections: idap.countries → idap.cities → {idap.streets, idap.businesses} (hierarchical — pass --parent to walk the tree) - 1 singleton: idap.lead (per-request visitor lead context; only Item Details accepts it) Each source carries: - id (use as the source_id in DataBinding / SourceBinding) - label + description (human-readable) - parent_id (NULL for top-level; set for hierarchical children) - is_collection (false for singletons like idap.lead — only item_details binds these) - schema_json.fields[] (filterable + sortable per field) - schema_json.filters[] (named filter helpers) Public read.

List files in your SpiderMedia bucket.

List the projects (websites) in the current workspace. Each project has an `id` (proj_xxx) that you pass as the optional `project` argument of any content/template tool — or bind via `spideriq use <workspace> --project <proj_>` — to scope content operations to that website.

List all SpiderPublish workflow recipes shipped in @spideriq/skills. Returns name, description, and kind (rule | recipe | config) for each manifest entry. Call get_recipe(name) to read full content. Use this when the user asks "how do I X?" — the recipe index points you at a known-good workflow markdown.

List videos in your SpiderMedia bucket.

List all configured workspaces and their authentication status.

Remove stored authentication credentials.

Test-fire a submission against a dynamic form block. NOT the production submit path — real form submissions come from a visitor's browser via POST /content/forms/{form_id}/submit (no auth). This MCP tool exists so agents can validate a form's wiring during authoring + smoke-test before publishing. When to use: - After authoring a new form block, fire a synthetic submission to confirm validation + persistence work. - After changing fields / submit_url / fallback_idap_lead, verify the new behaviour without leaving the editor. - Debugging cross-tenant isolation: pick a form_id from one tenant, attempt to write under another — server returns 404, never silently misroutes. Cross-tenant isolation: form_id is the composite "<page_uuid>:<block_uuid>". The server resolves client_id ONLY from the page row; no tenant signal is accepted in the URL or body. A form_id from a different tenant simply 404s. Validation: - Required fields must be present + non-empty. - Field type drives coercion (number → float, checkbox → bool, select/radio → must match options). - Unknown field names rejected with 400. Returns the full FormSubmitResponse: ok, submission_id (when persisted), success_action ('redirect' | 'message' | 'modal'), success_redirect_url, success_message, webhook_status (when submit_url is configured).

Cross-table search across bg-videos / components / site-templates by AI-discovery axes (Phase D). Use this BEFORE content_list_marketplace_components / content_list_marketplace_bg_videos when the user asks for an asset by intent ("a calm cinematic background video for a luxury hotel") rather than by category. The 4 universal axes (mood / palette / brand_fit / scene_type) plus per-asset agent_meta narrow the catalog by behaviour, not by component name. Universal axes (controlled vocabulary, see marketplace_taxonomy.py): - mood: calm, energetic, bold, confident, dreamy, futuristic, urban, minimal, warm, sensory, editorial, professional, friendly, clear, technical, credible - palette: free-form (e.g. monochrome, deep-blue, cream, neutral-warm) - brand_fit: saas, agency, ecommerce, fintech, real-estate, hospitality, restaurant, wellness, healthcare, blog, publication, personal, tech, design, consulting, outdoor, lifestyle - scene_type: hero-bold, feature-grid, pricing-tiers, social-proof, faq-accordion, conversion-cta, navigation-header, navigation-footer, data-collection-form, editorial-content, team-grid (components); city-aerial, nature-landscape, abstract-motion, food-prep, people-lifestyle, tech-hardware (bg-videos); marketing-site, docs-site, directory-site, portfolio-site (site-templates) Per-asset agent_meta (use marketplace_get_help for the full vocabulary): - bg-video: pace, time_of_day, weather, has_people, aspect_ratio, has_audio, music_tempo_bpm, transcript - component: interaction_pattern, trigger_kind, placement, motion_safety, conversion_strategy - site-template: page_count, has_blog, has_pricing, has_directory, has_booking, conversion_strategy, style_aesthetic, component_set Restrict the search to specific asset types via asset_types — e.g. asset_types=["bg_video"] when you need just a hero background, ["component","site_template"] when you're planning a full page. Public read, no auth required.

Suggest mood / palette / brand_fit_tags / scene_type / agent_meta for one marketplace asset using the SpiderGate V2 inference engine. Two-step apply pattern (recommended): 1. Call `marketplace_suggest_agent_meta` to get a SuggestEnvelope with proposed values + per-key confidence (high / medium / low → action: auto_apply | review | drop). 2. Review the envelope. For values you trust, call the matching apply tool: - bg_video → set_bg_video_agent_meta - component → set_component_agent_meta - site_template → set_site_template_agent_meta The apply tools are gated (dry_run=true default + confirm_token). They mark the row `agent_meta_source='llm_inferred'` so future bulk re-runs can distinguish machine suggestions from human curation. Anti-hallucination: the engine validates proposed values against the locked Pydantic enums BEFORE returning. Off-vocab values are dropped and listed in `dropped_keys` so you can audit suggestions that didn't make the cut. Universal `palette` is intentionally open-vocabulary. Confidence-gated apply (locked thresholds 0.75 / 0.55): - action="auto_apply" → safe to apply directly (≥0.75 + vocab match) - action="review" → human eyeball recommended (0.55–0.75) - action="drop" → engine already dropped these — don't apply Cost: <$0.01 per call (Opus 4.7 via the spideriq/vision or spideriq/lead-analysis task aliases). Vision is used for bg-videos when poster_url is present; text-only otherwise. Super_admin only.

Insert a marketplace section into an existing page. Phase 11+12 gated. When to use: - Adding a hero / pricing / FAQ block to a page the customer already has - Programmatic page assembly: list sections → preview → insert → publish position semantics: - "end" (default) — append at the end of the blocks array - "start" — prepend - "before" / "after" — relative to anchor_block_id (REQUIRED when used) - integer — explicit 0-based index, clamped to [0, len(blocks)] Phase 11+12 flow: 1. Call with dry_run=true → returns {dry_run, preview, confirm_token, expires_at} 2. Inspect the preview (insertion_index, new_block_id, blocks_count_before/after) 3. Call again with confirm_token=<token> → mutates the page and returns the new block id The inserted block is type='component' with the requested component_slug + props. The page itself is NOT republished — call content_publish_page after if needed, or content_deploy_site to push everything live.

Request access to SpiderIQ API. This sends an approval email to the admin. After calling this, use check_access_status to poll for approval. Once approved, the token is automatically saved for subsequent API calls.

Patch agent-discovery axes + agent_meta on a bg-video catalog row (super_admin). Phase 11+12 gated. Same shape as set_component_agent_meta, but BgVideoAgentMeta has different keys: - pace: slow, medium, fast (slow=meditative, medium=narrative, fast=energetic) - time_of_day: dawn, day, dusk, night - weather: clear, cloudy, rain, snow, fog, stormy (NULL = indoor / abstract) - has_people: bool (TRUE if humans visible) - aspect_ratio: 16:9, 9:16, 1:1, 4:3, 21:9 - has_audio: bool - music_tempo_bpm: 20–300 (only meaningful when has_audio=true) - transcript: ≤ 2000 chars (accessibility + agent context) The bg-video catalog is global — every tenant sees the same rows — so this is super_admin only on the server. replication_prompt also accepted for free-form curator notes. Defaults dry_run=true.

Patch the agent-discovery axes on a component: universal axes (mood / palette / brand_fit_tags / scene_type) + per-component agent_meta JSONB. Phase 11+12 gated. Use this to make a component findable by intent through marketplace_search. Strict enum validation at the API boundary — unknown values 422 with the accepted vocabulary listed. agent_meta keys (ComponentAgentMeta, extra="forbid"): - interaction_pattern: static, click, hover, scroll, timer, form, drag - trigger_kind: page-load, scroll-into-view, click, hover, exit-intent, timer-fixed-date, timer-elapsed, form-submit, geo-match, none - placement: above-fold, below-fold, side-rail, modal, toast, footer, header, any - motion_safety: bool (TRUE if component honours prefers-reduced-motion) - accessibility_notes: string ≤ 1000 chars - conversion_strategy: primary-cta, secondary-cta, trust, scarcity, social-proof, education, navigation, none Pass only the fields you want to change — exclude_unset semantics. Defaults dry_run=true.

Set the 4-class behavioural taxonomy on a component: kind ∈ {static, interactive, dynamic, extension}. Phase 11+12 gated. When to use: - Curating a freshly-created custom component into the right marketplace tab - Reclassifying a legacy 'static' component as 'interactive' once you add JS - Promoting a Dynamic component (kind='dynamic' requires block_type + sources to already be set on the row, or this PATCH 400s on the DB CHECK constraint) The DB CHECK constraints (migration 174) enforce kind invariants — setting kind='dynamic' on a row missing block_type returns 400 with a specific constraint message. Phase A schemas (marketplace_taxonomy.py) define the strict enum. dry_run=true (default when neither flag set) returns a preview envelope with a confirm_token; pass confirm_token=<token> to commit.

Patch agent-discovery axes + agent_meta on a site_template catalog row (super_admin). Phase 11+12 gated. SiteTemplateAgentMeta keys: - page_count: 1–200 (number of pages the template ships with) - has_blog: bool - has_pricing: bool - has_directory: bool (programmatic SEO target) - has_booking: bool (SpiderBook integration) - conversion_strategy: same vocabulary as ComponentAgentMeta - style_aesthetic: minimal, bold, editorial, playful, premium, technical, brutalist, soft - component_set: array of component slugs the template ships with (≤ 100) The site-template catalog is global — super_admin only. Defaults dry_run=true.

Apply a pre-built theme to your site. Copies all theme templates to your template set. Phase 11+12: defaults to dry_run=true. Review the preview, then call again with confirm_token to actually apply.

Delete a custom template (reverts to the theme default for that path). Phase 11+12 Lock 4 gate is opt-in via dry_run/confirm_token (defaults preserve immediate-delete for backward compat).

Get a Liquid template source code by path (e.g. "templates/blog.liquid"). Returns YOUR tenant's KV override if one exists, otherwise the bundled default-theme file. A 404 means neither exists for this tenant — it does NOT mean the feature is missing: the page can still render from the default theme even when this returns 404 (e.g. templates/changelog.liquid). Likewise, a large inline-CSS template here is your own prior customization, not what SpiderPublish ships.

Get template config: current theme, route overrides, settings, and connected data sources.

SpiderPublishREADME — agent orchestration entry-point. Returns four sections in one response: • reference — canonical schema (content types, block types, Liquid filters/tags, template structure, data sources). The exact YAML/JSON/MD payload the legacy tool returned. Includes per-block-type field maps + agent-natural alias hints (2026-05-22 usability F-19) so an agent that writes `hero.title` instead of `hero.headline` catches the mistake before publishing. • site_context — current spideriq.json binding (client_id, project_name, brand_name) walked up from cwd; null when unbound. • recipes — workflow markdowns from @spideriq/skills (build-a- homepage, add-a-component, swap-a-hero-block, clone-a-site, add-a-domain). Read the matching one BEFORE improvising. • routing — "if user asks X, call tool Y" rules. Adopt before improvising. Call this FIRST in any SpiderPublish-related conversation. The reference still comes from /api/v1/content/help so it tracks the deployed API. For the live theme's per-block-type fields, call `template_inspect_block_fields(block_type)` — it returns the canonical fields the ACTIVE theme's snippet reads + the agent-natural alias map.

Get the canonical `data.*` fields the default theme reads for a block type, plus the agent-natural alias map. Use this BEFORE inserting a non-component block (hero, cta_section, stats_bar, comparison_table, etc.) to avoid the silent-blank-section trap from the 2026-05-22 usability report (F-9). Returns: • fields — what the snippet actually reads • _aliases — common mistakes → canonical field name (e.g. {"title": "headline", "cta_text": "cta_primary (object: {label, url})"}) • _anti_patterns — shapes that 422 (e.g. rich_text + data.content as a string is REJECTED — pass data.html instead) • _notes — free-form caveats Omit `block_type` to list all known block types. Public read, no auth.

List all custom Liquid templates for your site.