Retrieve & store via the API

The platform exposes a small REST API so a Python script can pull models and experiments out of the Knowledge Graph, fetch your own saved and shared work, and push new experiments back, without clicking through the UI.

• Curated (public) models and experiments need no account.
• Your private and shared records need an API key tied to your account.

All you need is requests (or any HTTP client) plus the tvbo package to run what you fetch.

pip install tvbo requests

Get an API key

Create one once, from Your Account → API keys: name a key at /my/api-keys and copy it when shown (it is displayed only once). Pass it as a bearer token. Keep it out of your code by reading it from an environment variable:

import os, requests

BASE = "http://tvbo.charite.de"
HEADERS = {"Authorization": f"Bearer {os.environ['TVBO_API_KEY']}"}

List what you can access

GET /api/tvbo/v1/experiments returns the experiments visible to you: the public curated ones, anything shared with the community, and your own private records (other users' private records are never listed).

r = requests.get(f"{BASE}/api/tvbo/v1/experiments", headers=HEADERS)
for exp in r.json()["data"]:
    print(exp["id"], exp["label"])

Models work the same way at GET /api/tvbo/v1/models.

Fetch one and run it

Fetch a single experiment by id as YAML and run it, loading the string straight into a SimulationExperiment with no temp file:

exp_id = 123  # from the list above
yaml_text = requests.get(
    f"{BASE}/api/tvbo/v1/experiments/{exp_id}?format=yaml", headers=HEADERS
).text

from tvbo import SimulationExperiment
result = SimulationExperiment.from_string(yaml_text).run()
result.plot()

Add ?format=json instead of yaml to get a parsed JSON body. A record private to another user returns 404: it is invisible to you, not merely forbidden.

Store an experiment from Python

POST /api/tvbo/v1/experiments saves an assembled experiment to your account, so collaborators can reproduce your run by id instead of you mailing a YAML file. Use ?visibility=private (default) or ?visibility=shared:

yaml_text = open("experiment.yaml").read()
r = requests.post(
    f"{BASE}/api/tvbo/v1/experiments?visibility=private",
    headers={**HEADERS, "Content-Type": "application/x-yaml"},
    data=yaml_text.encode("utf-8"),
)
print(r.json())   # {'success': True, 'id': 124, 'visibility': 'private'}

Pushing again with the same name replaces your existing record in place rather than creating a duplicate. The saved experiment then appears under My Models and, if shared, in the community gallery. Models push the same way at POST /api/tvbo/v1/models.

Endpoints at a glance

Curated, public models also ship with the tvbo package itself (see The tvbo Python package), so you only need the API for your own saved and shared work.