Private APIs
The private Workbench API is app.main:app on port 8001. The SPA (:5270) and Campaign Management call this surface with a Workbench session JWT. It is the source of truth for operators. The public gateway proxies a curated subset into /public/v1.
http://localhost:8001/api/v1/…
Authorization: Bearer <workbench-jwt>Local health (no JWT): GET http://localhost:8001/health. Root: GET http://localhost:8001/ returns API name and version.
Bind the private API to the cluster network. External notebooks and vendors should use :8004 with a public credential. MCP HTTP still uses :8001/mcp but requires the same dual auth as the gateway.
How the SPA authenticates
- User signs in (Workbench login).
- JWT is stored as the session (
ecosystem_auth). - Frontend calls
/api/v1/…(Vite proxies to:8001in localfrontend/run.sh). JWTAuthMiddlewarerejects missing/invalid tokens on protected routes.
There is no in-code Mongo URI. Set MONGODB_URI. Python 3.14.
Prefixes
| Prefix | App | Role |
|---|---|---|
/api/v1 | Private FastAPI | Almost all operator routes |
/api/graphtheory | Private FastAPI | Networks jobs (same paths as ecosystem-server networks) |
/api (pipeline) | Private FastAPI | Pipeline worker without the v1 prefix |
/v1 and /models | Private FastAPI | OpenAI-compatible LLM (/v1/messages, /v1/models) |
/mcp | Mounted MCP app | Streamable HTTP MCP (not under /api/v1) |
/health | Private FastAPI | Liveness |
Shared analytics dashboards can be viewed without a JWT on the dedicated share router. Everything else that mutates configuration requires a signed-in user (and often admin).
Router map (/api/v1)
Grouped the way app.main mounts them. Paths are relative to /api/v1 unless noted.
Identity and admin
| Area | Typical prefix | Purpose |
|---|---|---|
| Auth | /auth | Login, session |
| Users / roles / profiles | /users, /roles, /profiles | RBAC |
| Admin utilities | /admin | Server utilities |
| Private API keys | /admin/api-keys | Generate ecosystem JWTs |
| Public credentials | /admin/public-api-credentials | Issue ewb_public_… keys |
| About | /about | Version, build, companion assets |
Configuration entities
Generic CRUD lives at /entities/{collection} (same collections the public gateway exposes). First-class routers also exist for offer matrix, contacts, campaigns, ontology, plugins, and project export.
| Area | Typical prefix | Purpose |
|---|---|---|
| Generic entities | /entities | Projects, dynamic engagement, simulation, … |
| Projects | /projects | Project metadata |
| Data connections | /data-connections | Mongo / warehouse connections |
| Data forms | /data-forms | Forms |
| Templates | /templates | Templates |
| Plugins | /plugins | Pre/post-score Java samples |
| Offer matrix | /offer-matrix | Versioned catalog + history |
| Contacts | /contacts | Contact Sets, records, import |
| Ontology | /ontology | Documents, mappings, flags |
| Project export | /project-export | Import/export |
Deployments, scoring, runtime console
| Area | Typical prefix | Purpose |
|---|---|---|
| Deployments | /deployments | Push configuration toward Runtime |
| Predictions | /predictions | Prediction jobs |
| Batch scoring | /batch-scoring | Backend batch jobs |
| Jobs | /jobs | Async job store |
| Frames | /frames | Feature frames |
| Runtime console | /runtime-console | Campaign test / invocation debug |
| API tester | /api-tester | Operator HTTP tester (Workbench API Management) |
| Dynamic interactions | /dynamic (interactions router) | Dynamic Engagement config |
Workbench API Management (/docs/configuration/api) stores named Runtime test calls. Those hit Runtime /invocations and /response — they are not public-gateway routes.
Enrichment, files, search
| Area | Typical prefix | Purpose |
|---|---|---|
| Enrichment | /enrichment | Date, MCC, personality drift jobs |
| Prompt enrichment | /prompt-enrichment | LLM document enrichment |
| Filesystem | /filesystem | Browse worker files |
| Search | /search | Global search |
| Search-replace | /search-replace | Document replace |
| Document locks | /document-locks | Concurrent edit locks |
| Notebooks | /notebooks | Notebook module |
| Geocoding | /geocoding | Geocode helpers |
Algorithms and simulations
| Area | Typical prefix | Purpose |
|---|---|---|
| Algorithm configs | /algorithm-config | Saved algorithm documents |
| Spend Personality | /spend-personality, /algorithms/spend-personality | Wizard, runs, notebooks |
| Money Personality | /algorithms/money-personality | POST …/process |
| Sentimental equilibrium | /algorithms/sentimental-equilibrium | POST …/process |
| Two-Tower | /algorithms/two-tower | Train, export, generate Python |
| Simulations | /simulations | Save/run/validate connections (Simulations) |
| Network Selector | /network-selector | Diagnostics for the selector (not /networks/ SPA) |
MCP call_endpoint remaps /money-personality/process → /algorithms/money-personality/process (same for sentimental equilibrium).
Campaigns, agents, analytics, graphs
| Area | Typical prefix | Purpose |
|---|---|---|
| Campaigns | /campaigns | Campaign management, trigger, schedules |
| Agents | /agents | Agent configs + POST /agents/entity/explain |
| Ecosystem Agent | /claude-agent | Operator chat, status, profiles |
| EcoGentic | /ecogentic | Customer journeys (not operator chat) |
| Analytics | /analytics | Dashboards / charts |
| Shared analytics | share router | Unauthenticated dashboard view |
| MCP info | /mcp/ | Tool list (JWT). Protocol traffic is POST /mcp |
| Langflow | /langflow | Component generation |
| MLRun | /mlrun-runtime | MLRun module |
| Kubernetes | /k8s | Optional k8s deploy helpers |
| Graph theory | /api/graphtheory/* (no v1) | Networks build/analyze (Networks) |
Spend Personality processing also mounts data, scores, schedule, runs, health, preflight, processing-config, and analytics routers used by the wizard.
LLM
| Path | Purpose |
|---|---|
POST /v1/messages | Anthropic-compatible proxy → Workbench default LLM |
GET /v1/models, GET /models, GET /api/v1/models | Model catalog |
/api/v1/llm | LLM config and prompt library |
External Claude Code must set ANTHROPIC_BASE_URL to the Workbench host root (port 8001), not Anthropic SaaS. Leave ANTHROPIC_API_KEY empty. See Agents.
What stays private on purpose
These never appear as public-gateway entity collections:
public_api_credentialspublic_api_audit_events
Admin credential minting, user/role CRUD, filesystem browsing, and most enrichment internals stay on :8001. If an integration needs a private-only route, use MCP call_endpoint from a trusted operator session — do not punch a hole in the gateway without a scope.
Data Agents and Runtime
| Product | API | Not this private API |
|---|---|---|
| Data Agents | Data Agents service :54324 (POST /process) | Separate repo; same JWT cookie family |
| Runtime | :8091 /invocations, /response | Java scoring engine |
Related: Public APIs, API Keys.