Modern PetstoreAPI Docs
HomeGuides
Modern PetstoreAPIClassic PetstoreAPI
HomeGuides
Modern PetstoreAPIClassic PetstoreAPI
  1. Guides
  • Introduction
  • Quick Start Guide
  • API Protocols Guide
  • Protocol Guides
    • REST API
    • GraphQL
    • gRPC
    • Server-Sent Events (SSE)
    • WebSocket
    • Socket.IO
    • MQTT
    • Webhooks
    • MCP (Model Context Protocol)
  1. Guides

Quick Start Guide

Get started with the Modern Petstore API in minutes. This guide covers all available protocols and provides ready-to-use examples for the SaaS platform.

API Documentation#

Official Specifications#

OpenAPI 3.2 Spec (REST, SSE): JSON | YAML
AsyncAPI 3.0 Spec (WebSocket, Socket.IO, MQTT): JSON | YAML

Interactive Documentation#

Apidog UI (REST API): https://docs.petstoreapi.com/get-pet-25725398e0
Swagger UI (REST API): https://api.petstoreapi.com/v1/swagger-ui.html
AsyncAPI UI (Real-time APIs): https://api.petstoreapi.com/v1/asyncapi-ui.html

API Endpoints by Protocol#

REST API (HTTPS)#

Base URL: https://api.petstoreapi.com/v1

Server-Sent Events (SSE)#

Endpoint: https://api.petstoreapi.com/v1/chat/completions (with stream: true)

WebSocket#

Endpoint: wss://api.petstoreapi.com/v1/ws/chat

Socket.IO#

Endpoint: wss://api.petstoreapi.com

MQTT (IoT)#

Endpoint: mqtts://mqtt.petstoreapi.com:8883

Quick Examples#

1. REST API#

List Available Pets#

Get a Specific Pet#

Create a New Pet (Authenticated)#

Search Pets with Filters#

Advanced Search with QUERY Method#

Create an Order#


2. Server-Sent Events (SSE)#

AI Chat with Streaming Response#

JavaScript Example:
cURL Example:

3. WebSocket#

Customer Support Chat#

JavaScript Example:
Python Example:

4. Socket.IO#

Real-time Support Chat#

JavaScript Example:
Node.js Example:

5. MQTT (IoT Devices)#

Order Status Updates#

Python Example (paho-mqtt):
JavaScript Example (MQTT.js):

Authentication#

All authenticated endpoints require either OAuth 2.0 or Bearer Token (JWT) authentication.

Getting an Access Token#

Response:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshToken": "refresh_token_here",
  "user": {
    "id": "019b4137-6d8e-5c2b-e9f4-a3b5c8d7e2f1",
    "username": "your_username",
    "email": "user@example.com"
  }
}

Using the Token#

Include the token in the Authorization header:

Multi-Tenancy#

Isolate your data using the X-Tenant-ID header:
Important:
The tenant ID must be a valid UUID (v4 or v7)
Use the same tenant ID consistently for all related operations
Without a tenant ID, data is shared across all users

Rate Limits#

The API uses IETF standard rate limiting headers:
When you exceed the rate limit, you'll receive a 429 Too Many Requests response:
{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/v1/pets"
}

Error Handling#

All errors follow RFC 9457 Problem Details format:
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors",
  "instance": "/v1/pets",
  "errors": [
    {
      "field": "ageMonths",
      "message": "Must be a positive number",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "species",
      "message": "Must be one of: DOG, CAT, RABBIT, BIRD, REPTILE, OTHER",
      "code": "INVALID_ENUM_VALUE"
    }
  ]
}

Next Steps#

Explore the Full API: Visit the Swagger UI
Read the Specifications: Download the OpenAPI and AsyncAPI specs
Join the Community: Visit our GitHub repository
Get Support: Contact us at support@petstoreapi.com

Common Use Cases#

Browse Available Pets#

Get Pet Details#

Create an Adoption Application#

Chat with AI Pet Advisor#


Ready to build something amazing? Start exploring the Modern Petstore API today!
Modified at 2026-01-06 09:25:30
Previous
Introduction
Next
API Protocols Guide
Built with