Interface
Knowledgebase API
The planned query surface for the movement knowledgebase: windows, embeddings, and evidence — designed for analysts, tools, and AI agents alike.
Windows, embeddings, evidence
The knowledgebase is organized around three nouns. A window is a few seconds of one body’s movement — pose sequence plus metadata. Every window carries an embedding, its coordinate in movement space. And every derived statement links back to evidence: the raw segments that justify it. The rule the API is designed around is simple — no answer without a pointer to the movement it came from.
Planned endpoints
| Endpoint | Purpose |
|---|---|
| POST /v1/embed | Turn a pose sequence into its 384-d embedding. |
| POST /v1/query | Search the knowledgebase — by similarity, filters, or features — with evidence in every hit. |
| GET /v1/features | Enumerate the derived movement features a corpus exposes. |
Example: query and response
A representative exchange — shapes and names are illustrative and will be finalized with the first integration partners.
POST /v1/query
{
"similar_to": "win_02af31",
"filter": {
"athlete_id": "ath_114",
"date_range": ["2026-03-01", "2026-03-28"]
},
"features": ["speed_profile", "knee_asymmetry"],
"limit": 2
}
HTTP/1.1 200 OK
{
"model_version": "hmt-poc-0.9",
"schema_version": "2026-06",
"results": [
{
"window_id": "win_7c11e4",
"similarity": 0.93,
"features": { "speed_profile": 7.2, "knee_asymmetry": 0.14 },
"evidence": { "session_id": "ses_209", "t_start": 3121.4, "t_end": 3125.4 }
},
{
"window_id": "win_1d98b0",
"similarity": 0.91,
"features": { "speed_profile": 6.8, "knee_asymmetry": 0.17 },
"evidence": { "session_id": "ses_214", "t_start": 812.0, "t_end": 816.0 }
}
]
}Versioning, trust, and agents
Every response names the model_version and schema_version that produced it, because embeddings from different model versions are not comparable and no consumer should discover that by accident.
On top of the same query surface, an MCP server is planned so that AI agents — Claude, ChatGPT, custom systems — can ask movement questions directly and cite the evidence they get back. How that changes what a coach, physio, or analyst can do is told on the AI-agent platform page.