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

# Create Horse

> Create a new horse listing (seller or admin only)

## Authentication

Required - JWT Bearer token with `seller` or `admin` role

```bash theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
```

## Request Body

<ParamField body="name" type="string" required>
  Horse name (trimmed)
</ParamField>

<ParamField body="age" type="number" required>
  Horse age in years (0-40)
</ParamField>

<ParamField body="breed" type="string" required>
  Horse breed (trimmed)
</ParamField>

<ParamField body="discipline" type="string" required>
  Primary discipline (trimmed)
</ParamField>

<ParamField body="pedigree" type="string">
  Pedigree information
</ParamField>

<ParamField body="location" type="object" required>
  Horse location information

  <ParamField body="country" type="string" required>
    Country
  </ParamField>

  <ParamField body="region" type="string" required>
    Region or state
  </ParamField>

  <ParamField body="city" type="string">
    City
  </ParamField>

  <ParamField body="coordinates" type="object">
    GPS coordinates

    <ParamField body="lat" type="number">
      Latitude
    </ParamField>

    <ParamField body="lng" type="number">
      Longitude
    </ParamField>
  </ParamField>
</ParamField>

<ParamField body="price" type="number">
  Listing price (minimum: 0)
</ParamField>

<ParamField body="currency" type="string" default="USD">
  Currency code: USD, EUR, ARS, BRL, MXN
</ParamField>

<ParamField body="photos" type="array" required>
  Array of photos (minimum 3 required)

  <ParamField body="url" type="string" required>
    Photo URL
  </ParamField>

  <ParamField body="caption" type="string">
    Photo caption
  </ParamField>

  <ParamField body="is_cover" type="boolean" default={false}>
    Whether this is the cover photo
  </ParamField>
</ParamField>

<ParamField body="videos" type="array">
  Array of videos (optional)

  <ParamField body="url" type="string" required>
    Video URL (YouTube or Vimeo URLs will auto-generate embed\_url)
  </ParamField>

  <ParamField body="video_type" type="string" required>
    Type: training, competition, other
  </ParamField>

  <ParamField body="title" type="string">
    Video title
  </ParamField>

  <ParamField body="description" type="string">
    Video description
  </ParamField>

  <ParamField body="recorded_at" type="string" required>
    Recording date (ISO 8601)
  </ParamField>
</ParamField>

## Response

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

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  Created horse listing

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

  <ResponseField name="seller_id" type="string">
    Seller ID (automatically set from authenticated user)
  </ResponseField>

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

  <ResponseField name="age" type="number">
    Horse age
  </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">
    Location details
  </ResponseField>

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

  <ResponseField name="currency" type="string">
    Currency code
  </ResponseField>

  <ResponseField name="photos" type="array">
    Array of photos with generated IDs and timestamps
  </ResponseField>

  <ResponseField name="videos" type="array">
    Array of videos with auto-generated embed\_url for YouTube/Vimeo
  </ResponseField>

  <ResponseField name="status" type="string">
    Initial status (always "draft")
  </ResponseField>

  <ResponseField name="views_count" type="number">
    Initial view count (always 0)
  </ResponseField>

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

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

## Notes

* New listings are created with `status: "draft"` by default
* `seller_id` is automatically set from the authenticated user
* `views_count` is initialized to 0
* Video `embed_url` is auto-generated for YouTube and Vimeo URLs
* Photos must include at least 3 items (validated)
* Full-text search index includes name, breed, discipline, and pedigree

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.horsetrust.com/api/horses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -d '{
      "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
        },
        {
          "url": "https://cdn.horsetrust.com/photos/abc124.jpg",
          "caption": "Side view"
        },
        {
          "url": "https://cdn.horsetrust.com/photos/abc125.jpg",
          "caption": "Training session"
        }
      ],
      "videos": [
        {
          "url": "https://youtube.com/watch?v=abc123",
          "video_type": "competition",
          "title": "Thunder jumping 1.40m",
          "recorded_at": "2026-02-15T00:00:00Z"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.horsetrust.com/api/horses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    },
    body: JSON.stringify({
      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
        },
        {
          url: 'https://cdn.horsetrust.com/photos/abc124.jpg',
          caption: 'Side view'
        },
        {
          url: 'https://cdn.horsetrust.com/photos/abc125.jpg',
          caption: 'Training session'
        }
      ],
      videos: [
        {
          url: 'https://youtube.com/watch?v=abc123',
          video_type: 'competition',
          title: 'Thunder jumping 1.40m',
          recorded_at: '2026-02-15T00:00:00Z'
        }
      ]
    })
  });

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

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

  response = requests.post(
      'https://api.horsetrust.com/api/horses',
      headers={
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_JWT_TOKEN'
      },
      json={
          '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
              },
              {
                  'url': 'https://cdn.horsetrust.com/photos/abc124.jpg',
                  'caption': 'Side view'
              },
              {
                  'url': 'https://cdn.horsetrust.com/photos/abc125.jpg',
                  'caption': 'Training session'
              }
          ],
          'videos': [
              {
                  'url': 'https://youtube.com/watch?v=abc123',
                  'video_type': 'competition',
                  'title': 'Thunder jumping 1.40m',
                  'recorded_at': '2026-02-15T00:00:00Z'
              }
          ]
      }
  )

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Horse listing created",
    "data": {
      "_id": "507f1f77bcf86cd799439011",
      "seller_id": "507f191e810c19729de860ea",
      "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": [
        {
          "_id": "65f1a2b3c4d5e6f7g8h9i0j1",
          "url": "https://cdn.horsetrust.com/photos/abc123.jpg",
          "caption": "Thunder at competition",
          "is_cover": true,
          "uploaded_at": "2026-03-05T10:00:00Z"
        },
        {
          "_id": "65f1a2b3c4d5e6f7g8h9i0j2",
          "url": "https://cdn.horsetrust.com/photos/abc124.jpg",
          "caption": "Side view",
          "is_cover": false,
          "uploaded_at": "2026-03-05T10:00:00Z"
        },
        {
          "_id": "65f1a2b3c4d5e6f7g8h9i0j3",
          "url": "https://cdn.horsetrust.com/photos/abc125.jpg",
          "caption": "Training session",
          "is_cover": false,
          "uploaded_at": "2026-03-05T10:00:00Z"
        }
      ],
      "videos": [
        {
          "_id": "65f1a2b3c4d5e6f7g8h9i0j4",
          "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-05T10:00:00Z"
        }
      ],
      "status": "draft",
      "views_count": 0,
      "created_at": "2026-03-05T10:00:00Z",
      "updated_at": "2026-03-05T10:00:00Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

### 400 - Validation Error

```json theme={null}
{
  "success": false,
  "message": "Horse validation failed: name: Horse name is required, photos: At least 3 photos are required"
}
```

### 401 - Unauthorized

```json theme={null}
{
  "success": false,
  "message": "Authentication required"
}
```

### 403 - Forbidden

```json theme={null}
{
  "success": false,
  "message": "Seller role required"
}
```

### 500 - Server Error

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