Subject management

Subjects let you group analyses by individual runner. Create a subject record, then pass the subject_id when starting an analysis to link them together. Later, retrieve all analyses for a subject in a single call.

Typical workflow

When to use subjects

Subjects are optional. They are useful when you need to:

Track analyses per runner across multiple sessions
Store basic runner metadata (name, email, height, weight) once and reuse it
List all analyses for a specific runner

If you only run one-off analyses without tracking individual runners, you can skip subject management entirely.

Create a subject

All body fields are optional. The server generates a unique subject_id. Height must be in meters and weight in kilograms (metric system).

curl -X POST "https://partner-api.ochy-prod.com/subjects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "runner@example.com",
    "name": "Jane Smith",
    "height": 1.72,
    "weight": 62
  }'

import requests

response = requests.post(
    "https://partner-api.ochy-prod.com/subjects",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "email": "runner@example.com",
        "name": "Jane Smith",
        "height": 1.72,
        "weight": 62,
    },
)

subject = response.json()
print(f"Subject created: {subject['subject_id']}")

const response = await fetch(
  "https://partner-api.ochy-prod.com/subjects",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "runner@example.com",
      name: "Jane Smith",
      height: 1.72,
      weight: 62,
    }),
  }
);

const { subject_id } = await response.json();
console.log(`Subject created: ${subject_id}`);

Response (201 Created):

{
  "subject_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-03-20T15:30:00Z"
}

Link an analysis to a subject

Pass subject_id as a form field when starting an analysis:

curl -X POST "https://partner-api.ochy-prod.com/analysis/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@runner_side.mp4" \
  -F "analysis_type=side_view" \
  -F "height=1.72" \
  -F "weight=62" \
  -F "subject_id=550e8400-e29b-41d4-a716-446655440000"

The analysis is stored with a reference to the subject. You can then retrieve all analyses for that subject using the subject analyses endpoint. When you list all analyses, each item includes the subject_id field if a subject was linked.

List all subjects

curl "https://partner-api.ochy-prod.com/subjects" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    "https://partner-api.ochy-prod.com/subjects",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

data = response.json()
for subject in data["subjects"]:
    print(f"{subject['id']} - {subject.get('name', 'No name')}")

Response:

{
  "subjects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "runner@example.com",
      "name": "Jane Smith",
      "height": 1.72,
      "weight": 62,
      "created_at": "2025-03-20T15:30:00Z"
    }
  ],
  "count": 1
}

Get a single subject

curl "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the subject object, or 404 if the subject does not exist or has been deleted.

Update a subject

Only the provided fields are updated. Omitted fields remain unchanged. Same units as creation: height in meters, weight in kilograms.

curl -X PUT "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weight": 63}'

Response:

{
  "message": "Subject updated"
}

Delete a subject

Subjects are soft-deleted — the record is kept but excluded from list results. The endpoint uses POST instead of DELETE to prevent accidental deletion.

curl -X POST "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000/delete" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "message": "Subject deleted"
}

List analyses for a subject

Retrieve all analysis IDs linked to a specific subject:

curl "https://partner-api.ochy-prod.com/analysis/subjects/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"https://partner-api.ochy-prod.com/analysis/subjects/{subject_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

data = response.json()
for analysis in data["analysis_ids"]:
    print(f"{analysis['id']} - {analysis['status']}")

const res = await fetch(
  `https://partner-api.ochy-prod.com/analysis/subjects/${subjectId}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { analysis_ids, count } = await res.json();
console.log(`Found ${count} analyses for this subject`);

Response:

{
  "analysis_ids": [
    { "id": "a1b2c3d4", "status": "success" },
    { "id": "e5f6g7h8", "status": "analyzing" }
  ],
  "count": 2
}

Subject fields reference

Field	Type	Description
`id`	string	Server-generated UUID. Read-only.
`email`	string	Subject email address. Optional.
`name`	string	Subject display name. Optional.
`height`	number	Subject height in meters (e.g. `1.72`). Optional.
`weight`	number	Subject weight in kilograms (e.g. `62`). Optional.
`created_at`	string	ISO 8601 timestamp. Read-only.

Getting started

Guides

Typical workflow

When to use subjects

Create a subject

Link an analysis to a subject

List all subjects

Get a single subject

Update a subject

Delete a subject

List analyses for a subject

Subject fields reference

​Typical workflow

​When to use subjects

​Create a subject

​Link an analysis to a subject

​List all subjects

​Get a single subject

​Update a subject

​Delete a subject

​List analyses for a subject

​Subject fields reference

Typical workflow

When to use subjects

Create a subject

Link an analysis to a subject

List all subjects

Get a single subject

Update a subject

Delete a subject

List analyses for a subject

Subject fields reference