Pets

Endpoints for listing, creating, and retrieving pets.

Authentication: These endpoints use an API key provided via the X-API-Key header. See Authentication.

Related schemas: `Pet`, `CreatePetRequest` (see Schemas).

List all pets

GET /pets

Returns a list of pets. Optionally limit the number of results.

Query parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of pets to return.

Request example

curl -sS \
  -H "X-API-Key: $API_KEY" \
  "https://api.example.com/pets?limit=10"

Responses

200 OK

A JSON array of `Pet`.

Response example

[
  {
    "id": "pet_123",
    "name": "Mochi",
    "tag": "cat"
  },
  {
    "id": "pet_456",
    "name": "Rex",
    "tag": "dog"
  }
]

500 Server error

The server encountered an unexpected condition.

Create a pet

POST /pets

Creates a new pet.

Request body

Content type: application/json

Schema: `CreatePetRequest`

Field	Type	Required	Description
`name`	string	Yes	Pet name.
`tag`	string	No	Optional category/tag (e.g., `dog`, `cat`).

Request example

curl -sS -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mochi","tag":"cat"}' \
  "https://api.example.com/pets"

Responses

201 Created

Returns the created `Pet`.

Response example

{
  "id": "pet_789",
  "name": "Mochi",
  "tag": "cat"
}

400 Bad request

The request body was invalid (for example, missing required fields like name). See Errors for troubleshooting guidance.

Get a pet by ID

GET /pets/{petId}

Retrieves a single pet by its unique identifier.

Path parameters

Name	In	Type	Required	Description
`petId`	path	string	Yes	The pet ID to retrieve.

Request example

curl -sS \
  -H "X-API-Key: $API_KEY" \
  "https://api.example.com/pets/pet_123"

Responses

200 OK

Returns a `Pet`.

Response example

{
  "id": "pet_123",
  "name": "Mochi",
  "tag": "cat"
}

404 Pet not found

No pet exists for the provided petId. See Errors for recommended handling.