Skip to Content

API Reference

Every endpoint below shows a copy-pasteable request body and a sample response. Endpoints are grouped by component.

Workbench2 — two-tower algorithm

Base prefix: /api/v1.

MethodPathSync/Async
GET/algorithms/two-tower/healthsync
GET/algorithms/two-tower/predictorssync
GET/algorithms/two-tower/predictor-date-boundssync
GET/algorithms/two-tower/configssync
POST/algorithms/two-tower/configssync
POST/algorithms/two-tower/configs/{config_id}/prediction-linksync
GET/algorithms/two-tower/configs/{config_id}/jobssync
POST/algorithms/two-tower/trainasync job
POST/algorithms/two-tower/batch-scoreasync job
POST/algorithms/two-tower/export-embeddingsasync job
POST/algorithms/two-tower/preview-schemaasync job
POST/algorithms/two-tower/prepare-feature-frameasync job
POST/algorithms/two-tower/generate-notebooksync (writes .ipynb; UI/private)
POST/algorithms/two-tower/generate-pythonsync (returns script + explanation)
GET/algorithms/two-tower/runssync

Saved configuration

Request (POST /algorithms/two-tower/configs):

{ "config_id": "customer_offer_retrieval_v1", "name": "Customer Offer Retrieval v1", "engine": "pytorch_notebooks", "source": { "database": "logging", "collection": "ecosystemruntime_flatten", "predictor": "my_predictor", "from_date": "2026-01-01", "to_date": "2026-06-01" }, "features": { "target_column": "accepted", "user_features": ["customer_id", "price", "rank", "score"], "item_features": ["offer", "price", "rank", "score"], "categorical_columns": ["customer_id", "offer"] }, "keys": { "customer_key_field": "customer_id", "offer_key_field": "offer" }, "training": { "embedding_dim": 32, "epochs": 25, "stopping_rounds": 3, "batch_size": 256, "learning_rate": 0.001, "hidden": [128, 64] }, "embedding_export": { "database": "ecosystem_meta", "user_collection": "two_tower_user_embeddings", "item_collection": "two_tower_item_embeddings", "metric": "cosine", "normalized": true } }

Saved configurations are listed in the /two-tower table. Jobs should include context.config_id so the page can show all jobs for the selected config.

The deployable Workbench asset is still a prediction entity. Link or create it from the saved config:

{ "config_id": "customer_offer_retrieval_v1", "predict_id": "customer_offer_retrieval_v1", "create_if_missing": true }

The linked prediction stores compact two_tower metadata while detailed run history remains in two_tower_runs and async jobs.

Train

Request:

{ "config_id": "customer_offer_retrieval_v1", "engine": "h2o", "database": "logging", "flatten_collection": "ecosystemruntime_flatten", "predictor": "my_predictor", "from_date": "2026-01-01", "to_date": "2026-06-01", "embedding_dim": 32, "epochs": 5, "stopping_rounds": 3, "run_id": "tt_abc123" }

Response (job accepted) and final job result:

{ "job_id": "job_789" }
{ "run_id": "tt_abc123", "user_model_id": "two_tower_user_tt_abc123", "item_model_id": "two_tower_item_tt_abc123", "user_auc": 0.72, "item_auc": 0.68, "n_rows": 150000 }

Batch score

Request:

{ "run_id": "tt_abc123", "top_k": 10, "max_users": 5000, "scores_collection": "two_tower_scores" }

Response (per-customer document written to MongoDB):

{ "run_id": "tt_abc123", "customer_id": "user_1", "ranked": [ { "offer": "ProductB", "score": 0.87 }, { "offer": "ProductC", "score": 0.41 } ], "created_at": "2026-06-30T00:00:00Z" }

Export embeddings

Request:

{ "run_id": "tt_abc123", "config_id": "customer_offer_retrieval_v1", "embedding_database": "ecosystem_meta", "user_embedding_collection": "two_tower_user_embeddings", "item_embedding_collection": "two_tower_item_embeddings", "customer_key_field": "customer_id", "offer_key_field": "offer", "max_users": 100000, "max_items": 100000 }

Accepted response:

{ "job_id": "job_export_123", "message": "Embedding export started" }

Final job result:

{ "run_id": "tt_abc123", "config_id": "customer_offer_retrieval_v1", "embedding_database": "ecosystem_meta", "user_embedding_collection": "two_tower_user_embeddings", "item_embedding_collection": "two_tower_item_embeddings", "user_embedding_count": 240000, "item_embedding_count": 5800, "embeddings_exported_at": "2026-06-30T00:00:00Z" }

Concept test

Request:

{ "run_id": "tt_abc123", "customer_id": "user_1", "offers": ["ProductA", "ProductB"] }

Response:

{ "success": true, "run_id": "tt_abc123", "customer_id": "user_1", "ranked": [ { "offer": "ProductB", "score": 0.87 }, { "offer": "ProductA", "score": 0.12 } ] }

Public gateway (/public/v1/two-tower)

One credential on the gateway: X-API-Key (link an internal API key on the public credential) or a user JWT. Generated clients typically send X-API-Key only. Scopes: two-tower:configs, two-tower:train, plus jobs:read to poll async jobs.

MethodPathScope
GET/POST/public/v1/two-tower/configstwo-tower:configs
GET/PUT/public/v1/two-tower/configs/{config_id}two-tower:configs
GET/public/v1/two-tower/predictorstwo-tower:configs
GET/public/v1/two-tower/predictor-date-boundstwo-tower:configs
GET/public/v1/two-tower/runstwo-tower:configs
POST/public/v1/two-tower/preview-schematwo-tower:configs
POST/public/v1/two-tower/prepare-feature-frametwo-tower:train
POST/public/v1/two-tower/traintwo-tower:train
POST/public/v1/two-tower/concept-testtwo-tower:train
POST/public/v1/two-tower/export-embeddingstwo-tower:train
POST/public/v1/two-tower/batch-scoretwo-tower:train
POST/public/v1/two-tower/generate-pythontwo-tower:train

POST /export-embeddings is the embedding update path (upsert by run_id + entity key). Optional mode: full (default) or missing_keys_only.

POST /generate-python returns explanation_markdown, python_source, scopes, and endpoints for the full pipeline. generate-notebook stays private/UI only.

For PyTorch engine training and optional live user embeddings, use Workbench Train / Export embeddings or the public routes above. Sidecar HTTP paths are not part of the operator contract — see PyTorch Serving.

Python runner

The scriptable flow should call the same Workbench APIs as the UI:

python backend/scripts/two_tower_pipeline.py \ --config-id customer_offer_retrieval_v1 \ --steps train,concept-test,export-embeddings \ --wait

Expected JSON output:

{ "config_id": "customer_offer_retrieval_v1", "run_id": "tt_abc123", "jobs": [ { "step": "train", "job_id": "job_train_1", "status": "Completed" }, { "step": "export-embeddings", "job_id": "job_export_1", "status": "Completed" } ], "embedding_export": { "database": "ecosystem_meta", "user_collection": "two_tower_user_embeddings", "item_collection": "two_tower_item_embeddings", "user_embedding_count": 240000, "item_embedding_count": 5800 }, "deployment_properties": { "predictor.model.type": "similarity", "predictor.twotower.run.id": "tt_abc123" } }

ecosystem-runtime — invocations

Request (POST /invocate):

{ "campaign": "two_tower_demo", "sub-campaign": "default", "channel": "web", "customer": "user_1", "numberoffers": 3, "userid": "ecosystem", "in_params": { "input": ["customer_id"], "value": ["user_1"] } }

Response (trimmed):

{ "final_result": [ { "rank": 1, "result": { "offer": "ProductB", "offer_name": "ProductB", "score": 0.87 } }, { "rank": 2, "result": { "offer": "ProductC", "offer_name": "ProductC", "score": 0.41 } } ], "explore": 0, "uuid": "..." }
Last updated on