# Open Gaits API Guide

This guide explains how to read data from the Open Gaits (opengaits.com)
database using the public API — no prior API experience required.

## What this is

Open Gaits satellite sites (stables, associations, and other
community sites) can pull live data — horses, shows, results,
members, entities, and the stud directory — without needing direct
database access. The API lives on **opengaits.com** and hands back
data as **JSON**, a simple text format any programming language can
read.

This version is **read-only** (it can only return data, never
change anything) and **open** (no password or API key required —
anyone can read it, the same way anyone can browse opengaits.com's
public pages today).

## Base URL

```
https://opengaits.com/api/
```

## Endpoints

| Endpoint | What it returns |
|---|---|
| `/api/horses.php` | The horse registry |
| `/api/shows.php` | Shows, and (with `?results=1`) show results |
| `/api/members.php` | Members and entities (stables, businesses, associations) |
| `/api/studs.php` | The stud directory (horses currently standing at stud) |

## How to use it (no coding required, to start)

The simplest way to see it work: type a URL into your browser.
Visiting:

```
https://opengaits.com/api/horses.php
```

...returns a page of text like this:

```json
{
    "ok": true,
    "meta": {
        "generated_at": "2026-09-19T14:02:00+00:00",
        "page": 1,
        "per_page": 25,
        "total": 130,
        "total_pages": 6
    },
    "data": [
        { "id": 1, "name": "Comet", "...": "..." },
        { "id": 2, "name": "Ashfire", "...": "..." }
    ]
}
```

`"data"` is the list you asked for, `"meta"` tells you how many
pages there are, and `"ok": true` means nothing went wrong. If
something did go wrong, you'll see `"ok": false` and an `"error"`
message explaining what.

Every endpoint is paginated — 25 results per page by default, up to
100 per page with `?per_page=`.

## Horses — `/api/horses.php`

| Parameter | Example | What it does |
|---|---|---|
| `id` | `?id=42` | One specific horse |
| `search` | `?search=Comet` | Search by name |
| `owner_id` | `?owner_id=7` | Every horse belonging to one owner |
| `stable_id` | `?stable_id=3` | Every horse belonging to one stable |
| `page`, `per_page` | `?page=2&per_page=50` | Pagination |

`owner_id` and `stable_id` are different things: `owner_id` is the
member/entity that owns the horse directly, `stable_id` is which
stable the horse is kept at (a stable is its own record, with its
own owner). Use whichever one fits what you're building.

Each horse includes both the raw id and the looked-up display name
for its linked lookup values, so you don't need to keep your own
copies of these lists:

- `stable_id` / `stable_name`
- `breed_id` / `breed_name`
- `color_id` / `color_name`
- `pattern_id` / `pattern_name`
- `discipline_id` / `discipline_name` / `discipline_category` / `discipline_level`

## Studs — `/api/studs.php`

Studs aren't a separate table — they're horses currently marked as
standing at stud, so this endpoint mirrors `horses.php` filtered
down to those horses, with `stud_fee` included.

| Parameter | Example | What it does |
|---|---|---|
| `id` | `?id=9` | One specific stud entry |
| `breed` | `?breed=Friesian` | Filter by breed name |
| `owner_id` | `?owner_id=7` | Every stud belonging to one owner |
| `page`, `per_page` | `?page=2&per_page=50` | Pagination |

## Shows & Results — `/api/shows.php`

**Shows:**

| Parameter | Example | What it does |
|---|---|---|
| `id` | `?id=17` | One specific show |
| `status` | `?status=Approved` | Filter by status |
| `host_id` | `?host_id=7` | Every show hosted by one account |
| `discipline` | `?discipline=Eventing` | Only shows with a class in this discipline |
| `page`, `per_page` | `?page=2&per_page=50` | Pagination |

`discipline` matters when one account hosts shows across more than
one discipline (an account that hosted general shows before a site
narrowed to one discipline, say) — `host_id` alone would still pull
every discipline that account has ever run. Combine the two to scope
a site to just its own discipline.

Every show (single lookup or list) includes `host_name`, looked up
from the hosting account, alongside its raw `host_account_id`.

**Results** — add `results=1`, plus at least one of `id`,
`horse_id`, `owner_id`, or `host_id` (they can combine):

| Example | What it returns |
|---|---|
| `?results=1&id=17` | Every result from one show |
| `?results=1&horse_id=42` | One horse's full show record |
| `?results=1&owner_id=7` | Every result for every horse one owner has |
| `?results=1&host_id=7` | Every result across every show one account hosted — this is what an association site uses to build a standings/leaderboard page |
| `?results=1&host_id=7&discipline=Eventing` | Same, but only results from that account's Eventing classes |

Each result includes `horse_name`, `show_name`, `show_date`,
`host_name`, `class_name`, `class_category`, `class_level`, and
`placing`, so you don't need to cross-reference `horse_id` /
`show_id` / `show_class_id` / `host_account_id` yourself.

## Members & Entities — `/api/members.php`

"Members" are individual player accounts; "entities" are stables,
businesses, and associations.

| Parameter | Example | What it does |
|---|---|---|
| `type` | `?type=member` or `?type=entity` | Which registry to query (default: member) |
| `id` | `?type=entity&id=5` | One specific record |
| `category` | `?type=entity&category=Stable` | Filter entities by category |
| `page`, `per_page` | `?page=2&per_page=50` | Pagination |

## Using it in code

This is what replaces writing your own SQL against the shared
database. A satellite site's PHP page can do this instead:

```php
<?php
// Ask opengaits.com's API for page 1 of the horse registry
$response = file_get_contents('https://opengaits.com/api/horses.php');
$result = json_decode($response, true);

if ($result['ok']) {
    foreach ($result['data'] as $horse) {
        echo htmlspecialchars($horse['name'])
           . ' (' . htmlspecialchars($horse['breed_name']) . ')<br>';
    }
} else {
    echo 'Could not load horses right now.';
}
```

No database password anywhere in that code — it just asks a
question over the web and reads the answer back, the same way
visiting a web page works.

## What's *not* in this version (on purpose)

- **No writing data** (entering a show, registering a horse, etc.)
  — this first version is intentionally read-only, so it can be
  used safely before anything is trusted to change the database.
  Write access may be added later as a separate, more carefully
  guarded set of endpoints.
- **No API key** — anyone can read this data, the same as
  opengaits.com's public pages today. If that ever needs to change
  (for example, if private data is ever added to one of these
  tables), an API key can be layered on without rebuilding anything.

## Questions or errors?

If an endpoint ever returns `"ok": false` with a database-related
error, or a field is unexpectedly empty, reach out with the exact
error message and it can be tracked down and fixed.