Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hubify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Experiments API

Shipped today: GET /v1/experiments, POST /v1/experiments, plus the sub-collections /experiments/costs, /experiments/queues, /experiments/templates (GET + POST each). Per-experiment routes (GET /v1/experiments/{id}, /logs, /metrics) are planned, not yet live. Stream logs via the experiment-detail view in the web app or the Convex experiments.getLogs query.
Experiments are the core research unit in Hubify. Each experiment runs on GPU compute (or CPU), streams logs in real time, passes through QC gates, and stores results back to the lab.

​
Experiment Status Lifecycle

queued → running → pass / fail / blocked
StatusDescription
queuedWaiting for a compute pod or manual trigger
runningActively executing on a pod
passCompleted successfully and passed QC
failCompleted with errors or failed QC
blockedWaiting on a dependency or manual unblock

​
Create an Experiment

​
labId
string
required
Convex ID of the lab this experiment belongs to.
​
title
string
required
Human-readable experiment title (e.g., “MCMC Chain, Planck 2018 + BAO”).
​
projectId
string
Convex ID of the parent project, if applicable.
​
experimentId
string
Custom identifier (e.g., “EXP-054”). Auto-generated if omitted.
​
computeMode
string
default:"CPU"
Compute target: H200, H100, A100, or CPU.
​
config
object
Experiment configuration as a JSON object. Stored as a string internally.
​
template
string
Experiment template name (e.g., mcmc, anomaly-sweep, fisher-forecast).
​
priority
string
default:"normal"
Queue priority: critical, high, normal, low.
​
estimatedSeconds
number
Estimated runtime in seconds. Used for scheduling and cost projection.
curl -X POST https://www.hubify.com/api/v1/experiments \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "title": "MCMC Chain, Planck 2018 + BAO",
    "experimentId": "EXP-054",
    "computeMode": "H200",
    "config": {
      "script": "run_cobaya.py",
      "batch_size": 1,
      "env": {"COBAYA_PACKAGES": "/workspace/packages"}
    },
    "priority": "high",
    "estimatedSeconds": 7200
  }'
​
data
object

​
List Experiments

​
labId
string
required
Lab ID to list experiments for.
​
status
string
Filter by status: queued, running, pass, fail, blocked.
​
projectId
string
Filter by parent project.
​
limit
number
default:"50"
Results per page.
​
cursor
string
Pagination cursor.
curl "https://www.hubify.com/api/v1/experiments?labId=j57a8k9m2n3p4q5r&status=running" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Get an Experiment

curl https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Update an Experiment

Update metadata or status of an experiment. Use this to manually transition status (e.g., unblock a blocked experiment).
​
title
string
Updated title.
​
status
string
New status. Valid transitions depend on current status.
​
result
string
Result summary (typically set on completion).
​
priority
string
Updated priority.
curl -X PATCH https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "queued",
    "priority": "critical"
  }'

​
Delete an Experiment

Delete an experiment and its associated logs. Does not delete figures generated by the experiment. 
curl -X DELETE https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Experiment Logs

Stream or retrieve logs for a running or completed experiment.

​
List Logs

​
experimentId
string
required
Experiment Convex ID.
​
level
string
Filter by log level: info, warn, error, debug.
​
limit
number
default:"100"
Number of log entries to return.
curl "https://www.hubify.com/api/v1/experiments/EXP-054/logs?level=error&limit=50" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Subscribe to Logs (Real-Time)

// Real-time log subscription via Convex
client.onUpdate(
  api.experimentLogs.list,
  { experimentId: "j57a8k9m2n3p4q5r" },
  (logs) => {
    logs.forEach((log) => console.log(`[${log.level}] ${log.message}`));
  }
);

​
Experiment Metrics

After an experiment completes, metrics are available in the result and associated log entries. 
curl https://www.hubify.com/api/v1/experiments/EXP-054/metrics \
  -H "Authorization: Bearer $HUBIFY_TOKEN"
​
data
object