API-Referenz

Complete documentation of all LISA REST API endpoints.

Base URL#

• Production: https://api.biocv.info/api/v1
• Development: http://localhost:3000/api/v1

Authentication#

Most endpoints require JWT token authentication:

Authorization: Bearer <jwt-token>

Public endpoints (no authentication required):

• Health check
• Token generation
• Token refresh
• Firebase auth verification

Health Check#

Check API status (no authentication required).

Response:

{
  "success": true,
  "message": "LISA REST API is running",
  "timestamp": "2024-12-01T08:47:16.838Z",
  "version": "v1"
}

Token Management#

Get information about available token endpoints (no authentication required).

Response:

{
  "success": true,
  "message": "Token management endpoints",
  "endpoints": {
    "POST /tokens": {
      "description": "Generate JWT access and refresh tokens",
      "body": {
        "integratorUID": "string (required)",
        "expiresIn": "number (optional, 300-86400 seconds)",
        "refreshToken": "boolean (optional, default: false)"
      }
    },
    "GET /tokens/validate": {
      "description": "Validate JWT token and get token information",
      "headers": {
        "Authorization": "Bearer <jwt-token>"
      }
    },
    "POST /tokens/refresh": {
      "description": "Refresh access token using refresh token",
      "body": {
        "refreshToken": "string (required)"
      }
    },
    "POST /tokens/revoke": {
      "description": "Revoke JWT token (logout)",
      "headers": {
        "Authorization": "Bearer <jwt-token>"
      }
    },
    "GET /tokens/info": {
      "description": "Get detailed token information (requires valid token)",
      "headers": {
        "Authorization": "Bearer <jwt-token>"
      }
    }
  },
  "documentation": "https://github.com/BioCV-GmbH/lisa-rest-api/wiki",
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Generate JWT access and refresh tokens.

Request Body:

{
  "integratorUID": "your-integrator-uid",
  "expiresIn": 3600,
  "refreshToken": true
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": 1640995200000,
    "tokenType": "Bearer"
  },
  "message": "Token generated successfully",
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Refresh access token using refresh token.

Request Body:

{
  "refreshToken": "your-refresh-token"
}

Validate JWT token and get token information.

Headers:

Authorization: Bearer <jwt-token>

Revoke JWT token (logout).

Headers:

Authorization: Bearer <jwt-token>

Authentication#

Verify Firebase ID token and return user information.

Request Body:

{
  "idToken": "firebase-id-token-here"
}

Logout user (client-side token invalidation).

Users#

Get all users (admin only).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Get specific user (requires ownership).

Parameters:

• userId (path): User ID

Response:

{
  "success": true,
  "data": {
    "Uid": "user123",
    "Email": "user@example.com",
    "Name": "John Doe",
    "Language": "en",
    "Phone": "+1234567890",
    "Flagged": false,
    "Inactive": false,
    "BDUser": false
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Create new user (requires BDUser permission).

Request Body:

{
  "Email": "user@example.com",
  "Name": "John Doe",
  "Language": "en",
  "Phone": "+1234567890",
  "Uid": "user123",
  "Flagged": false,
  "Inactive": false,
  "BDUser": false
}

Update user (requires ownership).

Partial update user (requires ownership).

Delete user (requires ownership).

Search users with filters (BDUser permission required).

Query Parameters:

• email (optional): Filter by email
• name (optional): Filter by name
• flagged (optional): Filter by flagged status
• inactive (optional): Filter by inactive status
• language (optional): Filter by language

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/search?email=user@example.com&flagged=false"

Get user profile (public info only, requires ownership).

Response:

{
  "success": true,
  "data": {
    "Uid": "user123",
    "Name": "John Doe",
    "Language": "en"
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Get user's FCM tokens (requires ownership).

Add FCM token (requires ownership).

Request Body:

{
  "token": "fcm-token-here",
  "customName": "My Phone",
  "name": "John's iPhone",
  "email": "user@example.com",
  "rank": 1
}

Update user status (requires ownership).

Request Body:

{
  "flagged": false,
  "inactive": false,
  "requestDeletion": false
}

Animals#

Get all animals for a user (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals?page=1&limit=20"

Response:

{
  "success": true,
  "data": [
    {
      "ID": "Cow_001",
      "MAC": "AA:BB:CC:DD:EE:FF",
      "Group": "Barn_A",
      "Sex": "female",
      "Active": true,
      "CurrentTemperature": 38.5,
      "ReferenceTemperature": 38.2,
      "ReferenceTemperatureUpdatedAt": 1701345600000,
      "ReferenceTemperatureWindowDays": 7,
      "Battery": 85,
      "t": 1701432000000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "totalPages": 2
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Get specific animal (requires ownership).

Parameters:

• userId (path): User ID
• animalId (path): Animal ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/Cow_001"

Search animals with filters (requires ownership).

Query Parameters:

• group (optional): Filter by group
• sex (optional): Filter by sex (male/female)
• active (optional): Filter by active status
• suspicious (optional): Filter by suspicious status
• mac (optional): Filter by MAC address

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/search?group=Barn_A&sex=female&active=true"

Get location data for an animal (requires ownership).

Onboarding note: this endpoint exposes ANT+ positioning data uploaded by BioCV nodes. Each row represents a tag detection at a node with a timestamp (t), signal strength (rssi), and node ID (nodeuid), so treat it as proximity or coverage data rather than GPS. Use startTime and endTime to bound the time window and limit to cap results; the backing BigQuery dataset is configured via BIGQUERY_LOCATIONS_DATASET (default ants).

Query Parameters:

• startTime (optional): Start time in milliseconds since epoch
• endTime (optional): End time in milliseconds since epoch
• limit (optional): Maximum rows to return (default: 100, max: 10000)
• sortOrder (optional): Sort order ('asc' or 'desc', default: 'desc')

Get raw BioTag sensor samples for an animal (requires ownership).

This endpoint returns the raw time-series { t, c, x, y, z } from BigQuery (dataset animals by default; configurable via BIGQUERY_ANIMALS_DATASET). Timestamps (t) are milliseconds since epoch.

Query Parameters:

• startTime (optional): Start time in milliseconds since epoch
• endTime (optional): End time in milliseconds since epoch
• limit (optional): Maximum rows to return (default: 100, max: 10000)
• sortOrder (optional): Sort order ('asc' or 'desc', default: 'desc')

Get latest raw BioTag sensor samples for an animal (requires ownership).

Query Parameters:

• count (optional): Number of samples (default: 10, min: 1, max: 100)

Get raw BioTag sensor analytics for an animal (requires ownership).

Query Parameters:

• timeRange (optional): Predefined time ranges: 1h, 6h, 24h, 7d, 30d (default: 24h)

Get all AI predictions for an animal (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• classificationType (optional): Filter by prediction type (heat/birth/lameness)
• startDate (optional): Start date filter (ISO 8601 format)
• endDate (optional): End date filter (ISO 8601 format)
• minProbability (optional): Minimum probability threshold (0.0-1.0)
• maxProbability (optional): Maximum probability threshold (0.0-1.0)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions?classificationType=heat&minProbability=0.8"

Get predictions by classification type (requires ownership).

Parameters:

• classificationType (path): heat, birth, or lameness

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions/heat"

Get recent predictions (requires ownership).

Query Parameters:

• limit (optional): Number of recent predictions (1-100, default: 10)
• classificationType (optional): Filter by prediction type

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions/recent?limit=5&classificationType=heat"

Get predictions within date range (requires ownership).

Query Parameters:

• startDate (required): Start date (ISO 8601 format)
• endDate (required): End date (ISO 8601 format)
• classificationType (optional): Filter by prediction type

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions/range?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z&classificationType=birth"

Treatments#

Get all treatments for a user (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/treatments?page=1&limit=10"

Get specific treatment (requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/treatments/treatment_001"

Search treatments with filters (requires ownership).

Query Parameters:

• archived (optional): Filter by archived status
• mac (optional): Filter by MAC address
• medicine (optional): Filter by medicine
• diagnose (optional): Filter by diagnosis

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/treatments/search?archived=false&medicine=Antibiotic"

Get active treatments (Archived: false, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/treatments/active"

Get archived treatments (Archived: true, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/treatments/archived"

Create new treatment record (requires ownership).

Request Body:

{
  "Mac": "AA:BB:CC:DD:EE:FF",
  "Medicine": "Penicillin",
  "Diagnose": "Mastitis",
  "CustomName": "Dr. Smith",
  "Comment": "Left front quarter infection",
  "TreatmentAmount": 5,
  "TreatmentCount": 0,
  "TreatmentInterval": 12,
  "StartDate": "2024-01-15",
  "StartDateSeconds": 1705329000,
  "Archived": false,
  "PhoneHistory": [],
  "Dosis": 10.5,
  "Group": "Barn A",
  "Validated": false
}

Required Fields:

• Mac: Animal MAC address (must exist in user's Animals collection)
• Medicine: Medicine name
• Diagnose: Diagnosis
• CustomName: Veterinarian/technician name
• Comment: Treatment notes
• TreatmentAmount: Total treatments planned
• TreatmentCount: Treatments completed
• TreatmentInterval: Hours between treatments
• StartDate: Start date (string)
• StartDateSeconds: Start date as Unix timestamp
• Archived: Archive status
• PhoneHistory: Array of phone history entries

Optional Fields:

• Dosis: Dosage amount
• Group: Animal group
• Validated: Validation status

Response:

{
  "success": true,
  "data": {
    "ID": "1705329000000",
    "Mac": "AA:BB:CC:DD:EE:FF",
    "Medicine": "Penicillin",
    "Diagnose": "Mastitis",
    "CustomName": "Dr. Smith",
    "Comment": "Left front quarter infection",
    "TreatmentAmount": 5,
    "TreatmentCount": 0,
    "TreatmentInterval": 12,
    "StartDate": "2024-01-15",
    "StartDateSeconds": 1705329000,
    "Archived": false,
    "PhoneHistory": [],
    "Dosis": 10.5,
    "Group": "Barn A",
    "Validated": false,
    "t": 1705329000000
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Example:

curl -X POST "https://api.biocv.info/api/v1/users/user123/treatments" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "Mac": "AA:BB:CC:DD:EE:FF",
    "Medicine": "Penicillin",
    "Diagnose": "Mastitis",
    "CustomName": "Dr. Smith",
    "Comment": "Left front quarter infection",
    "TreatmentAmount": 5,
    "TreatmentCount": 0,
    "TreatmentInterval": 12,
    "StartDate": "2024-01-15",
    "StartDateSeconds": 1705329000,
    "Archived": false,
    "PhoneHistory": []
  }'

Births#

Get all birth records for a user (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births?page=1&limit=10"

Get specific birth record (requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births/birth_001"

Search birth records with filters (requires ownership).

Query Parameters:

• archived (optional): Filter by archived status
• mac (optional): Filter by MAC address

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births/search?archived=false"

Get active birth records (Archived: false, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births/active"

Get archived birth records (Archived: true, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births/archived"

Get birth statistics (requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/births/statistics"

Response:

{
  "success": true,
  "data": {
    "totalBirths": 25,
    "totalLiving": 300,
    "totalDead": 5,
    "averageLitterSize": 12.2,
    "survivalRate": 98.36
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Create new birth record (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "Living": 8,
  "Dead": 1,
  "StartDate": "2024-01-15",
  "StartTime": "14:30",
  "Comment": "Normal birth, one stillborn",
  "Archived": false,
  "Uid": "user123"
}

Required Fields:

• MAC: Animal MAC address (must exist in user's Animals collection)
• Living: Number of living offspring
• Dead: Number of dead offspring
• StartDate: Birth date (string)
• StartTime: Birth time (string)
• Comment: Birth notes
• Archived: Archive status
• Uid: User ID

Response:

{
  "success": true,
  "data": {
    "ID": "1705329000000",
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Living": 8,
    "Dead": 1,
    "StartDate": "2024-01-15",
    "StartTime": "14:30",
    "Comment": "Normal birth, one stillborn",
    "Archived": false,
    "Uid": "user123",
    "t": 1705329000000
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Example:

curl -X POST "https://api.biocv.info/api/v1/users/user123/births" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Living": 8,
    "Dead": 1,
    "StartDate": "2024-01-15",
    "StartTime": "14:30",
    "Comment": "Normal birth, one stillborn",
    "Archived": false,
    "Uid": "user123"
  }'

Inseminations#

Get all insemination records for a user (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/inseminations?page=1&limit=10"

Get specific insemination record (requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/inseminations/insemination_001"

Search insemination records with filters (requires ownership).

Query Parameters:

• archived (optional): Filter by archived status
• mac (optional): Filter by MAC address
• boar (optional): Filter by boar
• geneticLine (optional): Filter by genetic line

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/inseminations/search?archived=false&geneticLine=Yorkshire"

Get active insemination records (Archived: false, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/inseminations/active"

Get archived insemination records (Archived: true, requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/inseminations/archived"

Create new insemination record (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "Boar": "Boar_001",
  "GeneticLine": "Yorkshire",
  "Tubes": 2,
  "StartDate": "2024-01-15",
  "StartTime": "09:00",
  "Archived": false,
  "Occupied": true,
  "Uid": "user123"
}

Required Fields:

• MAC: Animal MAC address (must exist in user's Animals collection)
• Boar: Boar identification
• GeneticLine: Genetic line information
• Tubes: Number of tubes used
• StartDate: Insemination date (string)
• StartTime: Insemination time (string)
• Archived: Archive status
• Occupied: Occupied status
• Uid: User ID

Response:

{
  "success": true,
  "data": {
    "ID": "1705329000000",
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Boar": "Boar_001",
    "GeneticLine": "Yorkshire",
    "Tubes": 2,
    "StartDate": "2024-01-15",
    "StartTime": "09:00",
    "Archived": false,
    "Occupied": true,
    "Uid": "user123",
    "t": 1705329000000
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Example:

curl -X POST "https://api.biocv.info/api/v1/users/user123/inseminations" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Boar": "Boar_001",
    "GeneticLine": "Yorkshire",
    "Tubes": 2,
    "StartDate": "2024-01-15",
    "StartTime": "09:00",
    "Archived": false,
    "Occupied": true,
    "Uid": "user123"
  }'

LitterGuards (IoT Sensors)#

Get all LitterGuard devices for a user (requires ownership).

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')
• active (optional): Filter by device status (true/false)
• mac (optional): Filter by MAC address
• name (optional): Filter by device name

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards?active=true"

Get LitterGuard summary statistics (requires ownership).

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/summary"

Response:

{
  "success": true,
  "data": {
    "totalDevices": 5,
    "activeDevices": 4,
    "inactiveDevices": 1,
    "averageTemperature": 23.8,
    "devicesWithUnusualActivity": 0,
    "lastDataReceived": 1705392000
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Get specific LitterGuard device (requires ownership).

Parameters:

• macAddress (path): Device MAC address (e.g., "AA:BB:CC:DD:EE:FF")

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/AA:BB:CC:DD:EE:FF"

Get sensor readings for a device (requires ownership).

Query Parameters:

• timeRange (optional): Predefined time range - '1h', '6h', '24h', '7d', '30d'
• startTime (optional): Unix timestamp for start of data range
• endTime (optional): Unix timestamp for end of data range
• limit (optional): Maximum number of readings (1-100, default: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/AA:BB:CC:DD:EE:FF/sensordata?timeRange=24h&limit=50"

Get latest sensor readings (requires ownership).

Query Parameters:

• count (optional): Number of latest readings (1-100, default: 10)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/AA:BB:CC:DD:EE:FF/sensordata/latest?count=20"

Get analytics for a device (requires ownership).

Query Parameters:

• timeRange (optional): Time range for analytics - '1h', '6h', '24h', '7d', '30d' (default: '24h')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/AA:BB:CC:DD:EE:FF/analytics?timeRange=7d"

Response:

{
  "success": true,
  "data": {
    "averageTemperature": 23.2,
    "averageAccelerationMagnitude": 1.8,
    "temperatureRange": {
      "min": 22.1,
      "max": 24.5
    },
    "activityLevel": "normal",
    "unusualActivityDetected": false,
    "dataPointsCount": 1440,
    "timeRange": {
      "start": 1705305600,
      "end": 1705392000
    }
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Search LitterGuard devices with filters (requires ownership).

Query Parameters:

• active (optional): Filter by device status (true/false)
• mac (optional): Filter by MAC address
• name (optional): Filter by device name
• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/search?active=true&name=Barn"

Animal Production Data#

These endpoints provide access to production data records filtered by specific animals. All endpoints require ownership of the animal's user account.

Births (Animal-scoped)#

Get all birth records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address (e.g., "AA:BB:CC:DD:EE:FF")

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/births?page=1&limit=10"

Get a specific birth record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• birthId (path): Birth record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/births/1698765432000"

Get recent birth records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/births/recent?limit=5"

Get birth records within a date range for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• startDate (required): Start date in ISO 8601 format (e.g., "2024-01-01T00:00:00.000Z")
• endDate (required): End date in ISO 8601 format (e.g., "2024-01-31T23:59:59.999Z")

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/births/range?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z"

Create a new birth record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "Living": 10,
  "Dead": 0,
  "StartDate": "2024-01-15",
  "StartTime": "14:30:00",
  "Comment": "Normal birth, no complications",
  "Archived": false,
  "Mummified": 0,
  "Weaned": 9,
  "Parity": 3,
  "Assisted": false,
  "FarrowingDuration": 180,
  "Complications": null,
  "AverageLitterWeight": 1.5
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "Living": 10,
       "Dead": 0,
       "StartDate": "2024-01-15",
       "StartTime": "14:30:00",
       "Comment": "Normal birth"
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/births"

Response:

{
  "success": true,
  "data": {
    "ID": "1698765432000",
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Living": 10,
    "Dead": 0,
    "StartDate": "2024-01-15",
    "StartTime": "14:30:00",
    "t": 1698765432000
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Inseminations#

Get all insemination records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/inseminations?page=1&limit=10"

Get a specific insemination record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• inseminationId (path): Insemination record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/inseminations/1698765432000"

Get recent insemination records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/inseminations/recent?limit=5"

Get insemination records within a date range for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• startDate (required): Start date in ISO 8601 format
• endDate (required): End date in ISO 8601 format

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/inseminations/range?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z"

Create a new insemination record for an animal (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "Boar": "Boar-001",
  "GeneticLine": "Line-A",
  "StartDate": "2024-01-15",
  "StartTime": "10:00:00",
  "Tubes": 3,
  "serviceOrder": 1,
  "serviceType": "AI",
  "Parity": 2
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "Boar": "Boar-001",
       "StartDate": "2024-01-15",
       "StartTime": "10:00:00"
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/inseminations"

General Events#

Get all general event records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/general-events"

Get a specific general event record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• eventId (path): General event record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/general-events/1698765432000"

Get recent general event records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/general-events/recent?limit=5"

Create a new general event record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "Diagnose": "Sickness",
  "Description": "Respiratory infection, treated with antibiotics",
  "Archived": false,
  "Comment": "Additional notes about the event",
  "Token": "optional-token-identifier"
}

Required Fields:

• MAC: Animal MAC address (must exist in user's Animals collection)
• Diagnose: Event type - one of: "Sickness", "Death", "Lameness", "Other", "Note", "Recovered"
• Description: Event description

Optional Fields:

• Archived: Archive status (default: false)
• Comment: Alternative description field
• Token: Optional token identifier

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "Diagnose": "Sickness",
       "Description": "Respiratory infection, treated with antibiotics"
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/general-events"

Response:

{
  "success": true,
  "data": {
    "ID": "1698765432000",
    "MAC": "AA:BB:CC:DD:EE:FF",
    "Uid": "user123",
    "Diagnose": "Sickness",
    "Description": "Respiratory infection, treated with antibiotics",
    "Archived": false,
    "t": 1698765432000
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Pregnancy Checks#

Get all pregnancy check records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/pregnancy-checks"

Get a specific pregnancy check record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• checkId (path): Pregnancy check record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/pregnancy-checks/1698765432000"

Get recent pregnancy check records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/pregnancy-checks/recent?limit=5"

Create a new pregnancy check record for an animal (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "checkDate": "2024-01-15",
  "checkNumber": 1,
  "result": "pregnant",
  "method": "ultrasound",
  "technician": "Dr. Smith",
  "notes": "Confirmed pregnancy"
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "checkDate": "2024-01-15",
       "result": "pregnant",
       "method": "ultrasound"
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/pregnancy-checks"

Return to Estrus#

Get all return to estrus event records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/return-to-estrus"

Get a specific return to estrus event record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• eventId (path): Return to estrus event record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/return-to-estrus/1698765432000"

Get recent return to estrus event records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/return-to-estrus/recent?limit=5"

Create a new return to estrus event record for an animal (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "returnDate": "2024-01-15",
  "returnType": "regular",
  "daysSinceService": 21,
  "reasonCode": "normal"
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "returnDate": "2024-01-15",
       "returnType": "regular",
       "daysSinceService": 21
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/return-to-estrus"

Weanings#

Get all weaning records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/weanings"

Get a specific weaning record for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• weaningId (path): Weaning record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/weanings/1698765432000"

Get recent weaning records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/weanings/recent?limit=5"

Create a new weaning record for an animal (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "weaningDate": "2024-01-15",
  "countWeaned": 9,
  "weaningAge": 28,
  "weaningWeight": 6.5
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "weaningDate": "2024-01-15",
       "countWeaned": 9
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/weanings"

Animal Movements#

Get all animal movement records for a specific animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)
• sortBy (optional): Field to sort by (default: 't')
• sortOrder (optional): 'asc' or 'desc' (default: 'desc')

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/movements"

Get a specific animal movement record (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address
• movementId (path): Animal movement record ID

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/movements/1698765432000"

Get recent animal movement records for an animal (requires ownership).

Parameters:

• userId (path): User ID who owns the animal
• animalMac (path): Animal MAC address

Query Parameters:

• limit (optional): Number of records to return (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/movements/recent?limit=5"

Create a new animal movement record (requires ownership).

Request Body:

{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "movementDate": "2024-01-15",
  "fromStage": "gestation",
  "toStage": "farrowing",
  "fromLocation": "Barn A",
  "toLocation": "Farrowing Unit B"
}

Example:

curl -X POST \
     -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{
       "MAC": "AA:BB:CC:DD:EE:FF",
       "movementDate": "2024-01-15",
       "fromStage": "gestation",
       "toStage": "farrowing"
     }' \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/movements"

Common Query Parameters#

Most endpoints support these parameters:

Pagination#

• page: Page number (default: 1, min: 1)
• limit: Items per page (default: 10, min: 1, max: 100)

Sorting#

• sortBy: Field to sort by (default: 't' for timestamp)
• sortOrder: Sort order - 'asc' or 'desc' (default: 'desc')

Filtering#

• Specific filter parameters vary by endpoint
• Use search endpoints for advanced filtering

Response Format#

All endpoints return responses in this consistent format:

Success Response#

{
  "success": true,
  "data": { ... },
  "message": "Operation successful",
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Paginated Response#

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Error Response#

{
  "success": false,
  "error": "Error message",
  "details": [ ... ],
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Rate Limiting#

• General API: 100 requests per 15 minutes per IP
• Token Endpoints: 20 requests per 15 minutes per IP
• Rate limit information included in response headers

HTTP Status Codes#

API tiers, quotas and raw data#

Every authenticated request is counted against a per-endpoint, per-day quota tied to your account's API tier, on top of the IP-based rate limiter:

• Reads and writes both count. Quota resets daily at 00:00 UTC.
• Watch X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers.
• Raw sensor data endpoints (.../animals/:animalMac/sensordata, .../sensordata/latest, .../sensordata/analytics) require the Pro or Enterprise tier. Lower tiers receive 403.
• Full commercial detail: see the internal Billing documentation.

Next Steps#

• 📖 Data Models - Complete data structure documentation
• 💡 Code Examples - Implementation examples in various languages
• ⚡ Best Practices - Optimal API usage guidelines
• 🔧 Troubleshooting - Common issues and solutions