{ "openapi": "3.0.1", "info": { "title": "Animal Management", "description": "This portion of the API provides endpoints for managing animal records.", "version": "1.0" }, "servers": [ { "url": "https://api.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://api.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "security": [], "tags": [ { "name": "Animal", "description": "Represents basic animal data such as name, breed, birthday and so on. Each Animal must have an [`owner`](#contact)" }, { "name": "Breed", "description": "Defines and manages animal breeds within the system." }, { "name": "Sex", "description": "Defines and manages animal sex data (e.g., male, female, neutered)." }, { "name": "Species", "description": "Defines and manages animal species within the system." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.ezyvet.com/v1/oauth/access_token", "scopes": { "read-animal": "Read animal resources", "read-animalcolour": "Read animal colour resources", "read-breed": "Read breed resources", "read-sex": "Read sex resources", "read-species": "Read species resources", "write-animal": "Create and update animal resources" } } } } }, "parameters": { "active": { "name": "active", "in": "query", "description": "If true, the record is active and usable in ezyVet.", "required": false, "style": "form", "schema": { "type": "string" }, "example": "1" }, "AnimalV4-active": { "name": "active", "in": "query", "description": "If true, the record is active and usable in ezyVet.", "required": false, "style": "form", "schema": { "type": "string" }, "example": "1" }, "AnimalV4-createdAt": { "name": "createdAt", "in": "query", "description": "The ISO 8601 timestamp when the record was created.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "{\"gte\":\"2024-01-15T10:30:00Z\"}" }, "AnimalV4-id": { "name": "id", "in": "query", "description": "The unique identifier (uid) of the Animal. Accepts a single uid, or an `in` list of up to 100.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "{\"in\":[\"animal_AB3e7Z2i9FJu0j7hLExLp\",\"animal_Cd4F8g1H6jKl2m9N0pQrS\"]}" }, "AnimalV4-nextToken": { "name": "nextToken", "in": "query", "description": "A token to pass back to the server to get the next page of results.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "AB3e7Z2i9FJu0j7hLExLp" }, "AnimalV4-pageSize": { "name": "pageSize", "in": "query", "description": "Sets the number of items to be returned in each page. Default is 2000, Limit is 2000.", "required": false, "style": "form", "explode": true, "schema": { "type": "number", "default": 2000, "maximum": 2000 }, "example": 200 }, "AnimalV4-updatedAt": { "name": "updatedAt", "in": "query", "description": "The ISO 8601 timestamp when the record was last updated. Earlier API versions call this `modifiedAt`.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "{\"gte\":\"2024-12-15T00:00:00Z\",\"lte\":\"2024-12-20T14:22:00Z\"}" }, "breed-id": { "name": "id", "in": "query", "description": "The UID used by the system to uniquely identify a Breed.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "breed_Vy6dF2kM8nQ4rH0wC1jZe" }, "breed-legacyId": { "name": "legacyId", "in": "query", "description": "The legacy integer identifier for the Breed (passed as a string). Retained for backwards-compatibility with v1/v2 integrations.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "12" }, "created_at": { "name": "created_at", "in": "query", "description": "The epoch time when the record was created.", "required": false, "style": "form", "explode": true, "schema": { "type": "number" }, "example": 1695766710 }, "id": { "name": "id", "in": "query", "description": "The ezyVet ID of the record.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "1" }, "modified_at": { "name": "modified_at", "in": "query", "description": "The epoch time when the record was last modified", "required": false, "style": "form", "explode": true, "schema": { "type": "number" }, "example": 1695766710 }, "next_token": { "name": "next_token", "in": "query", "description": "A token to pass back to the server to get the next page of results.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "AB3e7Z2i9FJu0j7hLExLp" }, "nextToken": { "name": "nextToken", "in": "query", "description": "A token to pass back to the server to get the next page of results.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "AB3e7Z2i9FJu0j7hLExLp" }, "page_size": { "name": "page_size", "in": "query", "description": "Number of items per page. Default is 2000, maximum is 2000. Note: the legacy `limit` parameter is not supported and will return a 400 error.", "required": false, "style": "form", "explode": true, "schema": { "type": "number", "default": 2000, "maximum": 2000 }, "example": 200 }, "page_sizev1.1": { "name": "page_size", "in": "query", "description": "Sets the number of items to be returned in each page. Default is 2000, Limit is 2000.", "required": false, "style": "form", "explode": true, "schema": { "type": "number", "default": 2000, "maximum": 2000 }, "example": 200 }, "pageSize": { "name": "pageSize", "in": "query", "description": "Sets the number of items to be returned in each page. Default is 2000, Limit is 2000.", "required": false, "style": "form", "explode": true, "schema": { "type": "number", "default": 2000, "maximum": 2000 }, "example": 200 }, "species-id": { "name": "id", "in": "query", "description": "Filter by species UID only (`species_…`). Cannot be combined with `legacyId` on the same request. If no species matches the UID, the list endpoint returns **404** (same behaviour as Animal v4).", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "species_AB3e7Z2i9FJu0j7hLExLp" }, "species-legacyId": { "name": "legacyId", "in": "query", "description": "Filter by numeric species id (same value as the `legacyId` field on each Species resource). Must be a positive integer. Cannot be combined with the `id` (UID) filter on the same request. If no species matches, the list endpoint returns **404**.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 }, "species-name": { "name": "name", "in": "query", "description": "Filter by species name — **exact match** only.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "Canine" }, "species-status": { "name": "status", "in": "query", "description": "Return species with this `status` (`active` or `inactive`).", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/Status" }, "example": "active" }, "species-updatedAt": { "name": "updatedAt", "in": "query", "description": "Filter by last updated time (`speciesdata_time`). Value is a **URL-encoded JSON object** keyed by comparator, per the IDEXX API filtering standard. Supported comparators: `eq`, `gt`, `lt`, `gte`, `lte`. Multiple comparators may be combined in one object to express a range (e.g. `gte` + `lte`).\n\nExamples (raw JSON, before URL-encoding):\n- exact match — `updatedAt={\"eq\":\"2022-01-05T23:23:43Z\"}`\n- one-week range — `updatedAt={\"gte\":\"2024-05-17T00:00:00Z\",\"lte\":\"2024-05-24T00:00:00Z\"}`\n\nEach value must be a strict RFC-3339 instant: `YYYY-MM-DD` + `T` + `HH:MM:SS` (seconds required) + `Z` or `±HH:MM` (colon required). Unknown comparator keys return **400** `UnsupportedDateComparator`.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "{\"gte\":\"2024-05-17T13:00:00Z\",\"lte\":\"2024-05-24T00:00:00Z\"}" } }, "responses": { "AnimalV4-BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "AnimalV4-InternalServerError": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "AnimalV4-NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "AnimalV4-TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "AnimalV4-Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "AnimalV4-UnprocessableEntity": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-ErrorResponse" } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "BadRequestv4": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } }, "InternalError": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "500" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "An internal server error occurred" }, "detail": { "type": "string", "example": "An error occured, please contact API support with the id, status and code provided with the response." } } } } } }, "InternalErrorv4": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } }, "NotFound": { "description": "Not Found", "content": { "text/html": { "schema": { "type": "string", "example": "No input file specified." } } } }, "NotFoundv4": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "429" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "Too Many Requests" }, "detail": { "type": "string", "example": "Too Many Requests" } } } } } }, "TooManyRequestsv4": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "properties": { "level": { "type": "string", "example": "error" }, "type": { "type": "string", "example": "InvalidRequestException" }, "text": { "type": "string", "example": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \\\"access token\\\" parameter." }, "fields": { "type": "array", "example": [], "items": { "type": "string" } } } } } } } } } }, "Unauthorizedv4": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "422" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "Unprocessable Entity" }, "detail": { "type": "string", "example": "Unprocessable Entity" } } } } } }, "UnprocessableEntityv4": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponsev4" } } } } }, "schemas": { "AnimalItemv1": { "type": "object", "properties": { "animal": { "$ref": "#/components/schemas/Animalv1" } } }, "AnimalItemv1.1": { "type": "object", "properties": { "animal": { "$ref": "#/components/schemas/Animalv1.1" } } }, "AnimalItemv2": { "type": "object", "properties": { "animal": { "$ref": "#/components/schemas/Animalv2" } } }, "AnimalItemv2.1": { "type": "object", "properties": { "animal": { "$ref": "#/components/schemas/Animalv2.1" } } }, "AnimalListResponsev1": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Metav1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalItemv1" } }, "messages": { "type": "array", "items": { "type": "string" } } } }, "AnimalListResponsev1.1": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Metav1.1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalItemv1.1" } }, "messages": { "type": "array", "items": { "type": "string" } } } }, "AnimalListResponsev2": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Metav1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalItemv2" } }, "messages": { "type": "array", "items": { "type": "string" } } } }, "AnimalListResponsev2.1": { "type": "object", "description": "Standard v2-style response envelope with token-based pagination.", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalItemv2.1" } }, "messages": { "type": "array", "items": { "type": "string" } } } }, "Animalv1": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "string" }, "is_dead": { "type": "string" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "string" }, "species_id": { "type": "string" }, "breed_id": { "type": "string" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "string" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "string" }, "weight_unit": { "type": "string" }, "resuscitate": { "type": "string" }, "notes": { "type": "string" }, "notes_important": { "type": "string" }, "guid": { "type": "string" } } }, "Animalv1.1": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "string" }, "is_dead": { "type": "string" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "string" }, "species_id": { "type": "string" }, "breed_id": { "type": "string" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "string" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "string" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "boolean" }, "guid": { "type": "string" } } }, "Animalv2": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "number" }, "is_dead": { "type": "boolean" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "number" }, "species_id": { "type": "number" }, "breed_id": { "type": "number" }, "rabies_number": { "type": "string", "nullable": true }, "date_of_rabies_vaccination": { "type": "string", "nullable": true }, "microchip_number": { "type": "string" }, "contact_id": { "type": "number" }, "date_of_birth": { "type": "number" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "number" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "number" }, "weight_unit": { "type": "string" }, "resuscitate": { "type": "string" }, "notes": { "type": "string" }, "notes_important": { "type": "boolean" }, "guid": { "type": "string" } } }, "Animalv2.1": { "type": "object", "description": "Animal record in v2.1 format. Fields follow v2 snake_case conventions.\n\n**UID fields** (`uid`, `species_uid`, `breed_uid`, `contact_uid`) are new in v2.1. These correspond to the sole identifiers used in v4. Legacy integer ID fields are retained for backwards compatibility.\n", "properties": { "id": { "type": "integer", "description": "Legacy integer identifier for the Animal. Use `uid` for v4 migration.", "example": 42 }, "uid": { "type": "string", "description": "Globally unique identifier for the Animal. This becomes `id` in v4.", "example": "animal_AB3e7Z2i9FJu0j7hLExLp" }, "active": { "type": "boolean", "description": "If true, the Animal is active and usable in ezyVet.", "example": true }, "created_at": { "type": "integer", "description": "Unix epoch timestamp when the Animal was created.", "example": 1705312200 }, "modified_at": { "type": "integer", "description": "Unix epoch timestamp when the Animal was last modified.", "example": 1734705720 }, "name": { "type": "string", "description": "The name of the Animal.", "example": "Buddy" }, "code": { "type": "string", "description": "The custom code override for the Animal.", "example": "A0001234567890" }, "sex_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the Sex.", "example": 3 }, "sex_reference": { "type": "string", "nullable": true, "description": "Abbreviated sex reference (e.g. \"MN\" for Male Neutered, \"FE\" for Female Entire, \"U\" for Unknown). New in v2.1.", "example": "MN" }, "is_dead": { "type": "boolean", "description": "If true, the Animal is deceased.", "example": false }, "is_hostile": { "type": "string", "description": "Demeanour label for the Animal. One of \"Friendly\", \"Caution\", \"Unfriendly\", or \"Unknown\".", "example": "Friendly" }, "animalcolour_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the AnimalColour.", "example": 5 }, "species_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the Species. Use `species_uid` for v4 migration.", "example": 1 }, "species_uid": { "type": "string", "nullable": true, "description": "Globally unique identifier for the Species. New in v2.1 — corresponds to `species.id` in v4.", "example": "species_Tm4hG7nJ1bP9sK3wL5xRq" }, "breed_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the Breed. Use `breed_uid` for v4 migration.", "example": 12 }, "breed_uid": { "type": "string", "nullable": true, "description": "Globally unique identifier for the Breed. New in v2.1 — corresponds to `breed.id` in v4.", "example": "breed_Vy6dF2kM8nQ4rH0wC1jZe" }, "rabies_number": { "type": "string", "description": "The rabies registration number of the Animal.", "example": "" }, "date_of_rabies_vaccination": { "type": "integer", "nullable": true, "description": "Unix epoch timestamp of the rabies vaccination date.", "example": null }, "microchip_number": { "type": "string", "description": "The microchip number of the Animal.", "example": "982000123456789" }, "contact_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the owner Contact. Use `contact_uid` for v4 migration.", "example": 87 }, "contact_uid": { "type": "string", "nullable": true, "description": "Globally unique identifier for the owner Contact. New in v2.1 — corresponds to `ownerId` in v4.", "example": "contact_Xk9mR4pL2vN8qW1sT7yB3" }, "date_of_birth": { "type": "integer", "nullable": true, "description": "Unix epoch timestamp of the Animal's date of birth.", "example": 1589500800 }, "is_estimated_date_of_birth": { "type": "boolean", "nullable": true, "description": "If true, the date of birth is an estimate.", "example": false }, "date_of_death": { "type": "integer", "nullable": true, "description": "Unix epoch timestamp of the Animal's date of death. Null if alive.", "example": null }, "death_reason": { "type": "string", "nullable": true, "description": "The reason for the Animal's death. Null if alive.", "example": null }, "date_of_desex": { "type": "integer", "nullable": true, "description": "Unix epoch timestamp of when the Animal was spayed/neutered.", "example": null }, "referring_clinic_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the referring clinic Contact.", "example": null }, "referring_vet_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the referring vet Contact.", "example": null }, "residence_contact_id": { "type": "integer", "nullable": true, "description": "Legacy integer ID of the residence Contact (caretaker, if different from owner).", "example": null }, "weight": { "type": "number", "format": "double", "nullable": true, "description": "The weight of the Animal.", "example": 28.5 }, "weight_unit": { "type": "string", "nullable": true, "description": "The unit of weight measurement.", "enum": [ "kg", "lb", "g" ], "example": "kg" }, "resuscitate": { "type": "string", "nullable": true, "description": "Resuscitation preference. \"0\" = No, \"1\" = Yes, \"3\" = Advanced Life Support.", "enum": [ "0", "1", "3" ], "example": "1" }, "notes": { "type": "string", "nullable": true, "description": "General notes about the Animal.", "example": "Friendly dog, loves treats." }, "notes_important": { "type": "boolean", "nullable": true, "description": "If true, the Animal's notes are marked as important.", "example": false }, "guid": { "type": "string", "nullable": true, "description": "Legacy GUID for the Animal.", "example": null } } }, "AnimalV4-Animal": { "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The unique identifier for the Animal.", "example": "animal_AB3e7Z2i9FJu0j7hLExLp" }, "code": { "type": "string", "description": "The custom code override for the Animal.", "example": "A0001234567890" }, "name": { "type": "string", "description": "The name of the Animal.", "example": "Buddy" }, "ownerId": { "type": "string", "description": "The ID of the owner (contact) of the Animal.", "example": "contact_Xk9mR4pL2vN8qW1sT7yB3" }, "species": { "$ref": "#/components/schemas/AnimalV4-Species" }, "sex": { "$ref": "#/components/schemas/AnimalV4-Sex" }, "dateOfBirth": { "$ref": "#/components/schemas/AnimalV4-DateOfBirth" }, "type": { "type": "string", "description": "The type of Animal. `individual` for a single animal record; `group` for a herd, flock or litter record.\n", "enum": [ "individual", "group" ], "example": "individual" }, "breed": { "$ref": "#/components/schemas/AnimalV4-Breed" }, "weight": { "$ref": "#/components/schemas/AnimalV4-Weight" }, "death": { "$ref": "#/components/schemas/AnimalV4-Death" }, "insured": { "type": "boolean", "description": "Indicates if the Animal is insured.", "example": false }, "primaryHospital": { "type": "string", "description": "The ID of the primary hospital for the Animal.", "example": "hospital_Jn5fQ8wK3xR6mD0pV2cYa" }, "notes": { "type": "string", "description": "General notes about the Animal.", "example": "Friendly dog, loves treats. Regular checkups every 6 months." }, "notesImportant": { "type": "boolean", "description": "Indicates the Animal's `notes` are flagged as important. The key is omitted when the flag has never been set on the record.\n", "example": false }, "demeanour": { "type": "array", "description": "List of demeanours (behavioural traits) associated with the Animal.", "items": { "$ref": "#/components/schemas/AnimalV4-Demeanour" }, "example": [ { "name": "Food aggressive", "color": "", "icon": "" }, { "name": "Social", "color": "", "icon": "" } ] }, "microchip": { "type": "string", "description": "The microchip number of the Animal.", "example": "982000123456789" }, "status": { "$ref": "#/components/schemas/AnimalV4-Status" }, "resuscitate": { "type": "string", "description": "Resuscitation preference for the Animal.", "enum": [ "yes", "no", "unknown" ], "example": "yes" }, "referringClinic": { "$ref": "#/components/schemas/AnimalV4-ReferringClinic" }, "referringVet": { "$ref": "#/components/schemas/AnimalV4-ReferringVet" }, "residenceContact": { "$ref": "#/components/schemas/AnimalV4-ResidenceContact" }, "createdAt": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the record was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the record was last updated.", "example": "2024-12-20T14:22:00Z" } } }, "AnimalV4-AnimalListResponse": { "type": "object", "description": "Response envelope for the list endpoint (GET /v4/animal). `meta` is always present — `{}` on the last page (no `nextToken`). `errors` is always present on the wire and is `[]` on success.\n", "required": [ "meta", "data", "errors" ], "properties": { "meta": { "$ref": "#/components/schemas/AnimalV4-Meta" }, "data": { "type": "array", "description": "Array of Animal objects.", "items": { "$ref": "#/components/schemas/AnimalV4-Animal" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalV4-Error" } } } }, "AnimalV4-AnimalResponse": { "type": "object", "description": "Response envelope for the single-item endpoint (GET /v4/animal/{id}). `data` holds the Animal object directly (not an array). No `meta` on single-item endpoints. `errors` is always present on the wire and is `[]` on success.\n", "required": [ "data", "errors" ], "properties": { "data": { "$ref": "#/components/schemas/AnimalV4-Animal" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalV4-Error" } } } }, "AnimalV4-Breed": { "type": "object", "description": "Represents the breed of an Animal.", "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Breed.", "example": "breed_Vy6dF2kM8nQ4rH0wC1jZe" }, "name": { "type": "string", "description": "The name of the Breed.", "example": "Golden Retriever" } } }, "AnimalV4-DateOfBirth": { "type": "object", "description": "Represents the date of birth information for an Animal.", "properties": { "date": { "type": "string", "format": "date", "description": "The date of birth in YYYY-MM-DD format.", "example": "2020-05-15" }, "isEstimated": { "type": "boolean", "description": "Indicates if the date of birth is estimated.", "example": false } } }, "AnimalV4-Death": { "type": "object", "description": "Death information for a deceased Animal. **Present only when the animal is deceased.** The entire `death` key is omitted from the Animal object for living animals, so clients must not assume it is always present.\n", "properties": { "isDead": { "type": "boolean", "description": "Always `true` when this object is present. (The object is omitted entirely for live animals.)", "example": true }, "date": { "type": "string", "format": "date", "description": "The date of death in `YYYY-MM-DD` format.", "example": "2024-11-16" }, "reason": { "type": "string", "description": "The reason for death recorded against the animal. Empty string if not provided.", "example": "Old age" } } }, "AnimalV4-Demeanour": { "type": "object", "description": "Represents a demeanour (behavioural trait) of an Animal.", "properties": { "name": { "type": "string", "description": "The name of the demeanour.", "example": "Food aggressive" }, "color": { "type": "string", "description": "The display color for the demeanour (e.g., hex code or color name).", "example": "" }, "icon": { "type": "string", "description": "The icon identifier or URL for the demeanour.", "example": "" } } }, "AnimalV4-Error": { "type": "object", "description": "A single error. Errors are machine-readable and do not carry user-facing text — use `code` to decide what happened and render your own message. The HTTP status is on the response status line and is not repeated on the error object.\n", "required": [ "id", "code" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this error occurrence, composed of a trace id and an incrementing error number separated by an underscore (`{traceId}_{errorNumber}`). Quote this value when contacting API support.\n", "example": "8954638926413656075_1" }, "code": { "type": "string", "description": "Machine-readable identifier for the error type. Use this to decide how to handle the error and to render your own localised message. Values returned by the v4 Animal endpoints:\n - `AnimalNotFound` — **404**, no Animal matches the supplied id.\n - `RateLimitExceeded` — **429**, too many requests. Back off and retry.\n - `InvalidPageSize` — **400**, `pageSize` was outside the range 1–2000.\n - `UnsupportedQueryParam` — **400**, an unrecognised query parameter was supplied. Note that `modifiedAt` is not accepted on v4 — use `updatedAt`.\n - `InvalidPaginationToken` — **400**, the `nextToken` value was not a valid continuation token. Request the first page again rather than constructing a token yourself.\n - `RedundantParamsWithNextToken` — **400**, `pageSize` or a filter was sent alongside `nextToken`. Send `nextToken` on its own.\n - `TokenEncodeFailed` — **400**, a continuation token could not be produced for this page. Retry the request, and contact API support if it persists.\n - `InvalidDateFilter` — **400**, a `createdAt` or `updatedAt` value was not a strict RFC-3339 instant.\n - `UnsupportedDateComparator` — **400**, a date filter used a comparator other than `eq`, `gt`, `gte`, `lt` or `lte`.\n - `TooManyFilterValues` — **400**, the `id={\"in\":[...]}` list held more than 100 values.\n - `InvalidIdFilter` — **400**, the `id` filter value was malformed — an empty `in` list, a non-string entry, a bare JSON array instead of an object, or a value that is not a valid uid.\n - `UnsupportedFilterOperator` — **400**, the `id` filter used an operator other than `in`.\n - `InternalError` — **500**, an unexpected error occurred. Quote the `id` when contacting API support.\n", "example": "AnimalNotFound" }, "target": { "type": "string", "description": "Optional JSON pointer (RFC 6901) to the offending request field.", "example": "/id" } } }, "AnimalV4-ErrorResponse": { "type": "object", "description": "Error response structure. No meta section as there is no data/pagination.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalV4-Error" } } } }, "AnimalV4-IsDeadFilter": { "type": "string", "enum": [ "true", "false" ], "description": "Filter by death status. true = deceased only, false = alive only." }, "AnimalV4-Meta": { "type": "object", "description": "List-endpoint pagination metadata. Always present on `GET /v4/animal`: an empty object `{}` on the last page (no `nextToken`), or `{nextToken: \"...\"}` when more pages remain. This schema is **only used by the list endpoint** — `GET /v4/animal/{id}` uses the single-item `AnimalResponse` envelope (no `meta`), so `Meta` does not apply there.\n", "properties": { "nextToken": { "type": "string", "description": "Continuation token. Send back as `?nextToken=...` alone (no other params) to fetch the next page. Absent on the last page.", "nullable": true, "example": "eyJsYXN0QW5pbWFsSWQiOjE4OSwicGFnZVNpemUiOjEwLCJmaWx0ZXJzIjp7fX0" } } }, "AnimalV4-ReferringClinic": { "type": "object", "description": "Represents a referring clinic for an Animal.", "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Referring Clinic.", "example": "contact_Rw3bN7pK1mX9sF5vQ2dLa" } } }, "AnimalV4-ReferringVet": { "type": "object", "description": "Represents a referring veterinarian for an Animal.", "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Referring Vet.", "example": "contact_Hj8cT4wM6nR2kG0pY1xBf" } } }, "AnimalV4-ResidenceContact": { "type": "object", "description": "Represents the residence contact for an Animal.", "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Residence Contact.", "example": "contact_Lm5qW9nJ3bP7sK1xR4vDy" } } }, "AnimalV4-Sex": { "type": "object", "description": "Represents the sex/gender of an Animal via a reference abbreviation and name.", "properties": { "reference": { "type": "string", "description": "The abbreviated reference for the sex (e.g. \"MN\" for Male Neutered, \"FE\" for Female Entire, \"U\" for Unknown).", "example": "MN" }, "name": { "type": "string", "description": "The full name/description of the sex.", "example": "Male Neutered" } } }, "AnimalV4-Species": { "type": "object", "description": "Represents the species of an Animal.", "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Species.", "example": "species_Tm4hG7nJ1bP9sK3wL5xRq" }, "name": { "type": "string", "description": "The name of the Species.", "example": "Dog" } } }, "AnimalV4-Status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Animal status", "example": "active" }, "AnimalV4-Weight": { "type": "object", "description": "Represents the weight of an Animal with its unit.", "properties": { "value": { "type": "number", "format": "double", "description": "The weight value.", "example": 28.5 }, "unit": { "type": "string", "description": "The unit of weight measurement.", "enum": [ "kg", "lb", "g" ], "example": "kg" } } }, "BadRequest": { "description": "Bad Request", "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "error_3YLvb0V7eXcHqgGauTjDy" }, "status": { "type": "string", "example": "400" }, "code": { "type": "string", "example": "100001" }, "title": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." }, "detail": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." } } } } } }, "BreedListStatusFilter": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Query filter for `GET /v4/breed`. `active` and `inactive` restrict results; `all` disables status filtering. When omitted, the default is `active`.", "example": "active" }, "BreedMeta": { "type": "object", "description": "Metadata present in list responses. Contains the pagination token for the next page.", "properties": { "nextToken": { "type": "string", "description": "Token for fetching the next page of results. Null or omitted when no more pages exist.", "nullable": true, "example": "AB3e7Z2i9FJu0j7hLExLp" } } }, "BreedResponse": { "type": "object", "description": "Response envelope for the list endpoint (GET /v4/breed). Includes meta (nextToken) and data (array of Breed).", "required": [ "data" ], "properties": { "meta": { "$ref": "#/components/schemas/BreedMeta" }, "data": { "type": "array", "description": "Array of Breed objects.", "items": { "$ref": "#/components/schemas/Breedv4" } } } }, "BreedSpeciesRef": { "type": "object", "description": "Represents the Species this Breed belongs to.", "nullable": true, "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Species.", "example": "species_Tm4hG7nJ1bP9sK3wL5xRq" }, "legacyId": { "type": "string", "description": "The legacy integer identifier for the Species (returned as a string). Retained for backwards-compatibility with v1/v2 integrations.", "example": "1" } } }, "Breedv4": { "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The unique identifier (UID) for the Breed.", "example": "breed_Vy6dF2kM8nQ4rH0wC1jZe" }, "legacyId": { "type": "string", "description": "The legacy integer identifier for the Breed (returned as a string). Retained for backwards-compatibility with v1/v2 integrations.", "example": "12" }, "name": { "type": "string", "description": "The name of the Breed.", "example": "Labrador" }, "species": { "$ref": "#/components/schemas/BreedSpeciesRef" }, "status": { "$ref": "#/components/schemas/Status" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "The ISO 8601 timestamp when the Breed was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "The ISO 8601 timestamp when the Breed was last updated.", "example": "2024-12-20T14:22:00Z" } } }, "ErrorResponsev4": { "type": "object", "description": "Error response structure. No meta section as there is no data/pagination.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Errorv4" } } } }, "Errorv4": { "type": "object", "description": "Error object per the VetSoft API Errors standard. Errors are programmatically interpretable — they do not carry user-facing text. HTTP status is the response status line; it is not duplicated on the error object.", "additionalProperties": true, "required": [ "id", "code" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this error occurrence, composed of the trace ID and an incrementing error number separated by underscore (e.g. \"{traceId}_{errorNumber}\"). Used for log correlation.", "example": "8954638926413656075_1" }, "code": { "type": "string", "description": "PascalCase machine-readable error code. Clients use this to determine the error type and render their own localised message.", "example": "InvalidPaginationCursor" }, "target": { "type": "string", "description": "Optional JSON Pointer (RFC 6901) to the field that caused the error. Omitted when the error is not field-specific.", "example": "/data/name" } } }, "Meta": { "type": "object", "description": "Pagination metadata. When more pages exist, `next_token` contains the token for the next page.", "properties": { "next_token": { "type": "string", "nullable": true, "description": "Token for fetching the next page. Null or absent when there are no more pages.", "example": "AB3e7Z2i9FJu0j7hLExLp" } } }, "Metav1": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "Metav1.1": { "type": "object", "properties": { "next_token": { "type": "string" } } }, "SpeciesListResponse": { "type": "object", "description": "Response envelope for GET /v4/species (list). Always includes `meta` (empty object when there is no `nextToken`, for example on the last page), `data` (array of Species) and `errors`. `errors` is always present on the wire and is `[]` on success.", "required": [ "meta", "data", "errors" ], "properties": { "meta": { "$ref": "#/components/schemas/SpeciesMeta" }, "data": { "type": "array", "description": "Array of Species objects.", "items": { "$ref": "#/components/schemas/Speciesv4" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Errorv4" } } } }, "SpeciesMeta": { "type": "object", "description": "List response metadata. Always present on GET /v4/species. When there is no following page, `nextToken` is omitted (empty meta object).", "properties": { "nextToken": { "type": "string", "description": "Opaque token for the next page. Value is **Base64URL** (RFC 4648 URL-safe alphabet, no padding) over UTF-8 JSON.\n\nThe payload encodes the list filter snapshot, the effective `pageSize` used for that page, and the numeric `species_id` cursor (not the public UID) so pagination stays aligned with `ORDER BY species_id`. On continuation requests, filter values are taken from the token; sending `id`, `name`, `status`, `updatedAt`, or `pageSize` alongside `nextToken` returns **400** (`RedundantParamsWithNextToken`).\n\n**Example decoded payload** (JSON before Base64URL encoding):\n\n```json\n{\n \"lastSpeciesId\": 123,\n \"pageSize\": 2000,\n \"filters\": {\n \"id\": null,\n \"name\": null,\n \"status\": null,\n \"updatedAt\": null\n }\n}\n```", "nullable": true, "example": "eyJsYXN0U3BlY2llc0lkIjoxMjMsInBhZ2VTaXplIjoyMDAwLCJmaWx0ZXJzIjp7ImlkIjpudWxsLCJuYW1lIjpudWxsLCJzdGF0dXMiOm51bGwsInVwZGF0ZWRBdCI6bnVsbH19" } } }, "SpeciesResponse": { "type": "object", "description": "Success envelope for GET /v4/species/{id}. `data` is the Species object directly (not an array). `meta` is omitted (no pagination for a single resource). `errors` is always present on the wire and is `[]` on success.", "required": [ "data", "errors" ], "properties": { "data": { "$ref": "#/components/schemas/Speciesv4" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Errorv4" } } } }, "Speciesv4": { "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the Species.", "example": "species_Tm4hG7nJ1bP9sK3wL5xRq" }, "legacyId": { "type": "string", "description": "Numeric species id as a string, for use with older integrations.", "example": "5" }, "name": { "type": "string", "description": "Name of the species.", "example": "Canine" }, "status": { "$ref": "#/components/schemas/Status" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "The ISO 8601 timestamp when the record was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "The ISO 8601 timestamp when the record was last updated.", "example": "2024-12-20T14:22:00Z" } } }, "Status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Animal status", "example": "active" } } }, "paths": { "/v1/animal": { "post": { "deprecated": true, "description": "Its recommended to use the [`v4/animal endpoint`](/#get-animal-v4)", "summary": "Creates a single Animal", "operationId": "create-animal", "tags": [ "Animal" ], "security": [ { "bearerAuth": [ "write-animal" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "number" }, "name": { "type": "string" }, "sex_id": { "type": "number" }, "animalcolour_id": { "type": "number" }, "species_id": { "type": "number" }, "breed_id": { "type": "number" }, "weight": { "type": "number" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "boolean" } }, "required": [ "contact_id", "name", "sex_id", "animalcolour_id", "species_id", "breed_id", "weight", "weight_unit", "resuscitate" ] } } } }, "responses": { "200": { "description": "A JSON object containing the created Animal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "animal": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "string" }, "is_dead": { "type": "string" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "string" }, "species_id": { "type": "string" }, "breed_id": { "type": "string" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "string" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "string" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "string" }, "guid": { "type": "string" } } } } } }, "messages": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "deprecated": true, "description": "Its recommended to use the [`v4/animal endpoint`](/#get-animal-v4)", "summary": "Fetches a list containing Animal(s)", "operationId": "get-animal", "tags": [ "Animal" ], "parameters": [ { "name": "id", "in": "query", "description": "The ID number used by the system to uniquely identify an Animal.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If true, the Animal is active and usable in ezyVet.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "The epoch time when the Animal was created.", "schema": { "type": "string" } }, { "name": "modified_at", "in": "query", "description": "The epoch time when the Animal was last modified.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "The name of the Animal.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The custom code override for the Animal.", "schema": { "type": "string" } }, { "name": "sex_id", "in": "query", "description": "The ID of the Sex of the Animal.", "schema": { "type": "string" } }, { "name": "is_dead", "in": "query", "description": "If true, the Animal is dead.", "schema": { "type": "boolean" } }, { "name": "is_hostile", "in": "query", "description": "If true, the Animal is not friendly. This is marked by the 'FRIENDLY' or 'CARE' image on ezyVet's Animal screen.", "schema": { "type": "boolean" } }, { "name": "animalcolour_id", "in": "query", "description": "The ID of the AnimalColour.", "schema": { "type": "string" } }, { "name": "species_id", "in": "query", "description": "The ID of the Species of the Animal.", "schema": { "type": "string" } }, { "name": "breed_id", "in": "query", "description": "The ID of the Breed of the Animal.", "schema": { "type": "string" } }, { "name": "rabies_number", "in": "query", "description": "The rabies registration number of the Animal. This field is not necessarily used by clinics throughout the world.", "schema": { "type": "string" } }, { "name": "date_of_rabies_vaccination", "in": "query", "description": "The epoch time that the Animal was vaccinated against rabies. This field is not necessarily used by clinics throughout the world.", "schema": { "type": "string" } }, { "name": "microchip_number", "in": "query", "description": "The microchip number of the Animal.", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "description": "The ID of the owner of the Animal.", "schema": { "type": "string" } }, { "name": "date_of_birth", "in": "query", "description": "The epoch time the Animal was born.", "schema": { "type": "string" } }, { "name": "is_estimated_date_of_birth", "in": "query", "description": "If true, the date of birth is considered to be an estimate only.", "schema": { "type": "boolean" } }, { "name": "date_of_death", "in": "query", "description": "The epoch time the Animal died.", "schema": { "type": "string" } }, { "name": "death_reason", "in": "query", "description": "The reason of the Animal death.", "schema": { "type": "string" } }, { "name": "date_of_desex", "in": "query", "description": "The epoch time the Animal was spayed/neutered.", "schema": { "type": "string" } }, { "name": "referring_clinic_id", "in": "query", "description": "The Contact ID of the clinic that referred the Animal.", "schema": { "type": "string" } }, { "name": "referring_vet_id", "in": "query", "description": "The Contact ID of the vet that referred the Animal.", "schema": { "type": "string" } }, { "name": "residence_contact_id", "in": "query", "description": "The Contact ID for the caretaker of the Animal. Populated if and only if the animal does not stay at the same residence as the owner.", "schema": { "type": "string" } }, { "name": "weight_unit", "in": "query", "description": "The unit of weight that the Animal was measured with. This can be either Kilogram (kg), Pounds (lb) or Grams (g).", "schema": { "type": "string", "enum": [ "kg", "lb", "g" ] } }, { "name": "weight", "in": "query", "description": "The weight of the Animal.", "schema": { "type": "string" } }, { "name": "resuscitate", "in": "query", "description": "Whether the Animal's owner would like it to be resuscitated or not. This can be either No (0), Yes (1) or Advanced Life Support (3).", "schema": { "type": "number", "enum": [ 0, 1, 3 ] } }, { "name": "notes", "in": "query", "description": "Notes that are displayed within ezyVet on the animal page.", "schema": { "type": "string" } }, { "name": "notes_important", "in": "query", "description": "If true, the Animal's notes are marked as important.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of Animals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalListResponsev1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v1/animal/{id}": { "patch": { "deprecated": true, "description": "Its recommended to use the [`v4/animal endpoint`](/#get-animal-v4)", "summary": "Updates a single Animal", "operationId": "update-animal", "security": [ { "bearerAuth": [ "write-animal" ] } ], "tags": [ "Animal" ], "parameters": [ { "name": "id", "in": "path", "description": "The ID of the Animal to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Animal data to update", "content": { "application/merge-patch+json": { "schema": { "type": "object", "properties": { "active": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "string" }, "is_dead": { "type": "string" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "string" }, "species_id": { "type": "string" }, "breed_id": { "type": "string" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "string" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "string" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "string" }, "guid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful update", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "string" }, "is_dead": { "type": "string" }, "is_hostile": { "type": "string" }, "animalcolour_id": { "type": "string" }, "species_id": { "type": "string" }, "breed_id": { "type": "string" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "string" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "string" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "string" }, "referring_vet_id": { "type": "string" }, "residence_contact_id": { "type": "string" }, "weight": { "type": "string" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "string" }, "guid": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "animal": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "sex_id": { "type": "number" }, "is_dead": { "type": "boolean" }, "is_hostile": { "type": "boolean" }, "animalcolour_id": { "type": "number" }, "species_id": { "type": "number" }, "breed_id": { "type": "number" }, "rabies_number": { "type": "string" }, "date_of_rabies_vaccination": { "type": "string" }, "microchip_number": { "type": "string" }, "contact_id": { "type": "number" }, "date_of_birth": { "type": "string" }, "is_estimated_date_of_birth": { "type": "boolean" }, "date_of_death": { "type": "string" }, "death_reason": { "type": "string" }, "date_of_desex": { "type": "string" }, "referring_clinic_id": { "type": "number" }, "referring_vet_id": { "type": "number" }, "residence_contact_id": { "type": "number" }, "weight": { "type": "string" }, "weight_unit": { "type": "string", "enum": [ "kg", "lb", "g" ] }, "resuscitate": { "type": "string", "enum": [ "0", "1", "3" ] }, "notes": { "type": "string" }, "notes_important": { "type": "boolean" }, "guid": { "type": "string" } }, "required": [ "id", "active", "created_at", "modified_at", "name", "code", "sex_id", "is_dead", "is_hostile", "animalcolour_id", "species_id", "breed_id", "contact_id", "weight", "resuscitate", "notes", "guid" ] } }, "required": [ "animal" ] } }, "messages": { "type": "array", "items": { "type": "string" } } }, "required": [ "meta", "items", "messages" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete an Animal", "operationId": "delete-animal", "security": [ { "bearerAuth": [ "write-animal" ] } ], "tags": [ "Animal" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the animal to delete", "required": true, "schema": { "type": "number" } }, { "name": "authorization", "in": "header", "description": "Bearer token for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful deletion of the animal", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_matched": { "type": "number" }, "items_processed": { "type": "number" } } }, "items": { "type": "array", "items": {} }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1.1/animal": { "get": { "summary": "Fetches a list containing Animal(s) - uses token pagination.", "operationId": "get-animalv1-1", "tags": [ "Animal" ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/active" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/modified_at" }, { "$ref": "#/components/parameters/page_sizev1.1" }, { "$ref": "#/components/parameters/next_token" }, { "name": "name", "in": "query", "description": "The name of the Animal.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The custom code override for the Animal.", "schema": { "type": "string" } }, { "name": "sex_id", "in": "query", "description": "The ID of the Sex of the Animal.", "schema": { "type": "string" } }, { "name": "is_dead", "in": "query", "description": "If true, the Animal is dead.", "schema": { "type": "boolean" } }, { "name": "is_hostile", "in": "query", "description": "If true, the Animal is not friendly. This is marked by the 'FRIENDLY' or 'CARE' image on ezyVet's Animal screen.", "schema": { "type": "boolean" } }, { "name": "animalcolour_id", "in": "query", "description": "The ID of the AnimalColour.", "schema": { "type": "string" } }, { "name": "species_id", "in": "query", "description": "The ID of the Species of the Animal.", "schema": { "type": "string" } }, { "name": "breed_id", "in": "query", "description": "The ID of the Breed of the Animal.", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "description": "The ID of the owner of the Animal.", "schema": { "type": "string" } }, { "name": "weight", "in": "query", "description": "The weight of the Animal.", "schema": { "type": "string" } }, { "name": "weight_unit", "in": "query", "description": "The unit of weight that the Animal was measured with. This can be either Kilogram (kg), Pounds (lb) or Grams (g).", "schema": { "type": "string", "enum": [ "kg", "lb", "g" ] } } ], "responses": { "200": { "description": "A list of Animals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalListResponsev1.1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v1/animalcolour": { "get": { "summary": "Fetch an AnimalColour list", "operationId": "get-animalcolour", "description": "Fetches a list containing [`AnimalColour`](#animalcolour)(s). (up to 10)", "tags": [ "Animal Colour" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "The ID number used by the system to uniquely identify an [`AnimalColour`](#animalcolour)." }, { "name": "active", "in": "query", "schema": { "type": "string" }, "description": "If **true**, the [`AnimalColour`](#animalcolour) is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`AnimalColour`](#animalcolour) was created." }, { "name": "modified_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`AnimalColour`](#animalcolour) was last modified." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`AnimalColour`](#animalcolour)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "procedure": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-animalcolour" ] } ] } }, "/v1/breed": { "get": { "summary": "Fetch a Breed list", "operationId": "get-breed", "tags": [ "Breed" ], "description": "Fetches a list containing [`Breed`](#breed)(s). (up to 10)", "parameters": [ { "name": "species_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, { "name": "active", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, { "name": "created_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, { "name": "modified_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "default": 10 } }, { "name": "page", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "default": 1 } } ], "responses": { "200": { "description": "A JSON object containing the breed list", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "breed": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "name": { "type": "string" }, "species_id": { "type": "string" } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-breed" ] } ] } }, "/v1/sex": { "get": { "summary": "Fetch a Sex list", "operationId": "get-sex", "tags": [ "Sex" ], "description": "Fetches a list containing [`Sex`](#sex)(es). (up to 10)", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "The ID number used by the system to uniquely identify a [`Sex`](#sex)." }, { "name": "active", "in": "query", "schema": { "type": "string" }, "description": "If **true**, the [`Sex`](#sex) is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`Sex`](#sex) was created." }, { "name": "modified_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`Sex`](#sex) was last modified." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`Sex`](#sex)." }, { "name": "abbreviation", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`Sex`](#sex)." }, { "name": "is_desexed", "in": "query", "schema": { "type": "boolean" }, "description": "If **true**, the [`Sex`](#sex) is spayed/neutered." }, { "name": "limit", "in": "query", "schema": { "type": "string", "default": 10 }, "description": "Limits the number of items returned." }, { "name": "page", "in": "query", "schema": { "type": "string", "default": 1 }, "description": "Specifies the page number of the result." } ], "responses": { "200": { "description": "A list of Sexes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "sex": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "is_desexed": { "type": "string" } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-sex" ] } ] } }, "/v1/species": { "get": { "summary": "Fetch a Species list", "operationId": "get-species", "tags": [ "Species" ], "description": "Fetches a list containing [`Species`](#species). (up to 10)", "parameters": [ { "name": "id", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The ID number used by the system to uniquely identify an [`Species`](#species)." }, { "name": "active", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "If **true**, the [`Species`](#species) is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The epoch time when the [`Species`](#species) was created." }, { "name": "modified_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The epoch time when the [`Species`](#species) was last modified." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`Species`](#species)." } ], "responses": { "200": { "description": "A list of species", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "species": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-species" ] } ] } }, "/v2/animal": { "get": { "summary": "Fetches a list containing Animal(s)", "operationId": "get-animalv2", "tags": [ "Animal V2" ], "parameters": [ { "name": "id", "in": "query", "description": "The ID number used by the system to uniquely identify an Animal.", "schema": { "type": "string" } }, { "name": "uid", "in": "query", "description": "The UID used by the system to uniquely identify an Animal.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If true, the Animal is active and usable in ezyVet.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "The epoch time when the Animal was created.", "schema": { "type": "string" } }, { "name": "modified_at", "in": "query", "description": "The epoch time when the Animal was last modified.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The custom code override for the Animal.", "schema": { "type": "string" } }, { "name": "sex_id", "in": "query", "description": "The ID of the Sex of the Animal.", "schema": { "type": "string" } }, { "name": "is_dead", "in": "query", "description": "If true, the Animal is dead.", "schema": { "type": "boolean" } }, { "name": "is_hostile", "in": "query", "description": "If true, the Animal is not friendly. This is marked by the 'FRIENDLY' or 'CARE' image on ezyVet's Animal screen.", "schema": { "type": "boolean" } }, { "name": "animalcolour_id", "in": "query", "description": "The ID of the AnimalColour.", "schema": { "type": "string" } }, { "name": "species_id", "in": "query", "description": "The ID of the Species of the Animal.", "schema": { "type": "string" } }, { "name": "breed_id", "in": "query", "description": "The ID of the Breed of the Animal.", "schema": { "type": "string" } }, { "name": "rabies_number", "in": "query", "description": "The rabies registration number of the Animal. This field is not necessarily used by clinics throughout the world.", "schema": { "type": "string" } }, { "name": "date_of_rabies_vaccination", "in": "query", "description": "The epoch time that the Animal was vaccinated against rabies. This field is not necessarily used by clinics throughout the world.", "schema": { "type": "string" } }, { "name": "microchip_number", "in": "query", "description": "The microchip number of the Animal.", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "description": "The ID of the owner of the Animal.", "schema": { "type": "string" } }, { "name": "date_of_birth", "in": "query", "description": "The epoch time the Animal was born.", "schema": { "type": "string" } }, { "name": "is_estimated_date_of_birth", "in": "query", "description": "If true, the date of birth is considered to be an estimate only.", "schema": { "type": "boolean" } }, { "name": "date_of_death", "in": "query", "description": "The epoch time the Animal died.", "schema": { "type": "string" } }, { "name": "death_reason", "in": "query", "description": "The reason of the Animal death.", "schema": { "type": "string" } }, { "name": "date_of_desex", "in": "query", "description": "The epoch time the Animal was spayed/neutered.", "schema": { "type": "string" } }, { "name": "referring_clinic_id", "in": "query", "description": "The Contact ID of the clinic that referred the Animal.", "schema": { "type": "string" } }, { "name": "referring_vet_id", "in": "query", "description": "The Contact ID of the vet that referred the Animal.", "schema": { "type": "string" } }, { "name": "residence_contact_id", "in": "query", "description": "The Contact ID for the caretaker of the Animal. Populated if and only if the animal does not stay at the same residence as the owner.", "schema": { "type": "string" } }, { "name": "weight_unit", "in": "query", "description": "The unit of weight that the Animal was measured with. This can be either Kilogram (kg), Pounds (lb) or Grams (g).", "schema": { "type": "string", "enum": [ "kg", "lb", "g" ] } }, { "name": "weight", "in": "query", "description": "The weight of the Animal.", "schema": { "type": "string" } }, { "name": "resuscitate", "in": "query", "description": "Whether the Animal's owner would like it to be resuscitated or not. This can be either No (0), Yes (1) or Advanced Life Support (3).", "schema": { "type": "number", "enum": [ 0, 1, 3 ] } }, { "name": "notes", "in": "query", "description": "Notes that are displayed within ezyVet on the animal page.", "schema": { "type": "string" } }, { "name": "notes_important", "in": "query", "description": "If true, the Animal's notes are marked as important.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of Animals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalListResponsev2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v2.1/animal": { "get": { "summary": "Fetches a list containing Animal(s) — v2 format with token pagination and UID fields.", "description": "A transitional endpoint for managing animal records, bridging the gap between the legacy v2 API and the new v4 API. v2.1 retains the v2 response structure (snake_case fields, `meta`/`items`/`messages` envelope) but introduces two key changes:\n\n1. **Token-based pagination** — replaces offset/limit with `page_size` and `next_token`. The legacy `limit` and `offset` parameters are rejected with a 400 error.\n2. **Dual ID fields** — each entity reference includes both the legacy integer `id` (e.g. `species_id`) and a new globally unique string `uid` (e.g. `species_uid`). This allows integrations to start mapping to UIDs in preparation for v4, where UIDs are the sole identifier.\n\nOnce your integration exclusively uses UIDs, migrating to v4 is straightforward.\n", "operationId": "get-animal-v2.1", "tags": [ "Animal V2" ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/active" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/modified_at" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/next_token" }, { "name": "name", "in": "query", "description": "The name of the Animal.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The custom code override for the Animal.", "schema": { "type": "string" } }, { "name": "is_dead", "in": "query", "description": "If true, the Animal is dead.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of Animals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalListResponsev2.1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v4/animal": { "get": { "summary": "Fetches a list containing Animal(s) - uses token pagination.", "operationId": "get-animal-v4", "tags": [ "Animal V4" ], "parameters": [ { "$ref": "#/components/parameters/AnimalV4-id" }, { "$ref": "#/components/parameters/AnimalV4-active" }, { "$ref": "#/components/parameters/AnimalV4-createdAt" }, { "$ref": "#/components/parameters/AnimalV4-updatedAt" }, { "$ref": "#/components/parameters/AnimalV4-pageSize" }, { "$ref": "#/components/parameters/AnimalV4-nextToken" }, { "name": "name", "in": "query", "description": "The name of the Animal.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The custom code override for the Animal.", "schema": { "type": "string" } }, { "name": "ownerId", "in": "query", "description": "The ID of the owner (contact) of the Animal.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by the status of the Animal.", "required": false, "schema": { "$ref": "#/components/schemas/AnimalV4-Status" } }, { "name": "isDead", "in": "query", "description": "Filter by death status. true = deceased animals only, false = alive animals only.", "required": false, "schema": { "$ref": "#/components/schemas/AnimalV4-IsDeadFilter" } } ], "description": "Retrieve a paginated list of animals using token-based pagination.\n\n**Pagination:**\n- Use the `pageSize` parameter to control the number of items returned per page (default: 2000, max: 2000)\n- Use the `nextToken` parameter from the response `meta` object to fetch the next page\n- The `nextToken` will be omitted from the `meta` object when there are no more pages available\n- Send `nextToken` on its own. The page size and the filters from the original request are carried inside the token, so repeating `pageSize` or any filter alongside it returns `400 RedundantParamsWithNextToken`\n", "responses": { "200": { "description": "A list of Animals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-AnimalListResponse" } } } }, "400": { "$ref": "#/components/responses/AnimalV4-BadRequest" }, "401": { "$ref": "#/components/responses/AnimalV4-Unauthorized" }, "404": { "$ref": "#/components/responses/AnimalV4-NotFound" }, "422": { "$ref": "#/components/responses/AnimalV4-UnprocessableEntity" }, "429": { "$ref": "#/components/responses/AnimalV4-TooManyRequests" }, "500": { "$ref": "#/components/responses/AnimalV4-InternalServerError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v4/animal/{id}": { "get": { "summary": "Fetches a single Animal by its ID (uid).", "operationId": "get-animal-by-id-v4", "tags": [ "Animal V4" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (uid) of the Animal.\n\n Maps to the UID field on other API versions", "schema": { "type": "string" }, "example": "animal_AB3e7Z2i9FJu0j7hLExLp" } ], "responses": { "200": { "description": "A single Animal. `data` holds the Animal object directly (not an array). There is no `meta` on single-item endpoints. `errors` is always present and is `[]` on success.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimalV4-AnimalResponse" } } } }, "400": { "$ref": "#/components/responses/AnimalV4-BadRequest" }, "401": { "$ref": "#/components/responses/AnimalV4-Unauthorized" }, "404": { "$ref": "#/components/responses/AnimalV4-NotFound" }, "422": { "$ref": "#/components/responses/AnimalV4-UnprocessableEntity" }, "429": { "$ref": "#/components/responses/AnimalV4-TooManyRequests" }, "500": { "$ref": "#/components/responses/AnimalV4-InternalServerError" } }, "security": [ { "bearerAuth": [ "read-animal" ] } ] } }, "/v4/breed": { "get": { "summary": "Fetches a list containing Breed(s) - uses token pagination.", "description": "Query parameter names are **case-sensitive** and must match the parameters documented below exactly. Any unsupported query parameter returns **400 Bad Request** with error code `UnrecognisedParameter`.\n\n**Continuation contract**: `nextToken` must be sent alone. Sending it alongside `pageSize` or any filter returns `400 CursorConflictsWithParams` — page size and the filter snapshot are carried inside the token.", "operationId": "get-breed-v4", "tags": [ "Breed" ], "parameters": [ { "$ref": "#/components/parameters/breed-id" }, { "$ref": "#/components/parameters/breed-legacyId" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/nextToken" }, { "name": "name", "in": "query", "description": "Filter by the name of the Breed.", "required": false, "schema": { "type": "string" }, "example": "Labrador" }, { "name": "speciesId", "in": "query", "description": "Filter by the UID of the Species this Breed belongs to.", "required": false, "schema": { "type": "string" }, "example": "species_Tm4hG7nJ1bP9sK3wL5xRq" }, { "name": "legacySpeciesId", "in": "query", "description": "Filter by the legacy integer identifier of the Species this Breed belongs to (passed as a string). Retained for backwards-compatibility with v1/v2 integrations.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "status", "in": "query", "description": "Filter breeds by active flag. Omitting this parameter defaults to `active` (inactive breeds are excluded). Use `all` to return both active and inactive breeds. This parameter is ignored for filter matching when `nextToken` is supplied; the cursor carries the original filter state.", "required": false, "schema": { "$ref": "#/components/schemas/BreedListStatusFilter" } } ], "responses": { "200": { "description": "A list of Breeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestv4" }, "401": { "$ref": "#/components/responses/Unauthorizedv4" }, "429": { "$ref": "#/components/responses/TooManyRequestsv4" }, "500": { "$ref": "#/components/responses/InternalErrorv4" } }, "security": [ { "bearerAuth": [ "read-breed" ] } ] } }, "/v4/species": { "get": { "summary": "Fetches a list containing Species - uses token pagination.", "description": "Query parameter names are **case-sensitive** and must match the parameters documented below exactly (for example `name`, not `Name`). Any unsupported query parameter returns **400 Bad Request** with error code `UnsupportedQueryParam`.\n\n**Continuation contract**: `nextToken` must be sent alone. Sending it alongside `pageSize` or any filter returns `400 RedundantParamsWithNextToken` — page size and the filter snapshot are carried inside the token.", "operationId": "get-species-v4", "tags": [ "Species" ], "parameters": [ { "$ref": "#/components/parameters/species-id" }, { "$ref": "#/components/parameters/species-legacyId" }, { "$ref": "#/components/parameters/species-status" }, { "$ref": "#/components/parameters/species-name" }, { "$ref": "#/components/parameters/species-updatedAt" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/nextToken" } ], "responses": { "200": { "description": "A list of Species", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeciesListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestv4" }, "401": { "$ref": "#/components/responses/Unauthorizedv4" }, "404": { "$ref": "#/components/responses/NotFoundv4" }, "422": { "$ref": "#/components/responses/UnprocessableEntityv4" }, "429": { "$ref": "#/components/responses/TooManyRequestsv4" }, "500": { "$ref": "#/components/responses/InternalErrorv4" } }, "security": [ { "bearerAuth": [ "read-species" ] } ] } }, "/v4/species/{id}": { "get": { "summary": "Fetches a single Species by its ID (uid).", "operationId": "get-species-by-id-v4", "tags": [ "Species" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (uid) of the Species.", "schema": { "type": "string" }, "example": "species_AB3e7Z2i9FJu0j7hLExLp" } ], "responses": { "200": { "description": "Success body is `{ \"data\": { ... }, \"errors\": [] }` — `data` is the Species object directly. `meta` is omitted (no pagination for a single resource); `errors` is always present on the wire and is `[]` on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeciesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestv4" }, "401": { "$ref": "#/components/responses/Unauthorizedv4" }, "404": { "$ref": "#/components/responses/NotFoundv4" }, "422": { "$ref": "#/components/responses/UnprocessableEntityv4" }, "429": { "$ref": "#/components/responses/TooManyRequestsv4" }, "500": { "$ref": "#/components/responses/InternalErrorv4" } }, "security": [ { "bearerAuth": [ "read-species" ] } ] } } } }