> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/No-Country-simulation/S02-26-Equipo-33-Web-App/llms.txt
> Use this file to discover all available pages before exploring further.

# List Horses

> List active horse listings with filtering, pagination, and sorting

## Authentication

Optional - Public endpoint, authentication provides additional features

## Query Parameters

<ParamField query="breed" type="string">
  Filter by breed (case-insensitive partial match)
</ParamField>

<ParamField query="discipline" type="string">
  Filter by discipline (case-insensitive partial match)
</ParamField>

<ParamField query="country" type="string">
  Filter by country (case-insensitive partial match)
</ParamField>

<ParamField query="region" type="string">
  Filter by region (case-insensitive partial match)
</ParamField>

<ParamField query="min_price" type="number">
  Minimum price filter
</ParamField>

<ParamField query="max_price" type="number">
  Maximum price filter
</ParamField>

<ParamField query="search" type="string">
  Full-text search across name, breed, discipline, and pedigree
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination (minimum: 1)
</ParamField>

<ParamField query="limit" type="number" default="12">
  Number of results per page (minimum: 1, maximum: 50)
</ParamField>

<ParamField query="sort" type="string" default="created_at">
  Sort order. Options:

  * `created_at` - Newest first (default)
  * `price_asc` - Price low to high
  * `price_desc` - Price high to low
  * `age` - Age ascending
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of horse listings

  <ResponseField name="_id" type="string">
    Horse unique identifier
  </ResponseField>

  <ResponseField name="seller_id" type="object">
    Seller information

    <ResponseField name="_id" type="string">
      Seller ID
    </ResponseField>

    <ResponseField name="full_name" type="string">
      Seller full name
    </ResponseField>

    <ResponseField name="seller_profile" type="object">
      <ResponseField name="is_verified_badge" type="boolean">
        Whether seller has verified badge
      </ResponseField>
    </ResponseField>
  </ResponseField>

  <ResponseField name="name" type="string">
    Horse name
  </ResponseField>

  <ResponseField name="age" type="number">
    Horse age in years
  </ResponseField>

  <ResponseField name="breed" type="string">
    Horse breed
  </ResponseField>

  <ResponseField name="discipline" type="string">
    Primary discipline
  </ResponseField>

  <ResponseField name="pedigree" type="string">
    Pedigree information
  </ResponseField>

  <ResponseField name="location" type="object">
    <ResponseField name="country" type="string" required>
      Country location
    </ResponseField>

    <ResponseField name="region" type="string" required>
      Region/state
    </ResponseField>

    <ResponseField name="city" type="string">
      City
    </ResponseField>

    <ResponseField name="coordinates" type="object">
      <ResponseField name="lat" type="number">
        Latitude
      </ResponseField>

      <ResponseField name="lng" type="number">
        Longitude
      </ResponseField>
    </ResponseField>
  </ResponseField>

  <ResponseField name="price" type="number">
    Listing price
  </ResponseField>

  <ResponseField name="currency" type="string">
    Currency code (USD, EUR, ARS, BRL, MXN)
  </ResponseField>

  <ResponseField name="photos" type="array">
    Array of photos (minimum 3)

    <ResponseField name="url" type="string" required>
      Photo URL
    </ResponseField>

    <ResponseField name="caption" type="string">
      Photo caption
    </ResponseField>

    <ResponseField name="is_cover" type="boolean">
      Whether this is the cover photo
    </ResponseField>

    <ResponseField name="uploaded_at" type="string">
      Upload timestamp
    </ResponseField>
  </ResponseField>

  <ResponseField name="videos" type="array">
    Array of videos

    <ResponseField name="url" type="string" required>
      Video URL
    </ResponseField>

    <ResponseField name="embed_url" type="string">
      Auto-generated embed URL for YouTube/Vimeo
    </ResponseField>

    <ResponseField name="video_type" type="string" required>
      Type: training, competition, other
    </ResponseField>

    <ResponseField name="title" type="string">
      Video title
    </ResponseField>

    <ResponseField name="description" type="string">
      Video description
    </ResponseField>

    <ResponseField name="recorded_at" type="string" required>
      Recording date
    </ResponseField>

    <ResponseField name="uploaded_at" type="string">
      Upload timestamp
    </ResponseField>
  </ResponseField>

  <ResponseField name="status" type="string">
    Listing status: active, sold, paused, draft
  </ResponseField>

  <ResponseField name="views_count" type="number">
    Number of views
  </ResponseField>

  <ResponseField name="created_at" type="string">
    Creation timestamp
  </ResponseField>

  <ResponseField name="updated_at" type="string">
    Last update timestamp
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <ResponseField name="page" type="number">
    Current page number
  </ResponseField>

  <ResponseField name="limit" type="number">
    Results per page
  </ResponseField>

  <ResponseField name="total" type="number">
    Total number of results
  </ResponseField>

  <ResponseField name="pages" type="number">
    Total number of pages
  </ResponseField>
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.horsetrust.com/api/horses?breed=thoroughbred&discipline=jumping&page=1&limit=12&sort=price_asc" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.horsetrust.com/api/horses?breed=thoroughbred&discipline=jumping&page=1&limit=12&sort=price_asc', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.get(
      'https://api.horsetrust.com/api/horses',
      params={
          'breed': 'thoroughbred',
          'discipline': 'jumping',
          'page': 1,
          'limit': 12,
          'sort': 'price_asc'
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "seller_id": {
          "_id": "507f191e810c19729de860ea",
          "full_name": "John Smith",
          "seller_profile": {
            "is_verified_badge": true
          }
        },
        "name": "Thunder",
        "age": 8,
        "breed": "Thoroughbred",
        "discipline": "Show Jumping",
        "pedigree": "Sire: Storm Cat, Dam: Winning Colors",
        "location": {
          "country": "Argentina",
          "region": "Buenos Aires",
          "city": "San Isidro",
          "coordinates": {
            "lat": -34.4708,
            "lng": -58.5247
          }
        },
        "price": 45000,
        "currency": "USD",
        "photos": [
          {
            "url": "https://cdn.horsetrust.com/photos/abc123.jpg",
            "caption": "Thunder at competition",
            "is_cover": true,
            "uploaded_at": "2026-03-01T10:00:00Z"
          }
        ],
        "videos": [
          {
            "url": "https://youtube.com/watch?v=abc123",
            "embed_url": "https://www.youtube.com/embed/abc123",
            "video_type": "competition",
            "title": "Thunder jumping 1.40m",
            "recorded_at": "2026-02-15T00:00:00Z",
            "uploaded_at": "2026-03-01T10:00:00Z"
          }
        ],
        "status": "active",
        "views_count": 234,
        "created_at": "2026-03-01T10:00:00Z",
        "updated_at": "2026-03-05T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 12,
      "total": 45,
      "pages": 4
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseField name="success" type="boolean">
  false
</ResponseField>

<ResponseField name="message" type="string">
  Error description
</ResponseField>

### 500 - Server Error

```json theme={null}
{
  "success": false,
  "message": "Server error"
}
```