API & MCP

Create an API key from your account page. The secret is a pf_… token, shown once. Send it on every request, either header works:

# X-API-Key
curl -H "X-API-Key: pf_xxx" https://app.tesselo.it/api/v1/patterns

# or Authorization: Bearer
curl -H "Authorization: Bearer pf_xxx" https://app.tesselo.it/api/v1/patterns

The same API key authenticates both the REST API and MCP.

Programmatic access (REST API and MCP) requires a Pro or Agency plan — the trial includes it. On Starter, API/MCP calls return 403. If your account is suspended (frozen), calls return 402.

• Pro / Agency / trial — full programmatic access
• Starter — no API/MCP → 403
• Frozen (suspended) — 402

Requests are bucketed per API key, by plan. Exceeding the limit returns 429 with a Retry-After header.

• Pro — 120 req/min
• Agency — 600 req/min
• trial — 120 req/min

Generation consumes credits: creating a pattern from a preset (POST /api/v1/sources/presets) or from a URL (create_pattern_from_url) costs 1 credit each. Render, mockup, and read operations cost 0. When your balance is exhausted, generation calls return 402.

Main endpoints, with minimal examples:

# create a source from a preset (generation: 1 credit)
curl -X POST https://app.tesselo.it/api/v1/sources/presets \
  -H "X-API-Key: pf_xxx" -H "Content-Type: application/json" \
  -d '{"preset":"floral","seed":42}'

# list your patterns (read: 0 credits)
curl https://app.tesselo.it/api/v1/patterns -H "X-API-Key: pf_xxx"

# create a pattern (generation: 1 credit)
curl -X POST https://app.tesselo.it/api/v1/patterns \
  -H "X-API-Key: pf_xxx" -H "Content-Type: application/json" \
  -d '{"source_id":1,"group":"p4"}'

# render a tile (render: 0 credits)
curl -X POST https://app.tesselo.it/api/v1/patterns/42/render \
  -H "X-API-Key: pf_xxx" -H "Content-Type: application/json" \
  -d '{"size":1200,"format":"png"}' --output tile.png

Call a tool with a single POST. Authentication is the same API key as REST; plan gating, rate limits, and credit metering apply to MCP too.

# run a tool
curl -X POST https://app.tesselo.it/api/v1/mcp/execute \
  -H "X-API-Key: pf_xxx" -H "Content-Type: application/json" \
  -d '{"tool":"list_patterns","arguments":{}}'

# fetch the tool manifest
curl https://app.tesselo.it/api/v1/mcp/info -H "X-API-Key: pf_xxx"

From the web UI, create a key under Settings → API keys, or hit the REST endpoint with a JWT:

curl -X POST https://app.tesselo.it/api/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-bot"}'

The response includes secret (a pf_… token) shown once. Send it on every request as X-API-Key.

List your patterns:

curl https://app.tesselo.it/api/v1/patterns \
  -H "X-API-Key: pf_..."

Render a tile (PNG, 1200 px square):

curl -X POST https://app.tesselo.it/api/v1/patterns/42/render \
  -H "X-API-Key: pf_..." -H "Content-Type: application/json" \
  -d '{"size":1200,"format":"png"}' --output tile.png

Render a surface sheet (Repper-style, with vignette):

curl -X POST https://app.tesselo.it/api/v1/patterns/42/render \
  -H "X-API-Key: pf_..." -H "Content-Type: application/json" \
  -d '{
    "mode":"surface","size":1200,
    "surface_width":4000,"surface_height":3000,
    "surface_effects":[{"id":"vignette","params":{"strength":0.4}}]
  }' --output sheet.png

Full OpenAPI schema and interactive try-it-out at /docs.

For remote MCP clients that speak JSON-RPC 2024-11-05 over SSE — the same wire protocol Claude Desktop uses internally.

# 1. open the SSE stream (long-lived)
curl -N https://app.tesselo.it/api/v1/mcp/sse -H "X-API-Key: pf_..."
# → event: endpoint
#   data: /api/v1/mcp/messages?session_id=<uuid>

# 2. POST JSON-RPC frames to the endpoint URL above
curl -X POST "https://app.tesselo.it/api/v1/mcp/messages?session_id=<uuid>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → reply arrives on the SSE stream as an "event: message"

Run the server locally; Claude launches it on demand. Requires access to the PatternForge database from the host (same DATABASE_URL as the server).

{
  "mcpServers": {
    "patternforge": {
      "command": "/path/to/backend/.venv/bin/python",
      "args": ["-m", "patternforge.mcp.stdio"],
      "env": {
        "PATTERNFORGE_API_KEY": "pf_...",
        "DATABASE_URL": "postgresql+psycopg://user:pass@host:5432/patternforge"
      }
    }
  }
}

For Claude Code, drop the same block into ~/.claude/claude_desktop_config.json.

14 tools cover the full pattern lifecycle. Get the live catalog from /api/v1/mcp/info.

• list_groups, list_effects, list_surface_effects — introspection
• upload_source_from_base64, create_pattern, create_pattern_from_url — ingest
• list_patterns, get_pattern, update_pattern, delete_pattern — CRUD
• render_pattern_tile, render_pattern_surface, render_aperiodic — render
• validate_symmetry — verify wallpaper-group invariants

MCP endpoints are bucketed per API key (or per SSE session) at the limit reported by /api/v1/mcp/info. Exceeding it returns 429 with Retry-After: 60.

Vendi prodotti personalizzabili sul tuo store senza scrivere codice: il plugin PatternForge Connect aggiunge un bottone Personalizzaalle schede prodotto e collega il tuo WooCommerce all'editor PatternForge.

• Installa il plugin PatternForge Connect sul tuo WordPress/WooCommerce e attivalo.
• In WP Admin → PatternForge incolla la tua API key (piano Pro o Agency), imposta il backend https://app.tesselo.it/api/v1 e l'editor https://app.tesselo.it.
• Scegli i prodotti da abilitare: sulla scheda prodotto comparirà il bottone Personalizza.
• Il cliente progetta nell'editor (su app.tesselo.it, senza login, sessione guest del tuo tenant) e torna al prodotto con il design applicato — l'URL riporta ?pf_pattern_id=N.
• Il pattern_id finisce nei meta dell'ordine: il tuo provider POD recupera il file di stampa dal pattern via API (GET /api/v1/patterns/{id} + render/export).

Lato server il plugin chiama POST /api/v1/embed/handoff con la tua API key e riceve l'editor_url a cui puntare il bottone.

curl -X POST https://app.tesselo.it/api/v1/embed/handoff \
  -H "X-API-Key: pf_xxx" -H "Content-Type: application/json" \
  -d '{"product_id":123,"return_url":"https://tuoshop.it/product/123"}'
# → { "editor_url": "https://app.tesselo.it/editor?handoff=..." }

Branding: PatternForge è un servizio di Tesselo.

PatternForge può notificare il tuo sistema in tempo reale via webhook in uscita. Crea le sottoscrizioni dalla pagina Integrazioni (piano Pro/Agency o trial).

Eventi disponibili:

• pattern.created — un nuovo pattern è stato creato
• design.applied — un design è stato avviato per un prodotto (handoff editor)
• mockup.ready — i mockup di un pattern sono pronti
• credits.low — il saldo crediti è sceso sotto soglia

Ogni richiesta è un POST JSON con corpo { "event": "...", "data": { ..., "account_id", "delivery_id" } } e questi header:

X-PatternForge-Event: <evento>
X-PatternForge-Signature: sha256=<hex>

Verifica firma:calcola l'HMAC-SHA256 del corpo grezzo della richiesta usando il secretdella sottoscrizione (mostrato una sola volta alla creazione) e confrontalo con l'header X-PatternForge-Signature.

Retry: fino a 5 tentativi con backoff progressivo (1m, 5m, 30m, 60m), poi la consegna è marcata failed. Idempotenza: deduplica lato ricevente usando data.delivery_id.