Public APIs

The public gateway is a separate FastAPI app (app.public_api.main:app) on port 8004. It validates a public credential, forwards the caller’s JWT to private Workbench :8001/api/v1, and writes audit events. It 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.

Auth

GET http://localhost:8004/public/v1/health
X-API-Key: ewb_public_…
Authorization: Bearer <workbench-jwt>

• Public API key — which gateway routes are allowed
• User JWT — that user’s Workbench roles on the private backend

Login (no public key):

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

Then:

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

Health and login do not require a public key. Every other /public/v1 route does.

Grantable scopes

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

Auth & health

Contact catalogs

Contact Sets (not entity collections).

Jobs & predictions

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.

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.

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

Sentimental Equilibrium

Two-Tower

Ontology

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

Campaigns

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

Analytics dashboards

Workbench analytics dashboards (not Data Agents report jobs).

Account & models

Entity collections

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

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)

Related: Private APIs, API Keys, MCP.