Python API Examples

This guide shows how to use the REST API from Python with the requests library.

Setup

import os
import requests
import pandas as pd
from dotenv import load_dotenv

load_dotenv()                       # reads .env in the project root
API_KEY = os.environ["URN_API_KEY"]
BASE_URL = "http://localhost:5000"   # change for production / Render

Get Study Configuration

Retrieve the study’s treatments, factors, urn parameters, and seed.

response = requests.get(f"{BASE_URL}/study_config", params={
    "api_key": API_KEY,
    "study": "My Study",
})
config = response.json()

# Inspect treatments and factors
print(config["results"]["treatments"])   # e.g. ['Treatment A', 'Treatment B']
print(config["results"]["D"])            # e.g. 'chisquare'

# Build a quick factor-level table
pd.DataFrame({
    k: pd.Series(v)
    for k, v in config["results"]["factors"].items()
}).fillna("")

Example response:

{
  "message": "Success",
  "results": {
    "treatments": ["Treatment A", "Treatment B"],
    "factors": {
      "age_group": ["18-40", "41-65", "65+"],
      "sex": ["Male", "Female"]
    },
    "D": "chisquare",
    "alpha": 0,
    "beta": 1,
    "w": 1,
    "starting_seed": 100,
    "urn_selection": "method1"
  },
  "status": 200
}

List Participants

Fetch all randomized participants and load them into a DataFrame.

response = requests.get(f"{BASE_URL}/study_participants", params={
    "api_key": API_KEY,
    "study": "My Study",
})
data = response.json()

df = pd.DataFrame(data["results"])
print(f"{len(df)} participants randomized")
df.head()

The response includes one row per participant with columns for the assigned treatment (trt), factor levels (f_-prefixed), timestamp (datetime), and the user who performed the randomization (user).

Randomize a Participant

Send a POST request with the participant ID and all factor levels.

# Use the factor levels from the config response
factors = config["results"]["factors"]

params = {
    "api_key": API_KEY,
    "study": "My Study",
    "id": "P042",
}
# Add one level per factor
params["age_group"] = "18-40"
params["sex"] = "Female"

response = requests.post(f"{BASE_URL}/study_participants", params=params)
result = response.json()

assigned_treatment = result["results"][0]["trt"]
print(f"Participant P042 assigned to: {assigned_treatment}")

Example response:

{
  "message": "Success",
  "results": [{
    "id": "P042",
    "f_age_group": "18-40",
    "f_sex": "Female",
    "trt": "Treatment A",
    "datetime": "2025-09-15 14:30:00",
    "user": "alice"
  }],
  "status": 200
}

Batch Randomization

Randomize several participants in a loop, collecting results into a DataFrame.

import random

records = []
for i in range(10):
    params = {
        "api_key": API_KEY,
        "study": "My Study",
        "id": f"BATCH-{i:03d}",
    }
    # Pick a random level for each factor
    for factor, levels in factors.items():
        params[factor] = random.choice(levels)

    resp = requests.post(f"{BASE_URL}/study_participants", params=params)
    records.append(resp.json()["results"][0])

df_batch = pd.DataFrame(records)
print(df_batch[["id", "trt"]].to_string(index=False))

Error Handling

All endpoints return a status field in the JSON body. Check it to handle errors gracefully.

response = requests.get(f"{BASE_URL}/study_participants", params={
    "study": "My Study",
    # no api_key — this will fail
})
data = response.json()

if data["status"] != 200:
    print(f"Error {data['status']}: {data['message']}")

Common error codes:

Status	Meaning	Fix
400	Missing study name or invalid factor values	Check required parameters
401	Missing or invalid API key	Verify URN_API_KEY
404	Study not found in configuration	Check study name spelling