API Reference

BotManifoldClient

from botmanifold import BotManifoldClient

client = BotManifoldClient(
    api_key=None,           # or set BOTMANIFOLD_API_KEY
    base_url=None,          # defaults to https://api.botmanifold.com; or BOTMANIFOLD_API_URL
    timeout=30,             # request timeout in seconds
    training_api_key=None,  # or BOTMANIFOLD_TRAINING_API_KEY, for training reporting calls
)

The client exposes verify, training and pipeline, and a generic client.get(path) for any endpoint.

AsyncBotManifoldClient has the same shape; use it as an async context manager (needs the async extra):

async with AsyncBotManifoldClient() as client:
    report = await client.verify.run("policy.zip", scenario="messy_room")

client.verify

`run`

client.verify.run(
    policy="policy.zip",          # path or file object; or use policy_url
    scenario="messy_room",
    policy_url=None,              # a policy server you host (public address)
    policy_auth_token=None,       # that server's pairing token
    num_episodes=5,
    timeout=300,
    wait=True,
)

Provide either policy or policy_url. With wait=True it polls until the job finishes (or timeout seconds pass) and returns the final VerifyReport; with wait=False it returns immediately with the job_id and a pending verdict.

`submit`, `status`, `wait`

report = client.verify.submit("policy.zip", VerifyConfig(scenario="messy_room"))
report = client.verify.status(job_id)                       # one poll
report = client.verify.wait(job_id, timeout=300, poll_interval=5)

VerifyReport

Field	Type	Meaning
`job_id`	str	Job identifier
`verdict`	`Verdict`	`SAFE`, `UNSAFE`, `ERROR` or `PENDING`
`score`	float	0 to 1
`scenario`, `episodes`	str, int	What ran
`composite_score`	float or None	0 to 100
`progress_score`, `safety_score`	float or None	0 to 10, mean over episodes
`consistency`, `success_rate`, `vlm_agreement`	float or None	0 to 1
`needs_review`	bool	Low-confidence result queued for human review
`video_url`, `report_url`	str or None	Replay video and report page
`created_at`, `completed_at`	datetime or None	Timing
`episode_details`	list of dict	Per-episode results
`details`	dict	Extra verdict details
`is_safe`, `is_complete`	property	Convenience booleans

client.training

Training runs, checkpoints and managed jobs: list_runs, get_run, list_checkpoints, get_convergence_status, submit_job, get_job, list_jobs, cancel_job, get_job_logs, set_gpu_provider, and the reporting calls report_metrics, report_gpu and register_checkpoint (these need the training API key).

Training services

The Training Monitor and the managed-training orchestrator that these calls use are not deployed on the hosted platform yet.

client.pipeline

Datasets: list_datasets(page, page_size), get_dataset_quality(dataset_id), list_episodes(...) and exclude_episodes(...).

Errors

Exception	Raised when
`BotManifoldError`	Any API or network failure (message includes the status and detail)
`AuthenticationError`	The API returns 401 or 403 (bad or missing key)

CLI

botmanifold verify POLICY --scenario ID [--num-episodes N] [--output report.json] [--timeout S]
botmanifold verify --url URL --token TOKEN --scenario ID
botmanifold serve POLICY.py [--port 8765] [--host 0.0.0.0] [--no-token]
botmanifold mock-server EPISODE.jsonl --port 8765
botmanifold datasets list | quality <id> | episodes <id>
botmanifold scenario validate ...
botmanifold train submit | status | list | logs | cancel | set-provider
botmanifold bridge serve | teleop | upload | sessions | robots | pair | resume | jog | ...

botmanifold <command> --help shows every option. -v turns on verbose logging.

Environment variables

Variable	Purpose
`BOTMANIFOLD_API_KEY`	API key
`BOTMANIFOLD_API_URL`	API base URL
`BOTMANIFOLD_TRAINING_API_KEY`	Key for training reporting calls

On this page