Skip to main content

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:

  1. The REST API for games, the taxonomy, documents, AI tagging, review, similarity and the dashboard.
  2. The MCP server at /mcp for external AI clients.
  3. The GRE gateway at /gre/{service}/....
  4. The pipeline hub at /hubs/pipeline (SignalR) for the live Simulation view.
  5. The tagging processor, a background worker that runs bulk AI tagging.

Responsibilities​

AreaWhat it doesKey code
CatalogueCRUD, search with facets and tag filters, CSV import, platform JSON importEndpoints/GameEndpoints.cs, Infrastructure/GameImporter.cs, PlatformGameImporter.cs
TaxonomyTree of categories and characteristics; create, rename, move, merge, delete; snapshot export and importEndpoints/TaxonomyEndpoints.cs, Infrastructure/TaxonomyService.cs
DocumentsSearch and download game pages, manual HTML import, raw storageEndpoints/DocumentEndpoints.cs, Infrastructure/Documents/*
AI taggingPrompt composition, single-game extract, paste-back parse, bulk runs, conflictsDocumentEndpoints.cs, TaggingEndpoints.cs, TaggingProcessor.cs
ReviewAccept or reject AI-suggested tags, accept all above a confidenceTaggingEndpoints.cs, TagReviewer.cs
SimilaritySimilar games, compare, tuning with preview, 2D map, heatmap, export for GREEndpoints/SimilarityEndpoints.cs, Infrastructure/Similarity/*
AdminUsers, AI providers, versioned tagging promptAuthEndpoints.cs, AiProviderEndpoints.cs, AgentPromptEndpoints.cs
GRE gatewayRole-checked proxy to the five GRE servicesEndpoints/GreEndpoints.cs
Live viewOne sampler, many SignalR viewersPipeline/PipelineSampler.cs, PipelineHub.cs
MCP16 tools and 1 prompt for AI clientsMcp/*

REST API​

Auth column: any = any signed-in user, editor = editor or admin, admin = admin only.

Auth and users​

MethodPathAuthPurpose
POST/auth/loginanonymousReturns { token, expires, username, role }
GET/auth/meanyCurrent user and role
GET, POST/usersadminList or create users (password 10+ characters)
DELETE/users/{id}adminDelete a user (not yourself)

Games​

MethodPathAuthPurpose
GET/gamesanySearch: q, studio[], type[], status, node[] with match=all|any, sort=name|newest|rtp|studio|tags, paging
GET/games/facetsanyStudios, types and statuses with counts
GET/games/{id}anyGame with characteristics, their paths, confidence and origin
GET/games/{id}/snapshotanyGame plus its taxonomy subtree in the internal model's shape (?full=true for the whole tree)
POST, PUT, DELETE/games, /games/{id}editorCreate, update, delete; ExternalRef must be unique
PUT/games/{id}/characteristicseditorReplace the tag set. New tags are Manual; kept AI tags become accepted
POST/games/importeditorCSV import (5 MB limit)
POST/games/import/platformeditorPlatform JSON export import

Taxonomy​

MethodPathAuthPurpose
GET/taxonomy/treeanyFlat node list with game counts and the taxonomy version
GET/taxonomy/snapshotany{ Version, Tree } in the internal model's PascalCase shape
POST/taxonomy/importeditorAdds missing nodes from a snapshot; never deletes
POST, PUT, DELETE/taxonomy/nodes, /taxonomy/nodes/{id}editorCreate, update, delete nodes
POST/taxonomy/nodes/{id}/mergeeditorMove games to the target, keep the old name as a synonym

Documents, AI and review​

MethodPathAuthPurpose
GET/slotcatalog/search?q=editorSearch slotcatalog.com
POST/games/{id}/documents/fetcheditorDownload a page and store the raw HTML
POST/games/{id}/documents?url=editorStore HTML posted by the user (when a site blocks automated downloads)
GET/games/{id}/documents, /documents/{docId}/htmlanyList pages; read one as plain text
DELETE/documents/{docId}editorDelete a stored page
GET/games/{id}/ai/prompteditorThe full prompt (template, taxonomy, page text) to copy into any AI tool
POST/games/{id}/ai/extracteditorRun the prompt on a provider; returns proposals and conflicts, saves nothing
POST/games/{id}/ai/parseeditorValidate an answer pasted from another AI tool
POST/games/{id}/ai/applyeditorSave reviewed proposals as Inferred tags
GET/games/{id}/conflicts, /conflictsany, editorSource disagreements for a game, or all open ones by severity
POST/conflicts/{id}/resolveeditorPick a candidate (becomes a confirmed tag) or dismiss
GET/tagging/summaryeditorCounts for the tagging page
POST, GET/tagging/runseditorStart a bulk run; list recent runs with progress
GET/tagging/runs/{id}/itemseditorItems of a run
POST/tagging/runs/{id}/cancel, /retry-failededitorCancel; requeue failed items
GET/review/tagseditorGames with pending AI tags, with evidence and sources
POST/review/tags/accept, /reject, /accept-alleditorReview decisions
GET, POST, PUT, DELETE/ai/providers[...]any (read), adminProviders; POST /ai/providers/{id}/test makes a tiny real call
GET, POST/ai/prompts/{key}editorVersioned tagging prompt; POST /{version}/activate rolls back or forward

Similarity and dashboard​

MethodPathAuthPurpose
GET/games/{id}/similar?limit&sameTypeanyTop games by tag similarity, with shared tags
GET/games/{id}/compare/{otherId}anyScore breakdown: shared tags with share and rarity, tags unique to each
GET, PUT/similarity/settingsany, editorTuning; PUT bumps the revision and re-ranks for everyone
POST/similarity/settings/previeweditorCurrent vs proposed list for one game with unsaved settings
GET/similarity/map?method=pca|umap|graphany2D layout of every tagged game with axes and links
GET/similarity/heatmapanyGames by tags in clustered order
GET/similarity/export?after&size&kanyCatalogue with top-k neighbours by GameRef, for GRE
GET/dashboard/overview, /dashboard/statsanyCoverage, 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 bumps taxonomy_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 through TagProposer, 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 (else id) becomes ExternalRef, gameStudio (else provider) the studio, primaryType the game type, and the square thumbnail the thumbnail. Games are matched by ExternalRef, 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​

KeyPurpose
ConnectionStrings:DefaultPostgres (needs pgvector)
Auth:JwtKey32+ characters, required; also derives the key that encrypts AI provider keys
Auth:AdminPassword, Auth:AdminUserFirst admin at start-up
Documents:DirectoryWhere raw HTML is stored (a named volume in containers)
Ai:PromptPathOptional prompt template file; defaults to Prompts/taxonomy-extraction.md
Network:AllowPrivateHostsDevelopment only: lets outbound calls reach localhost or private hosts
Gre:ApiKey, Gre:{Service}UrlService key and base URLs for the gateway and sampler