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

# Introduction

> Integrate running biomechanical analysis into your application with the Ochy Partner API.

Ochy is a biomechanical analysis platform that turns a short video of a runner into
detailed performance data -- running metrics, joint angles, foot landing patterns,
pronation analysis, and running style classification.

The Partner API gives you programmatic access to this analysis engine. Upload a video,
wait for processing, and retrieve structured results that you can display in your own
product.

## What you can do

<CardGroup cols={2}>
  <Card title="Side view analysis" icon="person-running" href="/guides/example-videos#side-view">
    Capture a runner from the side to get biomechanical scores, running metrics (speed,
    step length, cadence, ground contact time), joint angles, overstride analysis, foot
    landing patterns, and running style classification.
  </Card>

  <Card title="Back view analysis" icon="person" href="/guides/example-videos#back-view">
    Capture a runner from behind to get pronation/supination data, pelvic drop, knee
    adduction, hip adduction, and gait cycle metrics for each leg.
  </Card>

  <Card title="Subject management" icon="users" href="/guides/subject-management">
    Create subjects to group analyses by individual runner. Track metadata,
    link analyses, and retrieve per-subject history.
  </Card>

  <Card title="Shoe recommendation" icon="shoe" href="/guides/shoe-recommendation">
    Combine a runner questionnaire with completed side and/or back analyses to obtain
    ideal shoe characteristics and ranked catalog matches (three-step flow).
  </Card>
</CardGroup>

## Video requirements

Upload an MP4, MOV, AVI, or WEBM file -- max 10 seconds, max 30 MB. Required orientation
(landscape or portrait) depends on the analysis type and whether the runner is on a treadmill.

<Tip>
  See [example videos](/guides/example-videos) for the full orientation matrix, resolution
  guidance, and sample input/output clips.
</Tip>

## How it works

<Steps>
  <Step title="Upload a video">
    Send a short video of a runner to the
    [start analysis](/api-reference/analysis/start-analysis) endpoint.
    Make sure the video meets the [orientation and format requirements](#video-requirements)
    for the chosen analysis type. You receive a `video_id` immediately.
  </Step>

  <Step title="Poll for results">
    Use the [get results](/api-reference/analysis/get-analysis-results) endpoint
    with your `video_id`. The status progresses from `pending` to `analyzing` to `success`.
    You can also use [webhooks](/guides/webhooks-and-api-keys#webhooks-overview) to receive pushed updates instead of
    polling only.
  </Step>

  <Step title="Retrieve data">
    Once the analysis is complete, the results endpoint returns biomechanical data,
    signed URLs for the annotated video and thumbnail. You can also fetch
    [calculated metrics](/api-reference/analysis/get-calculated-data)
    and [raw frame data](/api-reference/analysis/get-raw-data) separately.
  </Step>
</Steps>

## Use with AI coding agents

This documentation is designed to be **agent-friendly**. The entire API is described
by an OpenAPI 3.0 specification with detailed descriptions, typed schemas, and
realistic examples for every endpoint and response -- making it easy for AI coding
assistants to understand and generate accurate integration code.

Two machine-readable files are available at the root of this documentation site
(same access code as the docs):

| File             | URL                                 | Purpose                                                                |
| ---------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| **llms.txt**     | `https://docs.ochy.io/llms.txt`     | Documentation index -- lets an AI agent discover all available pages   |
| **openapi.yaml** | `https://docs.ochy.io/openapi.yaml` | Full API specification -- endpoints, parameters, schemas, and examples |

### Setup

Save the OpenAPI spec to your project so AI tools can reference it locally:

<Steps>
  <Step title="Download the spec">
    <a href="/openapi.yaml" download="openapi.yaml">Download openapi.yaml</a> and
    place it at the root of your project (or any convenient path).
  </Step>

  <Step title="Give your AI tool context">
    Point your coding assistant at the local file. See the tool-specific
    instructions below.
  </Step>

  <Step title="Ask for code">
    The spec contains every endpoint, parameter, schema, and realistic example
    response -- your AI tool will generate accurate integration code from it.
  </Step>
</Steps>

### Cursor

Reference the local spec file in chat with **`@openapi.yaml`**, then ask Cursor
to generate integration code.

For **permanent context**, create a Cursor rule at `.cursor/rules/ochy-api.mdc`:

```markdown theme={null}
# Ochy Partner API

When working with the Ochy API, refer to the OpenAPI spec at the project root
for endpoints, parameters, and response schemas:

- Spec file: @openapi.yaml
- Base URL: https://partner-api.ochy-prod.com
- Auth: API key passed as `?apiKey=` query parameter
- All endpoints use metric units: height in meters, weight in kilograms
```

### Other AI tools

| Tool                 | How to use                                                                     |
| -------------------- | ------------------------------------------------------------------------------ |
| **GitHub Copilot**   | Open `openapi.yaml` in a tab or reference it in chat with `#file:openapi.yaml` |
| **ChatGPT / Claude** | Upload the spec file, then ask for integration code                            |
| **Windsurf**         | Reference `openapi.yaml` in chat with `@openapi.yaml`                          |
| **Cline / Aider**    | Point at the spec file in your project root                                    |

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run your first analysis in under 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how API key authentication works.
  </Card>

  <Card title="Analysis workflow" icon="diagram-project" href="/guides/analysis-workflow">
    Understand the full analysis lifecycle, video constraints, and polling strategy.
  </Card>

  <Card title="API keys and webhooks" icon="paper-plane" href="/guides/webhooks-and-api-keys">
    Receive progress and completion events on your server without polling.
  </Card>

  <Card title="Subject management" icon="users" href="/guides/subject-management">
    Organize analyses by individual runner with subjects.
  </Card>

  <Card title="Shoe recommendation" icon="shoe" href="/guides/shoe-recommendation">
    Questionnaire plus analyses to get ranked shoe matches and parameter recommendations.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/analysis/start-analysis">
    Browse all endpoints with request and response schemas.
  </Card>
</CardGroup>