ClinovaVet API Documentation

Getting Started

The ClinovaVet API provides RESTful access to your clinic's data. All requests are made over HTTPS to https://app.clinova.vet/api/v1.

⚠️ Important: The API is currently in active development. Endpoints and response formats may change. We recommend versioning your integrations.

Base URL

https://app.clinova.vet/api/v1

Rate Limits

Rate limits are enforced to ensure system stability:

100 requests per minute per API key
1,000 requests per hour per API key

Authentication

All API requests require authentication using your secret API key. Include your key in the Authorization header as a Bearer token.

Obtaining Your API Key

Log in to your ClinovaVet account
Navigate to Settings → Modules
Enable the Developer API module
Copy your secret key (begins with sk_live_)

🔒 Security: Never expose your API key in client-side code, public repositories, or logs. Store it securely as an environment variable.

Example Request

curl https://app.clinova.vet/api/v1/owners \
  -H "Authorization: Bearer sk_live_a3f8b9c1e2d4f5g6h7i8j9k0l1m2n3o4p5q6"

Response Codes

Code	Meaning
200	Success
201	Resource created
400	Bad request (invalid parameters)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Owners

Manage client (pet owner) records.

GET /owners Paginated

Retrieve a list of all owners.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of records (default: 50, max: 100)
`offset`	integer	Pagination offset (default: 0)
`search`	string	Search by name, email, or phone

Example Request

GET /api/v1/owners?limit=10&search=Smith

Example Response

{
  "data": [
    {
      "id": "cku9g6x2p0000ab0f0s1z2z3z",
      "firstName": "John",
      "middleName": null,
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+1-555-123-4567",
      "address": "123 Main St, New York, NY 10001",
      "lastVisit": "2026-01-15T14:30:00.000Z",
      "createdAt": "2024-03-01T10:00:00.000Z",
      "updatedAt": "2026-01-15T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

GET /owners/{id}

Retrieve details for a specific owner.

Example Request

GET /api/v1/owners/cku9g6x2p0000ab0f0s1z2z3z

Example Response

{
  "id": "cku9g6x2p0000ab0f0s1z2z3z",
  "firstName": "John",
  "middleName": null,
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phone": "+1-555-123-4567",
  "address": "123 Main St, New York, NY 10001",
  "lastVisit": "2026-01-15T14:30:00.000Z",
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2026-01-15T14:30:00.000Z",
  "pets": [
    {
      "id": "cku9g7y3q0001ab0f0t2a3b4c",
      "name": "Max",
      "species": "Dog",
      "breed": "Golden Retriever"
    }
  ]
}

POST /owners

Create a new owner record.

Request Body

Field	Type	Required	Description
`firstName`	string	Yes	Owner's first name
`lastName`	string	Yes	Owner's last name
`middleName`	string	No	Owner's middle name
`email`	string	No	Email address
`phone`	string	No	Phone number
`address`	string	No	Physical address

Example Request

POST /api/v1/owners
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+1-555-987-6543",
  "address": "456 Oak Ave, Brooklyn, NY 11201"
}

Example Response

{
  "id": "cku9h8z4r0002ab0f0u3b4c5d",
  "firstName": "Jane",
  "middleName": null,
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+1-555-987-6543",
  "address": "456 Oak Ave, Brooklyn, NY 11201",
  "lastVisit": null,
  "createdAt": "2026-01-20T21:45:00.000Z",
  "updatedAt": "2026-01-20T21:45:00.000Z"
}

Pets

Manage patient (pet) records.

GET /pets Paginated

Retrieve a list of all pets.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of records (default: 50, max: 100)
`offset`	integer	Pagination offset
`ownerId`	string	Filter by owner ID
`species`	string	Filter by species (Dog, Cat, etc.)

Example Response

{
  "data": [
    {
      "id": "cku9g7y3q0001ab0f0t2a3b4c",
      "name": "Max",
      "species": "Dog",
      "breed": "Golden Retriever",
      "birthdate": "2020-05-15T00:00:00.000Z",
      "weight": 32.5,
      "neutered": true,
      "ownerId": "cku9g6x2p0000ab0f0s1z2z3z",
      "createdAt": "2024-03-01T10:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 87,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

POST /pets

Create a new pet record.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Pet's name
`species`	string	Yes	Dog, Cat, Bird, etc.
`ownerId`	string	Yes	Owner's ID
`breed`	string	No	Breed name
`birthdate`	string	No	ISO 8601 date
`weight`	number	No	Weight in kg
`neutered`	boolean	No	Default: false

Example Request

POST /api/v1/pets
Content-Type: application/json

{
  "name": "Bella",
  "species": "Cat",
  "breed": "Siamese",
  "ownerId": "cku9g6x2p0000ab0f0s1z2z3z",
  "birthdate": "2022-08-20",
  "weight": 4.2,
  "neutered": true
}

Medical Records

Access SOAP notes and diagnostic data.

GET /medical-records Paginated

Retrieve medical records.

Query Parameters

Parameter	Type	Description
`petId`	string	Filter by pet ID
`startDate`	string	ISO date filter (from)
`endDate`	string	ISO date filter (to)

Example Response

{
  "data": [
    {
      "id": "cku9i9a5s0003ab0f0v4c5d6e",
      "date": "2026-01-15T14:30:00.000Z",
      "title": "Annual Checkup",
      "description": "Patient alert and responsive...",
      "diagnosis": "Healthy, no concerns",
      "treatment": "Continue current diet, schedule next checkup",
      "differentialDiagnosis": null,
      "bloodTestJson": null,
      "urineTestJson": null,
      "petId": "cku9g7y3q0001ab0f0t2a3b4c",
      "createdById": "auth0|123456",
      "createdAt": "2026-01-15T14:30:00.000Z"
    }
  ]
}

Invoices

Manage billing and payments.

GET /invoices Paginated

Retrieve invoices.

Query Parameters

Parameter	Type	Description
`status`	string	PAID, UNPAID, CANCELLED
`ownerId`	string	Filter by owner

Example Response

{
  "data": [
    {
      "id": "cku9j0b6t0004ab0f0w5d6e7f",
      "invoiceNumber": "INV-2026-001523",
      "totalAmount": 245.50,
      "status": "PAID",
      "ownerId": "cku9g6x2p0000ab0f0s1z2z3z",
      "petId": "cku9g7y3q0001ab0f0t2a3b4c",
      "itemsJson": "[{\"name\":\"Rabies Vaccine\",\"price\":45.00,\"quantity\":1}]",
      "createdAt": "2026-01-15T15:00:00.000Z"
    }
  ]
}

Error Handling

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Owner with ID 'invalid-id' not found",
    "details": {}
  }
}

Common Error Codes

Code	Description
`INVALID_API_KEY`	API key is missing or invalid
`RESOURCE_NOT_FOUND`	Requested resource doesn't exist
`VALIDATION_ERROR`	Request body validation failed
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Server-side error occurred

✨ Need Help?
Contact our support team at galaxyorb.cloud/contact or open a support ticket for technical assistance.