Component System — AI Agent Reference

v1.0.0 | 2026-04-13

Everything an AI agent needs to create, publish, and use SpiderIQ components across all 4 interactivity tiers. This document is self-contained — no other docs needed.

Full guides: Component Builder Guide | Tiers Reference

Discovery

# Full content reference (YAML, ~2,867 tokens)
GET /api/v1/content/help

# Available CDN libraries for Tier 3
GET /api/v1/content/cdn-allowlist

# Published components (your client + global)
GET /api/v1/content/components

Lifecycle

create (POST) → edit (PATCH) → publish (POST) → use in page block → new version (POST, same slug, bumped version)

Status flow: draft → published → archived

Field Reference

Field	Type	Required	Tier	Description
`slug`	string	Yes	All	URL-safe identifier (kebab-case)
`name`	string	Yes	All	Display name
`version`	string	No	All	Semver (default `"1.0.0"`)
`category`	enum	No	All	`hero`, `cta`, `faq`, `pricing`, `features`, `testimonials`, `contact_form`, `footer`, `header`, `gallery`, `stats`, `custom`
`description`	string	No	All	Short description
`html_template`	string	Yes (T1-3)	1-3	Liquid HTML template. Access props via `{{ props.field }}`
`css`	string	No	1-3	Component CSS (scoped via Shadow DOM)
`js`	string	No	2-3	Vanilla JS. Receives `root` (shadowRoot) and `props` args
`dependencies`	string[]	No	3	CDN allowlist keys (e.g., `["gsap", "chartjs"]`)
`framework`	string	Yes (T4)	4	`"react"`, `"vue"`, or `"svelte"`
`source_code`	string	Yes (T4)	4	Framework source (JSX, Vue SFC, or Svelte)
`props_schema`	object	No	All	JSON Schema for prop validation
`default_props`	object	No	All	Default prop values (overridden by block props)
`thumbnail_url`	string	No	All	Preview image URL
`tags`	string[]	No	All	Discovery tags
`is_global`	boolean	No	All	Visible to all clients (default `false`)
`bundle_url`	string	Read-only	4	R2 CDN URL of built bundle
`build_status`	string	Read-only	4	`none`, `building`, `success`, `failed`
`build_error`	string	Read-only	4	Error message on build failure

Tier Selection

No JS needed?                          → Tier 1 (html_template + css)
Vanilla JS is enough?                  → Tier 2 (add js field)
Need GSAP / Chart.js / Swiper / etc?   → Tier 3 (add dependencies array)
Need React / Vue / Svelte?             → Tier 4 (add framework + source_code)

CDN Allowlist (Tier 3)

Key	Name	Category
`gsap`	GSAP Core	animation
`gsap/ScrollTrigger`	GSAP ScrollTrigger	animation
`gsap/Flip`	GSAP Flip	animation
`animejs`	anime.js	animation
`alpinejs`	Alpine.js	framework
`chartjs`	Chart.js	visualization
`lottie`	Lottie Web	animation
`swiper`	Swiper	carousel
`countup`	CountUp.js	animation
`three`	Three.js	3d

Current list: GET /api/v1/content/cdn-allowlist

Props Schema Patterns

String:

{ "headline": { "type": "string", "title": "Headline" } }

Number with range:

{ "columns": { "type": "integer", "minimum": 1, "maximum": 6, "default": 3 } }

Enum:

{ "style": { "type": "string", "enum": ["centered", "left", "split"] } }

Array of strings:

{ "features": { "type": "array", "items": { "type": "string" } } }

Array of objects (repeater):

{
  "items": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" }
      },
      "required": ["title"]
    }
  }
}

Example: Tier 1 Hero Component

Create

curl -X POST "https://spideriq.ai/api/v1/dashboard/content/components" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "hero-simple",
    "name": "Simple Hero",
    "category": "hero",
    "html_template": "<section class=\"hero\"><h1>{{ props.headline }}</h1><p>{{ props.subheadline }}</p><a href=\"{{ props.cta_url }}\" class=\"btn\">{{ props.cta_text }}</a></section>",
    "css": ":host { display: block; } .hero { padding: 5rem 2rem; text-align: center; background: linear-gradient(135deg, var(--primary), #111); color: white; } h1 { font-size: 3rem; margin: 0 0 1rem; } p { opacity: 0.85; margin: 0 0 2rem; } .btn { display: inline-block; padding: 0.75rem 2rem; background: white; color: var(--primary); border-radius: 0.5rem; text-decoration: none; font-weight: 600; }",
    "props_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" },
        "subheadline": { "type": "string" },
        "cta_text": { "type": "string" },
        "cta_url": { "type": "string" }
      },
      "required": ["headline"]
    },
    "default_props": { "cta_text": "Get Started", "cta_url": "/signup" }
  }'

Response: { "id": "abc123...", "slug": "hero-simple", "status": "draft", ... }

Publish

curl -X POST "https://spideriq.ai/api/v1/dashboard/content/components/abc123/publish" \
  -H "Authorization: Bearer $CLIENT_TOKEN"

Use in Page

curl -X POST "https://spideriq.ai/api/v1/dashboard/content/pages" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home",
    "slug": "home",
    "blocks": [
      {
        "id": "hero-1",
        "type": "component",
        "component_slug": "hero-simple",
        "props": { "headline": "Welcome to Acme", "subheadline": "AI-powered everything." }
      }
    ]
  }'

Example: Tier 3 Animated Stats

curl -X POST "https://spideriq.ai/api/v1/dashboard/content/components" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "stats-animated",
    "name": "Animated Stats",
    "category": "stats",
    "dependencies": ["gsap", "gsap/ScrollTrigger"],
    "html_template": "<section class=\"stats\">{% for s in props.stats %}<div class=\"stat\"><span class=\"val\" data-target=\"{{ s.value }}\">0</span><span class=\"lbl\">{{ s.label }}</span></div>{% endfor %}</section>",
    "css": ".stats { display: flex; gap: 3rem; justify-content: center; padding: 4rem 2rem; } .val { font-size: 3rem; font-weight: 700; color: var(--primary); display: block; } .lbl { font-size: 0.875rem; opacity: 0.7; text-transform: uppercase; }",
    "js": "gsap.registerPlugin(ScrollTrigger); root.querySelectorAll('.val').forEach(el => { gsap.fromTo(el, { textContent: 0 }, { textContent: parseInt(el.dataset.target), duration: 2, ease: 'power2.out', snap: { textContent: 1 }, scrollTrigger: { trigger: el, start: 'top 80%' } }); });",
    "props_schema": {
      "type": "object",
      "properties": {
        "stats": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": { "type": "integer" },
              "label": { "type": "string" }
            }
          }
        }
      },
      "required": ["stats"]
    }
  }'

API Reference

Dashboard (requires auth)

Method	Endpoint	Notes
`POST`	`/dashboard/content/components`	Create component
`GET`	`/dashboard/content/components`	List all (any status)
`GET`	`/dashboard/content/components/{id}`	Get by ID
`GET`	`/dashboard/content/components/by-slug/{slug}?version=`	Get by slug (optional version)
`PATCH`	`/dashboard/content/components/{id}`	Update draft component
`DELETE`	`/dashboard/content/components/{id}`	Delete component
`POST`	`/dashboard/content/components/{id}/publish`	Publish (202 for Tier 4)
`POST`	`/dashboard/content/components/{id}/archive`	Archive component
`GET`	`/dashboard/content/components/{id}/build-status`	Tier 4 build status
`POST`	`/dashboard/content/components/{id}/rebuild`	Tier 4 re-build (202)
`GET`	`/dashboard/content/components/{slug}/versions`	List all versions

Public (no auth)

Method	Endpoint	Notes
`GET`	`/content/components`	List published + global
`GET`	`/content/components/{slug}?version=`	Get published by slug
`GET`	`/content/cdn-allowlist`	List available CDN libraries

All endpoints are prefixed with /api/v1.

MCP Tools

Tool	Description
`content_create_component`	Create a new component (any tier)
`content_update_component`	Update an existing component
`content_publish_component`	Publish a component
`content_archive_component`	Archive a component
`content_list_components`	List components
`content_get_component`	Get component by ID or slug
`content_list_cdn_allowlist`	List available CDN libraries
`content_get_build_status`	Check Tier 4 build status
`content_rebuild_component`	Re-trigger Tier 4 build

Common Mistakes

Using document.querySelector() — Use root.querySelector(). Your JS runs inside the shadow root; document refers to the parent page.
Forgetting to publish — Only published components render on live pages. Draft components are invisible.
Using Tailwind classes — Tailwind CSS from the parent page does not penetrate Shadow DOM. Write plain CSS inside the css field.
Referencing unknown CDN keys — Dependency keys must exist in the CDN allowlist. Check GET /content/cdn-allowlist first.
Not polling build-status for Tier 4 — publish returns 202 (async). The component won't render until build_status: "success".
Setting framework without source_code — Both are required for Tier 4. Setting only framework creates an unbuildable component.
Using external stylesheets or @import — Shadow DOM blocks external CSS. All styles must be inline in the css field.
Not setting props_schema — Without a schema, props won't be validated. The component still works, but agents and the dashboard can't generate input forms.

Shadow DOM Rules

CSS is fully scoped — Component CSS cannot leak to the page or other components. Page CSS cannot affect component internals.
Use root.querySelector() — Never document.querySelector(). The root parameter is the ShadowRoot element.
var(--primary) works — CSS custom properties pierce Shadow DOM by design. Your site's primary_color is available as var(--primary).
No Tailwind, no @import, no external stylesheets — Write all CSS in the css field. It's scoped and isolated.
Each instance gets its own shadow root — Two instances of the same component on one page are fully independent.

Discovery​

Lifecycle​

Field Reference​

Tier Selection​

CDN Allowlist (Tier 3)​

Props Schema Patterns​

Example: Tier 1 Hero Component​

Create​

Publish​

Use in Page​

Example: Tier 3 Animated Stats​

API Reference​

Dashboard (requires auth)​

Public (no auth)​

MCP Tools​

Common Mistakes​

Shadow DOM Rules​