Taxonomy API (Kaleido.Taxonomy.Api)
The Taxonomy API is the platform's front door and the home of Kaleido Taxonomy. It runs as one ASP.NET Core process on port 8080 and hosts five things at once:
- The REST API for games, the taxonomy, documents, AI tagging, review, similarity and the dashboard.
- The MCP server at
/mcpfor external AI clients. - The GRE gateway at
/gre/{service}/.... - The pipeline hub at
/hubs/pipeline(SignalR) for the live Simulation view. - The tagging processor, a background worker that runs bulk AI tagging.
Responsibilities
| Area | What it does | Key code |
|---|---|---|
| Catalogue | CRUD, search with facets and tag filters, CSV import, platform JSON import | Endpoints/GameEndpoints.cs, Infrastructure/GameImporter.cs, PlatformGameImporter.cs |
| Taxonomy | Tree of categories and characteristics; create, rename, move, merge, delete; snapshot export and import | Endpoints/TaxonomyEndpoints.cs, Infrastructure/TaxonomyService.cs |
| Documents | Search and download game pages, manual HTML import, raw storage | Endpoints/DocumentEndpoints.cs, Infrastructure/Documents/* |
| AI tagging | Prompt composition, single-game extract, paste-back parse, bulk runs, conflicts | DocumentEndpoints.cs, TaggingEndpoints.cs, TaggingProcessor.cs |
| Review | Accept or reject AI-suggested tags, accept all above a confidence | TaggingEndpoints.cs, TagReviewer.cs |
| Similarity | Similar games, compare, tuning with preview, 2D map, heatmap, export for GRE | Endpoints/SimilarityEndpoints.cs, Infrastructure/Similarity/* |
| Admin | Users, AI providers, versioned tagging prompt | AuthEndpoints.cs, AiProviderEndpoints.cs, AgentPromptEndpoints.cs |
| GRE gateway | Role-checked proxy to the five GRE services | Endpoints/GreEndpoints.cs |
| Live view | One sampler, many SignalR viewers | Pipeline/PipelineSampler.cs, PipelineHub.cs |
| MCP | 16 tools and 1 prompt for AI clients | Mcp/* |
REST API
Auth column: any = any signed-in user, editor = editor or admin, admin = admin only.
Auth and users
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /auth/login | anonymous | Returns { token, expires, username, role } |
| GET | /auth/me | any | Current user and role |
| GET, POST | /users | admin | List or create users (password 10+ characters) |
| DELETE | /users/{id} | admin | Delete a user (not yourself) |
Games
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /games | any | Search: q, studio[], type[], status, node[] with match=all|any, sort=name|newest|rtp|studio|tags, paging |
| GET | /games/facets | any | Studios, types and statuses with counts |
| GET | /games/{id} | any | Game with characteristics, their paths, confidence and origin |
| GET | /games/{id}/snapshot | any | Game plus its taxonomy subtree in the internal model's shape (?full=true for the whole tree) |
| POST, PUT, DELETE | /games, /games/{id} | editor | Create, update, delete; ExternalRef must be unique |
| PUT | /games/{id}/characteristics | editor | Replace the tag set. New tags are Manual; kept AI tags become accepted |
| POST | /games/import | editor | CSV import (5 MB limit) |
| POST | /games/import/platform | editor | Platform JSON export import |
Taxonomy
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /taxonomy/tree | any | Flat node list with game counts and the taxonomy version |
| GET | /taxonomy/snapshot | any | { Version, Tree } in the internal model's PascalCase shape |
| POST | /taxonomy/import | editor | Adds missing nodes from a snapshot; never deletes |
| POST, PUT, DELETE | /taxonomy/nodes, /taxonomy/nodes/{id} | editor | Create, update, delete nodes |
| POST | /taxonomy/nodes/{id}/merge | editor | Move games to the target, keep the old name as a synonym |
Documents, AI and review
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /slotcatalog/search?q= | editor | Search slotcatalog.com |
| POST | /games/{id}/documents/fetch | editor | Download a page and store the raw HTML |
| POST | /games/{id}/documents?url= | editor | Store HTML posted by the user (when a site blocks automated downloads) |
| GET | /games/{id}/documents, /documents/{docId}/html | any | List pages; read one as plain text |
| DELETE | /documents/{docId} | editor | Delete a stored page |
| GET | /games/{id}/ai/prompt | editor | The full prompt (template, taxonomy, page text) to copy into any AI tool |
| POST | /games/{id}/ai/extract | editor | Run the prompt on a provider; returns proposals and conflicts, saves nothing |
| POST | /games/{id}/ai/parse | editor | Validate an answer pasted from another AI tool |
| POST | /games/{id}/ai/apply | editor | Save reviewed proposals as Inferred tags |
| GET | /games/{id}/conflicts, /conflicts | any, editor | Source disagreements for a game, or all open ones by severity |
| POST | /conflicts/{id}/resolve | editor | Pick a candidate (becomes a confirmed tag) or dismiss |
| GET | /tagging/summary | editor | Counts for the tagging page |
| POST, GET | /tagging/runs | editor | Start a bulk run; list recent runs with progress |
| GET | /tagging/runs/{id}/items | editor | Items of a run |
| POST | /tagging/runs/{id}/cancel, /retry-failed | editor | Cancel; requeue failed items |
| GET | /review/tags | editor | Games with pending AI tags, with evidence and sources |
| POST | /review/tags/accept, /reject, /accept-all | editor | Review decisions |
| GET, POST, PUT, DELETE | /ai/providers[...] | any (read), admin | Providers; POST /ai/providers/{id}/test makes a tiny real call |
| GET, POST | /ai/prompts/{key} | editor | Versioned tagging prompt; POST /{version}/activate rolls back or forward |
Similarity and dashboard
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /games/{id}/similar?limit&sameType | any | Top games by tag similarity, with shared tags |
| GET | /games/{id}/compare/{otherId} | any | Score breakdown: shared tags with share and rarity, tags unique to each |
| GET, PUT | /similarity/settings | any, editor | Tuning; PUT bumps the revision and re-ranks for everyone |
| POST | /similarity/settings/preview | editor | Current vs proposed list for one game with unsaved settings |
| GET | /similarity/map?method=pca|umap|graph | any | 2D layout of every tagged game with axes and links |
| GET | /similarity/heatmap | any | Games by tags in clustered order |
| GET | /similarity/export?after&size&k | any | Catalogue with top-k neighbours by GameRef, for GRE |
| GET | /dashboard/overview, /dashboard/stats | any | Coverage, RTP bands, release years, tag origins, untagged games |
Internals worth knowing
- Taxonomy rules live in
TaxonomyService: only characteristics can be tagged, a single-value category accepts one child per game, a node's type never changes, and every change bumpstaxonomy_state.Version. Import adds and never deletes, up to 5,000 nodes. - Tag origins:
Manual(a person),Source(an importer),Inferred(AI, waiting for review). Every AI path, whether in-app, pasted or MCP, saves throughTagProposer, so all of them obey the same rules. See AI tagging. - Similarity vectors are cached in memory and persisted in pgvector, keyed by a fingerprint of tags, nodes, taxonomy version and settings revision. See Tag similarity.
- Platform import maps the casino platform's export onto
Game:contentKey(elseid) becomesExternalRef,gameStudio(elseprovider) the studio,primaryTypethe game type, and the square thumbnail the thumbnail. Games are matched byExternalRef, then by name for games that have none yet, so re-importing updates instead of duplicating. The platform is the authority for those fields; characteristics are never touched.
Sequence: manual tagging
Configuration
| Key | Purpose |
|---|---|
ConnectionStrings:Default | Postgres (needs pgvector) |
Auth:JwtKey | 32+ characters, required; also derives the key that encrypts AI provider keys |
Auth:AdminPassword, Auth:AdminUser | First admin at start-up |
Documents:Directory | Where raw HTML is stored (a named volume in containers) |
Ai:PromptPath | Optional prompt template file; defaults to Prompts/taxonomy-extraction.md |
Network:AllowPrivateHosts | Development only: lets outbound calls reach localhost or private hosts |
Gre:ApiKey, Gre:{Service}Url | Service key and base URLs for the gateway and sampler |