API reference

The WoalzCraft Brain is a FastAPI service hosted at https://woalzcraft-brain.woalz.com. It serves the plugin, but anyone with a valid key can call it directly. The plugin reaches it only for optional community-knowledge features; it is off until you sign in.

Authentication

All write endpoints and most read endpoints require a bearer token:

Authorization: Bearer <your-key>

Key tiers

Brain access is not metered, there is no per-tier request quota. The limits below are fair-use ceilings to prevent abuse; normal usage never hits them. Tiers mainly distinguish how a key was obtained and what it can do (read vs. contribute vs. administer).

Read access (search, browse, fetch entries) is free on every tier. Contribution (write) keys are issued to community contributors, not sold; see Contributing. The plugin's own license state (Pro vs. not-yet-activated) is a separate, plugin-side concept from these Brain key tiers, see the pricing page.

Anonymous signup (legacy)

POST /auth/signup-anonymous
Content-Type: application/json

{
  "machine_fp": "<32-char hex hash>",
  "plugin_version": "Batara.0.96.8",
  "install_source": "fab"
}

Returns a fresh community-tier key. Rate-limited per IP, with a lifetime cap per fingerprint. This endpoint remains for direct API use, but the current plugin signs in first (the "Sign in with Woalz" device flow) rather than auto-provisioning an anonymous key.

The install_source field classifies the install at runtime for per-channel analytics:

Core endpoints

Entries

GET /entries?entry_type=example&tier=gold&limit=20

List approved entries. Filterable by entry_type (example | node_ref | pattern), tier (gold | candidate | raw), category, tag, and ue5.

Semantic search

GET /search?q=<query>&limit=5
Authorization: Bearer <any-key>

Nearest-neighbour search over entry embeddings (pgvector HNSW). Returns:

{
  "query": "spawn a cube on begin play",
  "results": [
    {
      "entry": { "id": "...", "prompt": "...", "blueprint_json": { ... } },
      "score": 0.87,
      "match_type": "semantic"
    }
  ],
  "total": 5,
  "cached": false
}

Contribute

POST /contribute/blueprint
Authorization: Bearer <write-or-admin-key>
Content-Type: application/json

{
  "prompt": "spawn a cube on begin play",
  "blueprint_json": { ... },
  "quality_score": 0.95,
  "connection_rate": 1.0,
  "compile_score": 1.0,
  "ai_provider": "claude"
}

Runs a 3-layer dedup check (exact-Gold, exact-Candidate, semantic) and either accepts, merges quality into an existing candidate, or rejects as a duplicate.

Admin endpoints

All under /admin/* and require an admin-tier key:

Interactive schema

The full OpenAPI schema and a live try-it-out are the authoritative reference, kept in sync with the running service automatically, at woalzcraft-brain.woalz.com/docs.

Rate limits

Configured via env vars; current live values are readable at /admin/settings. Limits apply per-key for authenticated calls and per-IP for /auth/signup-anonymous. Beyond the limit you'll get 429 Too Many Requests with a Retry-After header.

Status codes we use