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.

Authentication

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

Authorization: Bearer <your-key>

Key tiers

| Tier | Quota | Obtain via | | -------------- | ------------- | -------------------------------------------------------------- | | community | 60 req/hr | Plugin first-run auto-signup, or POST /auth/signup-anonymous | | user | 300 req/hr | Email-opt-in upgrade (sign up at woalz.com + verify email) | | woalz_free | (community-equiv) | Woalz Platform freemium account (auto-granted on plugin install) | | woalz_pro | (paid plan) | Woalz subscription via woalz.com or Fab Marketplace listing | | read | (legacy) | Historic keys; behave like community | | write | 30 req/min | Admin-issued; for agents that contribute entries | | admin | 60 req/min | Admin-issued; full CRUD + key management |

See Identity Strategy (plugin repo) for the full 5-mode model and per-channel tier provisioning behavior.

Anonymous signup

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

{
  "machine_fp": "<32-char hex hash>",
  "plugin_version": "0.9.0-alpha4",
  "install_source": "fab"
}

Returns a fresh wbk-c_... community-tier key. Rate-limited to 5/hour per IP; lifetime cap of 3 keys per fingerprint. The plugin does this transparently on first launch.

The install_source field (added in plugin v0.9.0-alpha4) classifies the install at runtime:

| Value | Meaning | | ----------------- | -------------------------------------------------------- | | project_manual | Plugin in [Project]/Plugins/ — dev install, default | | engine_manual | Plugin in Engine/Plugins/ (sideloaded, not Marketplace) | | fab | Plugin in Engine/Plugins/Marketplace/ or Engine/Plugins/Fab/ (from Epic Fab) | | woalz | Plugin install marker dropped by woalz.com installer | | unknown | Detection failed (defensive default) |

Brain admin dashboards segment usage by install_source 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, 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 duplicate.

Admin endpoints

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

| Route | Action | | ------------------------------------------------- | ------------------------------------------- | | GET /admin/stats | Aggregate counters | | GET /admin/analytics/timeline?days=30 | Daily signup / submission / approval series | | GET /admin/analytics/top-entries?limit=15 | Most-queried entries | | GET /admin/analytics/top-contributors | Contributor leaderboard | | GET /admin/entries?tier=... | Full entries listing (all statuses) | | PATCH /admin/entries/{id} | Update any entry field | | POST /admin/promote/{id} / /demote/{id} | Tier adjustments | | GET /admin/review-queue?status=pending | Correction proposals | | POST /admin/review-queue/{id}/merge / /reject | Decision | | GET /admin/stale-flags?status=active | Broken-per-UE flags | | GET /admin/keys / POST / DELETE | Key management | | GET /admin/audit | Immutable action trail | | GET /admin/settings | Current Brain config (read-only) |

Interactive schema

Full OpenAPI schema + live try-it-out at woalzcraft-brain.woalz.com/docs.

Rate limits

Configured via env vars; current live values readable at /admin/settings. Limits apply per-key for authenticated calls, 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

| Code | Meaning | | ----- | ---------------------------------------------------------------------- | | 200 | OK | | 201 | Created | | 204 | No content (e.g. after delete) | | 400 | Bad request (malformed body) | | 401 | Invalid / inactive key | | 403 | Key valid but wrong tier | | 404 | Target not found | | 409 | Conflict (duplicate signup fingerprint, proposal not in pending state) | | 422 | Validation error (Pydantic schema mismatch) | | 429 | Rate limit | | 500 | Server error (shows traceback only when DEBUG=true) | | 502 | Brain unreachable from BFF |