Pet Profiles API Overview
This page collects the shared conventions, data objects, and validation rules for pet profiles. The complete request, complete response examples, and field descriptions for each endpoint are on the corresponding endpoint page.
Basics
Gateway base URL:
https://open-api.habitaxx.com/v1/ms-ai-fastRequest headers
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/jsonContent-Type is required only when a request body is present.
Unified JSON response
{
"code": 200,
"message": "success",
"data": {}
}| Field | Type | Description |
|---|---|---|
code | integer | 200 on success; on failure a business error code that matches the HTTP status. |
message | string | Status text: always "success" on success (normalised by the gateway) and a safe Chinese message on failure. Do not use it for program logic. |
data | any | Business data; the structure and content vary by endpoint. |
List endpoints do not return pagination metadata
List endpoints accept page and limit, but the response body only contains code, message and data — there is no page_info, total or total_pages. Count results on your side, or treat a page whose length equals limit as "there may be more".
Endpoint overview
| Endpoint | Method | Returns | Purpose |
|---|---|---|---|
/pets/pet-info | GET | Breed catalogue | Prerequisite: look up the standard breed library to obtain the breed_code used when creating or updating a profile. |
/pet-profiles | POST | A single profile | Create a pet profile. |
/pet-profiles | GET | data is an array of profiles | List profiles with pagination. |
/pet-profiles/{pet_profile_id} | GET | Profile + records | Retrieve a profile. |
/pet-profiles/{pet_profile_id} | PATCH | The updated profile | Partially update a profile. |
/pet-profiles/{pet_profile_id} | DELETE | {"id": 44} | Soft-delete a profile. |
Data object: PetProfile
| Field | Type | Writable | Description |
|---|---|---|---|
id | integer | No | Pet-profile ID, generated by the platform after creation. |
name | string | Yes | Pet name, required on creation, maximum 64 characters. |
avatar | string | null | Yes | Avatar URL, maximum 500 characters. |
birthday | string(date-time) | null | Yes | Date of birth. |
gender | integer | null | Yes | 1 male, 2 female, null unknown. |
pet_type | integer | null | Yes | 1 cat, 2 dog, 3 exotic pet, null unspecified. |
pet_variety | string | null | Yes | Breed text supplied by the caller, maximum 100 characters. |
breed_code | string | null | Yes | Standard breed code, maximum 64 characters; get values from Breed library lookup. |
weight | string | null | Yes | Weight as a string with a unit, such as "10.10kg", maximum 20 characters. |
is_neutered | integer | null | Yes | 0 not neutered, 1 neutered, null unknown. |
locale | string | No | Display language actually used for this response. |
breed_display_name | string | null | No | Standard breed display name returned according to locale. |
created_at / updated_at | string(date-time) | No | Creation and update time. |
records | object | No | Returned by the detail endpoint only: extension records grouped by record_type; {} when there are no records. |
Field validation rules
| Field | Rule |
|---|---|
name | Required (on creation), maximum 64 characters. |
gender | Only 1, 2, or null is allowed. |
pet_type | Only 1, 2, 3, or null is allowed. |
is_neutered | Only 0, 1, or null is allowed. |
breed_code | When non-empty it must exist in the platform standard breed library (see Breed library lookup); when pet_type is cat or dog the code prefix must match. |
weight | String; always include a unit (such as kg). |
birthday | ISO 8601 date-time string. Use null for an unknown value, not an empty string. |
Error handling
| HTTP status | Meaning | Caller action |
|---|---|---|
400 | A business rule is not satisfied, for example locale is not enabled or the breed does not match the type. | Read message and correct the input. |
401 / 403 | Token missing, invalid, or insufficient permission. | Exchange a new Token; do not pass internal identity fields. |
404 | The profile does not exist, was deleted, or does not belong to the current user. | Refresh local state; do not treat it as safe to retry. |
422 | A field type, length, or format does not match the schema. | Correct it per the field rules and retry. |
429 | Rate limit triggered. | Back off and retry. |
5xx | The service or a dependency is temporarily unavailable. | Reads may be retried; for write operations confirm the previous result first to avoid duplicate creation. |
Endpoints not covered in this round
The pet extension records (the /pet-profiles/{pet_profile_id}/records family) are not used in the current public flow, so they were not turned into endpoint pages in this round. Evaluate them separately when needed.