> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ochy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subject management

> Create and manage subjects to organize analyses by individual runner.

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

```mermaid theme={null}
sequenceDiagram
    participant You
    participant API as Ochy API

    You->>API: POST /subjects (runner info)
    API-->>You: 201 { subject_id }

    You->>API: POST /analysis/start (video + subject_id)
    API-->>You: 202 { video_id }

    Note over You,API: Repeat for every session

    You->>API: GET /analysis/subjects/{subject_id}
    API-->>You: 200 { analysis_ids, count }
```

## 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).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://partner-api.ochy-prod.com/subjects?apiKey=YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "runner@example.com",
      "name": "Jane Smith",
      "height": 1.72,
      "weight": 62
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://partner-api.ochy-prod.com/subjects",
      params={"apiKey": "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']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://partner-api.ochy-prod.com/subjects?apiKey=YOUR_API_KEY",
    {
      method: "POST",
      headers: { "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}`);
  ```
</CodeGroup>

Response (`201 Created`):

```json theme={null}
{
  "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:

```bash theme={null}
curl -X POST "https://partner-api.ochy-prod.com/analysis/start?apiKey=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](#list-analyses-for-a-subject).

When you [list all analyses](/api-reference/analysis/list-analyses), each item includes
the `subject_id` field if a subject was linked.

## List all subjects

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://partner-api.ochy-prod.com/subjects?apiKey=YOUR_API_KEY"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://partner-api.ochy-prod.com/subjects",
      params={"apiKey": "YOUR_API_KEY"},
  )

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

Response:

```json theme={null}
{
  "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

```bash theme={null}
curl "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000?apiKey=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**.

```bash theme={null}
curl -X PUT "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weight": 63}'
```

Response:

```json theme={null}
{
  "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.

```bash theme={null}
curl -X POST "https://partner-api.ochy-prod.com/subjects/550e8400-e29b-41d4-a716-446655440000/delete?apiKey=YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "message": "Subject deleted"
}
```

## List analyses for a subject

Retrieve all analysis IDs linked to a specific subject:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://partner-api.ochy-prod.com/analysis/subjects/550e8400-e29b-41d4-a716-446655440000?apiKey=YOUR_API_KEY"
  ```

  ```python Python theme={null}
  response = requests.get(
      f"https://partner-api.ochy-prod.com/analysis/subjects/{subject_id}",
      params={"apiKey": "YOUR_API_KEY"},
  )

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

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://partner-api.ochy-prod.com/analysis/subjects/${subjectId}?apiKey=YOUR_API_KEY`
  );
  const { analysis_ids, count } = await res.json();
  console.log(`Found ${count} analyses for this subject`);
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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.                     |