API Reference
TrackerAI API
Integrate veterinary AI directly into your applications. Authenticate with your API key and call POST /analyse for one-shot clinical analysis, or POST /telemetry for longitudinal monitoring.
Authentication
All API requests must include an X-API-Key header with a valid API key. Generate one from the API Keys page.
http
X-API-Key: trai_sk_YOUR_KEY_HERE
API key usage is counted against your account's daily quota, same as web app usage.
Base URL
text
https://tracker--trackerai-backend-fastapi-app.modal.run/api/v1
Endpoint
POST/api/v1/analyseRun a veterinary analysis
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| model_type | "completion"|"reasoning"|"behavioral" | Yes | Model to use. "completion" and "reasoning" use the same input schema; "behavioral" requires behavioral_subtype. |
| behavioral_subtype | "collar"|"clinical" | No | Required when model_type is "behavioral". Selects wearable-sensor or clinical-history schema. |
| chat_id | integer | No | If provided, appends the message to an existing chat. Must be owned by the authenticated user and have the same model_type. |
| input_data | object | Yes | Model-specific input fields. See schemas below. |
input_data schemas
| Field | Type | Required | Description |
|---|---|---|---|
| species | string | Yes | Animal species, e.g. 'Canine', 'Feline' |
| breed | string | Yes | Breed name, e.g. 'Labrador Retriever' |
| age | string | Yes | Age with units, e.g. '3 years', '6 months' |
| sex | string | Yes | Sex and reproductive status, e.g. 'Male neutered' |
| weight | string | Yes | Body weight with units, e.g. '28 kg' |
| clinical_history | string | Yes | Free-text presenting complaint and relevant history |
Response (200)
| Field | Type | Required | Description |
|---|---|---|---|
| chat_id | integer | Yes | ID of the chat record created or updated |
| message_id | integer | Yes | ID of the assistant message created |
| output.summary | string | Yes | 1-2 sentence clinical summary |
| output.clinical_reasoning | string | null | Yes | Detailed reasoning (reasoning model only) |
| output.differentials | Differential[] | Yes | Up to 5 differential diagnoses |
| output.confidence_level | "low"|"moderate"|"high" | Yes | Model's overall confidence |
| output.emergency_flag | boolean | Yes | True only if objective markers indicate immediate danger |
| output.emergency_justification | string | null | Yes | Required if emergency_flag is true |
| output.recommended_workup | string[] | Yes | Up to 8 recommended diagnostic steps |
| output.initial_management | string[] | Yes | Initial management steps |
| output.prognosis | string | Yes | Prognosis statement |
| output.disclaimer | string | Yes | Standard clinical disclaimer |
| emergency_flag | boolean | Yes | Top-level emergency flag (mirrors output.emergency_flag) |
| confidence_level | string | Yes | Top-level confidence level |
| retry_count | integer | Yes | Number of self-consistency retries used |
Code examples
curl
curl -X POST https://tracker--trackerai-backend-fastapi-app.modal.run/api/v1/analyse \
-H "X-API-Key: trai_sk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"model_type": "completion",
"input_data": {
"species": "Canine",
"breed": "Labrador Retriever",
"age": "4 years",
"sex": "Male neutered",
"weight": "32 kg",
"clinical_history": "Acute onset vomiting x 3 episodes in 12h. Inappetent. No diarrhoea. Up to date on vaccinations."
}
}'Longitudinal Monitoring (Telemetry)
Stream biomechanical / behavioural observations for a patient over time. TrackerAI maintains per-patient baselines, detects trends and drift, and returns a longitudinal analysis. The POST /telemetry endpoint accepts an X-API-Key or Bearer token; the patient endpoints below use a Bearer session token.
POST/api/v1/telemetryIngest one observation
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| schema_version | string | No | Contract version. Default "petgym.telemetry.v1". |
| patient | object | Yes | Patient signalment (see below). |
| observation | object | Yes | The reading (see below). |
| analyse | boolean | No | Run the longitudinal analysis immediately and return it. Default true. |
| Field | Type | Required | Description |
|---|---|---|---|
| external_id | string | Yes | Your patient reference. Maps to (or creates) a TrackerAI patient under your account. |
| species | string | Yes | e.g. 'Canine', 'Feline' |
| breed | string | No | Breed name |
| sex | string | No | Sex |
| neuter_status | string | No | 'Neutered' or 'Intact' |
| date_of_birth | string (ISO) | No | Used to derive age |
| weight_kg | number | No | Body weight in kg |
| name | string | No | Display name |
| Field | Type | Required | Description |
|---|---|---|---|
| recorded_at | string (ISO 8601) | Yes | Timestamp of the reading. |
| external_id | string | No | Idempotency key — a repeat returns the existing observation. |
| session_type | "rehab_session"|"daily_monitoring"|"post_op_check"|"baseline_capture"|"ad_hoc" | No | Context of the reading. Default 'ad_hoc'. |
| source | "petgym_device"|"wearable_collar"|"video_system"|"manual_entry" | No | Where the data came from. |
| device | object | No | { device_id, firmware_version } — provenance. |
| processing | object | No | { pipeline_version, processed_at } — biomechanics provenance. |
| metrics | Metric[] | No | List of measurements (item shape below). |
| events | string[] | No | Discrete observations, e.g. 'completed 8/10 reps'. |
| notes | string | No | Free-text clinician/owner notes. |
Response (200)
| Field | Type | Required | Description |
|---|---|---|---|
| patient_id | integer | Yes | TrackerAI patient id. |
| observation_id | integer | Yes | Stored observation id. |
| created | boolean | Yes | False if an idempotent duplicate was found. |
| analysis | object | null | Yes | LongitudinalAnalysisOutput when analyse=true: summary, trend_assessment, metric_trends, clinical_reasoning, drift_detected, alerts, recommended_actions, confidence_level… |
bash
curl -X POST https://tracker--trackerai-backend-fastapi-app.modal.run/api/v1/telemetry \
-H "X-API-Key: trai_sk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"schema_version": "petgym.telemetry.v1",
"patient": {
"external_id": "PG-10293",
"species": "Canine",
"breed": "Labrador Retriever",
"sex": "Male", "neuter_status": "Neutered", "weight_kg": 31.2
},
"observation": {
"external_id": "OBS-55821",
"recorded_at": "2026-06-04T09:00:00Z",
"session_type": "rehab_session",
"source": "petgym_device",
"metrics": [
{ "key": "mobility_score", "value": 72, "unit": "index_0_100", "confidence": 0.9 },
{ "key": "gait_symmetry_index", "value": 0.82, "unit": "ratio" }
],
"events": ["completed 8/10 reps"],
"notes": "Owner reports stiffness after rest."
},
"analyse": true
}'Patient & analysis endpoints
POST/telemetryIngest one observation (creates/links the patient, updates baselines, runs the analysis). API key or Bearer.
GET/patientsList your monitored patients.
POST/patientsCreate a patient.
GET/patients/{id}Get a patient.
DELETE/patients/{id}Delete a patient and all of its data.
GET/patients/{id}/observationsList a patient's observations.
POST/patients/{id}/observationsAdd one observation to a known patient (runs the analysis).
GET/patients/{id}/timelineMetric series + full analysis & observation history + open alerts.
GET/patients/{id}/alertsList open alerts.
POST/patients/{id}/alerts/{alertId}/ackAcknowledge an alert.
POST/patients/{id}/analyseRe-run the analysis on the latest observation.
Error codes
401
Unauthorized
Missing or invalid API key / Bearer token.
403
Forbidden
Account is inactive, or API access is not enabled for your account.
404
Not Found
Patient or resource not found, or not owned by your account.
422
Unprocessable Entity
Input validation failed. Check the error detail for which field is missing or invalid.
429
Too Many Requests
Daily quota exhausted. Resets at midnight UTC.
500
Internal Server Error
Analysis pipeline failed. Retry once; if persistent, contact support.