Skip to Content

Public APIs

The public gateway is a separate FastAPI app (app.public_api.main:app) on port 8004. It validates either a Workbench JWT or a public key. With a key alone, private calls use the linked internal API key on that credential (Administration → API Keys → Public API Access). When a JWT is present, it is forwarded to private Workbench :8001/api/v1. The gateway writes audit events and never uses a shared operator token for interactive user requests.

PUBLIC_API_INTERNAL_SERVICE_TOKEN is an optional server-only fallback for automated jobs, not for people.

Local OpenAPI: http://localhost:8004/docs (disable with PUBLIC_API_DOCS_ENABLED=false). Prefix default: /public/v1.

Administration → API Keys → Public API Access → Public APIs is generated from the same catalog as this page (admin_public_api_catalog). Badges follow the scopes on the selected credential.

Auth

Send one credential on protected routes: a public key (X-API-Key: ewb_public_… or Authorization: Bearer ewb_public_…) or a Workbench user JWT (Authorization: Bearer <jwt>).

With a public key only, scopes and resource bindings on that credential apply; the gateway uses the linked internal API key for private backend calls. With a JWT only, Workbench roles apply. Sending both still works.

GET http://localhost:8004/public/v1/health X-API-Key: ewb_public_…

Health and login do not require a public key. Every other /public/v1 route requires one of the credentials above.

Login (no public key required for this call):

curl -s -X POST http://localhost:8004/public/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"your-password"}'

Example with a public key only:

import os import requests BASE = "http://localhost:8004/public/v1" headers = {"X-API-Key": os.environ["EWB_PUBLIC_API_KEY"]} projects = requests.get(f"{BASE}/entities/projects", headers=headers, params={"limit": 20}) print(projects.json())

The Python SDK’s login() is optional when you call with a scoped public key that has a linked internal key.

Grantable scopes

ScopeUnlocks
entities:read / entities:writeEntity collections and campaign reads/writes
catalogs:read / catalogs:writeContact Sets. Public catalog routes listed below are GET; writes go through private contacts or MCP call_endpoint
contacts:read / contacts:writeContact Set records
frames:readReserved on credentials (not a CORE catalog group yet)
predictions:runBatch scoring, Spend Personality runtime score, /v1/models
jobs:readAsync job status, campaign runs
runtime:evidence:readReserved on credentials (not a CORE catalog group yet)
networks:jobs / networks:read / networks:analyzeGraph jobs and analysis
spend-personality:configs / spend-personality:runsSpend Personality configs, pipeline, drift
money-personality:runsMoney Personality process
sentimental-equilibrium:runsSentimental equilibrium process
two-tower:configs / two-tower:trainTwo-Tower configs, train, export, batch-score
lora:configs / lora:trainLoRA Recommender configs, train, export, batch-score
data-management:read / data-management:writeMongo Data Management (optional credential bindings database_names, collection_refs as db.collection)
simulation:read / simulation:runsSimulation status, logs, results; start and cancel runs
ontology:read / ontology:writeOntology documents and mappings

Grant the minimum set. Polling async work also needs jobs:read.


Auth & health

MethodPathScopePurpose
POST/public/v1/auth/loginnoneEmail/password → JWT
GET/public/v1/healthnoneGateway health

Contact catalogs

Contact Sets (not entity collections).

MethodPathScopePurpose
GET/public/v1/catalogscatalogs:readList Contact Sets
GET/public/v1/catalogs/{catalog_id}catalogs:readRead one Contact Set
GET/public/v1/catalogs/{catalog_id}/recordscontacts:readList records

Jobs & predictions

MethodPathScopePurpose
GET/public/v1/jobs/{job_id}jobs:readAsync job status
POST/public/v1/batch-scoring/jobspredictions:runStart backend batch-scoring
GET/public/v1/batch-scoring/jobs/{job_id}jobs:readBatch-scoring progress
POST/public/v1/predictions/runpredictions:runSpend Personality runtime scoring

POST /predictions/run scores through a Runtime deployment. Closed-loop learning still uses Runtime POST /response with that row’s uuid and offer_name.

Networks

Same contract as Networks Jobs & API. Responses never include the full analysis graph — only a display sample, stats, and metrics summary.

MethodPathScope
POST/public/v1/networks/jobsnetworks:jobs
GET/public/v1/networks/jobs/{job_id}networks:read
GET/public/v1/networks/jobs/{job_id}/eventsnetworks:read
GET/public/v1/networks/jobs/{job_id}/resultnetworks:read
DELETE/public/v1/networks/jobs/{job_id}networks:jobs
GET/public/v1/networks/graphs/{graph_id}/displaynetworks:read
GET/public/v1/networks/graphs/{graph_id}/metricsnetworks:read
POST/public/v1/networks/graphs/{graph_id}/analyzenetworks:analyze
POST/public/v1/networks/graphs/{graph_id}/temporal/{category}networks:analyze

Spend Personality

Needs spend-personality:configs, spend-personality:runs, and jobs:read (plus predictions:run for optional score proof). POST /runs is fire-and-forget — poll GET /public/v1/jobs/{job_id} until lifecycle_state is Completed. Keep polling Queued / Running / Stalled. Treat Failed / Cancelled as errors.

MethodPathScopePurpose
GET / POST/public/v1/spend-personality/configsspend-personality:configsList or upsert algorithm config
GET/public/v1/spend-personality/configs/{config_id}spend-personality:configsRead config and run_log
POST/public/v1/spend-personality/runsspend-personality:runsPhased or full pipeline
POST/public/v1/spend-personality/driftspend-personality:runsRecompute personality drift

POST /runs fields: algorithm_config_id (required), optional phases (import_check, enrich, score_unscored, prepare_model, deploy), running_config_id from the first response so later phases share leader model ids, plus project_id / week_start_day.

Money Personality

MethodPathScopePurpose
POST/public/v1/money-personality/processmoney-personality:runsStart scoring; poll jobs

Sentimental Equilibrium

MethodPathScopePurpose
POST/public/v1/sentimental-equilibrium/processsentimental-equilibrium:runsStart the Workbench contact-rate batch from prediction logs (or a field map / Mongo pipeline); poll jobs. Writes recommended_engagement_rate and rate_adjustment. Live Dynamic Engagement arm_reward for sentimentalEquilibrium is a separate offer-rank number — see Sentimental Equilibrium.

The ecosystem-server munge option sentiment is retired. Callers that still hit that path receive an error pointing at Workbench POST /api/v1/algorithms/sentimental-equilibrium/process (public gateway path above).

Two-Tower

MethodPathScopePurpose
GET / POST/public/v1/two-tower/configstwo-tower:configsList or upsert
GET / PUT/public/v1/two-tower/configs/{config_id}two-tower:configsRead / update
GET/public/v1/two-tower/predictorstwo-tower:configsDistinct predictors in flatten
GET/public/v1/two-tower/predictor-date-boundstwo-tower:configsDate range and row count
GET/public/v1/two-tower/runstwo-tower:configsRecent training runs
POST/public/v1/two-tower/preview-schematwo-tower:configsPreview flatten schema (async)
POST/public/v1/two-tower/prepare-feature-frametwo-tower:trainH2O frame without training
POST/public/v1/two-tower/traintwo-tower:trainStart training
POST/public/v1/two-tower/concept-testtwo-tower:trainSync concept rank for one customer
POST/public/v1/two-tower/export-embeddingstwo-tower:trainExport user/item embeddings
POST/public/v1/two-tower/batch-scoretwo-tower:trainTop-K offers to a collection
POST/public/v1/two-tower/generate-pythontwo-tower:trainRunnable Python + explanation

LoRA Recommender

Same shape as Two-Tower on the public gateway. Operator UI: LoRA Recommender.

MethodPathScopePurpose
GET / POST/public/v1/lora/configslora:configsList or upsert
GET / PUT/public/v1/lora/configs/{config_id}lora:configsRead / update
GET/public/v1/lora/predictorslora:configsDistinct predictors in flatten
GET/public/v1/lora/predictor-date-boundslora:configsDate range and row count
GET/public/v1/lora/runslora:configsRecent training runs
POST/public/v1/lora/trainlora:trainStart training
POST/public/v1/lora/concept-testlora:trainSync concept rank for one customer
POST/public/v1/lora/export-embeddingslora:trainExport user/item embeddings
POST/public/v1/lora/batch-scorelora:trainTop-K offers to a collection
POST/public/v1/lora/generate-pythonlora:trainRunnable Python + explanation

Simulations

Workbench in-process simulation engine. UI and field semantics: Simulations.

MethodPathScopePurpose
GET/public/v1/simulations/statussimulation:readMongo / engine health
POST/public/v1/simulations/validate-connectionssimulation:readDatabase and pulse-responder checks
POST/public/v1/simulations/from-deploymentsimulation:runsMaterialize simulation from a deployment
POST/public/v1/simulations/runsimulation:runsStart a run
POST/public/v1/simulations/cancelsimulation:runsCooperative cancel
GET / DELETE/public/v1/simulations/logssimulation:read / simulation:runsRead or clear run logs
GET/public/v1/simulations/results/parameterssimulation:readOptions-store parameter snapshots
GET/public/v1/simulations/results/plotsimulation:readPlot series
GET/public/v1/simulations/results/optionssimulation:readOptions-store snapshots

Data Management

Scoped Mongo inspection and document CRUD (not entity collections). Optional credential bindings: database_names, collection_refs (db.collection).

The gateway rejects admin, local, and config, any system.* collection, and the public credential / audit collections. Drop, rename, deleteMany, aggregate, and export stay on the private API only.

MethodPathScopePurpose
GET / POST/public/v1/data-management/databasesread / writeList or create databases
GET / POST/public/v1/data-management/databases/{database}/collectionsread / writeList or create collections
GET/public/v1/data-management/databases/{database}/collections/{collection}/fieldsdata-management:readField sample / schema
GET/public/v1/data-management/databases/{database}/collections/{collection}/indexesdata-management:readIndex list
POST/public/v1/data-management/databases/{database}/collections/{collection}/documents/querydata-management:readQuery documents
POST/public/v1/data-management/databases/{database}/collections/{collection}/documentsdata-management:writeInsert documents
POST/public/v1/data-management/databases/{database}/collections/{collection}/documents/updatedata-management:writeUpdate documents (POST, not PUT)
—(single-document delete — path in live catalog)data-management:writeDelete one document
POST/public/v1/data-management/databases/{database}/collections/{collection}/importdata-management:writeImport documents

Ontology

Updates use POST, not PUT/PATCH. Same contract as private /api/v1/ontology/*.

MethodPathScope
GET/public/v1/ontologyontology:read
GET / POST / DELETE/public/v1/ontology/{ontology_id}read / write / write
POST/public/v1/ontology/from-data-sourceontology:write
GET / POST/public/v1/ontology/{ontology_id}/mappingsread / write
POST/public/v1/ontology/{ontology_id}/mappings/suggest-multiontology:write
POST/public/v1/ontology/{ontology_id}/mappings/{mapping_id}ontology:write
POST/public/v1/ontology/{ontology_id}/resolve-termontology:read
POST/public/v1/ontology/{ontology_id}/resolve-questionontology:read

Campaigns

Campaign delivery channels (email, WhatsApp, SMS, …) are not Runtime scoring channel (app / web / api).

MethodPathScopePurpose
GET/public/v1/campaignsentities:readList campaigns
GET/public/v1/campaigns/channel-catalogentities:readPlatform delivery channel catalog
GET/public/v1/campaigns/{campaign_id}entities:readRead one
GET/public/v1/campaigns/{campaign_id}/channelsentities:readOptions, selection, send_track
PUT/public/v1/campaigns/{campaign_id}/channel-selectionentities:writeSet option ids
POST/public/v1/campaigns/{campaign_id}/triggerentities:writeTrigger a run
POST/public/v1/campaigns/{campaign_id}/apply-paramsentities:writeParameter overrides
GET / PUT/public/v1/campaigns/{campaign_id}/schedulesread / writeEmbedded schedules
POST/public/v1/campaigns/{campaign_id}/schedules/syncentities:writeSave and arm crons
POST/public/v1/campaigns/{campaign_id}/schedules/generateentities:readNatural-language draft (no write)
POST/public/v1/campaigns/{campaign_id}/scheduleentities:writeRegister one cron
DELETE/public/v1/campaigns/{campaign_id}/schedules/{schedule_id}entities:writeUnregister one
DELETE/public/v1/campaigns/{campaign_id}/scheduleentities:writeUnregister one (schedule_id) or all
GET/public/v1/campaigns/{campaign_id}/runsjobs:readList runs
GET/public/v1/campaigns/runs/{run_id}jobs:readRead run
GET/public/v1/campaigns/runs/{run_id}/progressjobs:readProgress
POST/public/v1/campaigns/runs/{run_id}/stopentities:writeStop run

Analytics dashboards

Workbench analytics dashboards (not Data Agents report jobs).

MethodPathScopePurpose
GET/public/v1/analytics/dashboardsentities:readList
GET/public/v1/analytics/dashboards/{dashboard_id}entities:readRead
GET / POST/public/v1/analytics/dashboards/{dashboard_id}/shareread / writeShare metadata

Account & models

MethodPathScopePurpose
GET/public/v1/me/apisnone (key identifies credential)Endpoints this credential can reach
GET/v1/models (also /models)predictions:runOpenAI-compatible model list

Entity collections

CRUD at /public/v1/entities/{collection}. List names: GET /public/v1/entities/collections.

ActionMethodPathScope
ListGET/public/v1/entities/{collection}entities:read
ReadGET/public/v1/entities/{collection}/{entity_id}entities:read
CreatePOST/public/v1/entities/{collection}entities:write
UpdatePUT/public/v1/entities/{collection}/{entity_id}entities:write
DeleteDELETE/public/v1/entities/{collection}/{entity_id}entities:write

List query params: skip, limit, q, fields.

Public collections include: projects, agent configs / nodes / channels, custom channel modules, calendar, fact injection (chat_config), dashboards, data wizards, dynamic engagement, enrichment configs and pipelines, frames, predictions, data connections, offer matrix (+ history), prompt library, responder analytics and API config, simulation, networks, campaigns.

Settings (operators)

SettingDefaultRole
PUBLIC_API_PREFIX/public/v1Path prefix
PUBLIC_API_CORS_ORIGINS—CORS
PUBLIC_API_SECRET_PEPPER—Hash secrets and IPs
PUBLIC_API_INTERNAL_BASE_URLhttp://localhost:8001/api/v1Private proxy target
PUBLIC_API_INTERNAL_SERVICE_TOKEN—Job fallback only
PUBLIC_API_AUDIT_TTL_DAYS0 = keepAudit TTL
PUBLIC_API_DOCS_ENABLED— (see Workbench public-api-gateway runbook)Enable OpenAPI at /docs on :8004
PUBLIC_API_DEFAULT_RATE_LIMIT_PER_MINUTE— (see runbook)Default per-credential rate limit
PUBLIC_API_EXTERNAL_BASE_URL—Public base URL for open-tracking and unsubscribe links (must be reachable from mail clients)

Related: Private APIs, API Keys, MCP.

Last updated on