canonical: https://jentic.com/apis/swagger-api/swagger-petstore

# SmartBear Swagger Petstore - OpenAPI 3.0

Jentic publishes the agent-ready OpenAPI specification for the Swagger Petstore example API, the canonical reference implementation for OpenAPI 3.0. This sample Pet Store Server demonstrates REST API design patterns, authentication schemes, and data modeling best practices. Manage pet inventory with full CRUD operations, process store orders, and handle user accounts. Supports both OAuth 2.0 and API key authentication. Includes operations for finding pets by status or tags, uploading pet images, managing inventory, and placing orders. Widely used for API learning, tooling validation, and OpenAPI specification testing.

## For AI agents

Manage pet store inventory, process orders, and handle user accounts through the canonical OpenAPI 3.0 example API.

## Scope

Example/demo API only - not for production use. Does not persist data reliably, enforce real business logic, or provide SLA guarantees. Use for learning, testing, and demonstration purposes exclusively.

## Capabilities

- Create, read, update, and delete pets with name, category, photoUrls, tags, and status
- Find pets by status (available, pending, sold) or by tags with array filters
- Upload pet images with multipart form data
- Manage store inventory and retrieve available stock counts by status
- Place orders for pets with quantity, ship date, status, and completion tracking
- Retrieve order details by ID and delete orders
- Create user accounts with username, email, password, and phone
- User login and logout with session management
- Batch create users with array input
- Update and delete user profiles by username

## Use cases

### OpenAPI Learning and Tooling Validation

The Swagger Petstore is the canonical example for learning OpenAPI 3.0 specification structure, testing code generators, validating API documentation tools, and demonstrating REST API design patterns. It includes common patterns like resource CRUD, filtering by status or tags, file uploads, authentication flows, and error handling. Use this for teaching REST API development, testing OpenAPI-based SDKs, or validating API gateway configurations.

Example prompt: Use the Swagger Petstore API to demonstrate how to find pets by status, create a new pet with tags, upload a pet photo, and place an order through a REST API

### AI Agent API Integration Testing

AI agents use the Swagger Petstore through Jentic to test API integration workflows, validate tool-calling patterns, and develop agentic API interaction logic without impacting production systems. The agent searches Jentic for 'petstore API', receives the full operation schema with pet, store, and user resources, and executes test scenarios. Ideal for training agents on REST patterns, authentication handling, and error recovery before connecting to real-world APIs.

Example prompt: Search for available pets, create a new pet named 'Max' with status 'available' and tags ['friendly', 'trained'], upload a photo, then place an order for pet ID 123

### REST API Design Pattern Reference

Study common REST API design patterns including resource collections, query parameter filtering, path parameter identification, request body schemas, status-based filtering, pagination concepts, and authentication flows. The Petstore demonstrates how to model relationships (pet -> category, pet -> tags), handle file uploads, manage user sessions, and structure error responses with standard HTTP status codes.

Example prompt: Analyze the Petstore API structure to extract patterns for filtering (findByStatus, findByTags), resource identification (GET `/pet/{petId}`), and batch operations (POST `/user/createWithList`)

### Authentication Flow Demonstration

The Petstore supports both OAuth 2.0 (with implicit flow and scopes write:pets, read:pets) and API key authentication (via api_key header). Use this to learn how to implement multiple authentication schemes in a single API, scope-based authorization, session management with login/logout endpoints, and security scheme configuration in OpenAPI. Demonstrates how different operations require different auth levels.

Example prompt: Demonstrate both authentication methods: first authenticate with OAuth 2.0 to create a pet (write:pets scope), then use API key auth to retrieve pet details, and finally logout to terminate the session

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/pet/findByStatus` | Find pets by status (available, pending, sold) with comma-separated values |
| GET | `/pet/findByTags` | Find pets by tags with array query parameters |
| GET | `/pet/{petId}` | Retrieve a specific pet by ID |
| POST | `/pet` | Add a new pet to the store with name, category, photoUrls, tags, and status |
| PUT | `/pet` | Update an existing pet by ID |
| DELETE | `/pet/{petId}` | Delete a pet by ID |
| POST | `/pet/{petId}/uploadImage` | Upload a pet image with multipart form data |
| GET | `/store/inventory` | Get store inventory counts by status |
| POST | `/store/order` | Place an order for a pet |
| GET | `/store/order/{orderId}` | Retrieve order details by ID |
| POST | `/user` | Create a new user account |
| GET | `/user/login` | Log user into the system |
| GET | `/user/logout` | Log out current user session |

## Key resources

- **Pet** — Pet inventory items with id, name, category, photoUrls, tags, and status (available, pending, sold)
- **Order** — Store orders with id, petId, quantity, shipDate, status (placed, approved, delivered), and complete flag
- **User** — User accounts with id, username, firstName, lastName, email, password, phone, and userStatus
- **Category** — Pet categories with id and name used for organizing pet inventory
- **Tag** — Pet tags with id and name used for filtering and searching pets

## Why Jentic

- **Setup:** Wiring the Swagger Petstore by hand means standing up its OAuth2 implicit flow with the read:pets and write:pets scopes and its api_key header against the demo host yourself. Through Jentic you install once, import the Swagger Petstore from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Petstore puts the pet and order id in the URL path (`/pet/{petId}`, `/store/order/{orderId}`), so a rule can pin your agent to one pet or order. You choose the operations it may call, so a destructive one like deleting a pet is not included unless you add it.
- **Credential handling:** Your Petstore OAuth token or api_key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find pets by status' or 'place a store order', and Jentic returns the matching Petstore operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HTTPBin API** — HTTPBin tests HTTP request/response patterns while Petstore demonstrates REST resource modeling
- **FakeJSON API** — A mock-data API for generating realistic fake JSON responses, an alternative for prototyping and testing without a real backend.

## FAQ

### What is the Swagger Petstore API used for?

The Swagger Petstore is the canonical example API for the OpenAPI specification. It demonstrates REST API design patterns, authentication schemes, and resource modeling best practices. It's widely used for learning OpenAPI, testing code generators, validating API tooling, and teaching REST API development concepts. Not intended for production use - it's an educational reference implementation.

### What authentication does the Swagger Petstore API support?

Petstore supports two authentication schemes: OAuth 2.0 with implicit flow (scopes: write:pets, read:pets) for operations that modify data, and API key authentication via the api_key header for read operations. Through Jentic, credentials are stored encrypted and injected at execution time - agents never handle raw secrets or OAuth tokens.

### Can I use the Swagger Petstore API for production applications?

No. The Swagger Petstore is a sample/example API designed for learning, testing, and demonstration purposes only. It's not intended for production use. Use it to understand OpenAPI patterns, test API tooling, or train AI agents on REST API interactions before connecting to real-world production APIs.

### How do I filter pets by status in the Petstore API?

Use the GET `/pet/findByStatus` endpoint with the status query parameter set to 'available', 'pending', or 'sold'. Multiple status values can be provided as comma-separated strings. This demonstrates the standard REST pattern for filtering resource collections by an enumerated attribute.

### How do I test API integrations with the Swagger Petstore through Jentic?

Search Jentic for 'petstore API' or 'swagger example API', then load the operation schemas for pet, store, or user resources. Execute test scenarios like creating pets, placing orders, and managing users. Jentic handles authentication injection, so agents can focus on learning API interaction patterns. Install with pip install jentic run it through Jentic One, the self-hosted execution layer.

### What REST API patterns does the Petstore demonstrate?

The Petstore demonstrates: resource CRUD operations (POST, GET, PUT, DELETE), query parameter filtering (findByStatus, findByTags), path parameter identification (GET `/pet/{petId}`), file uploads (POST `/pet/{petId}/uploadImage`), batch operations (POST `/user/createWithList`), session management (login/logout), and standard HTTP status codes for error handling.

### Can I limit what my agent is allowed to do with the Swagger Petstore API?

Yes. Jentic One runs self-hosted, so your own rules decide which Petstore operations and credentials your agent may use. Because the API puts the pet and order identifiers in the URL path (`/pet/{petId}`, `/store/order/{orderId}`), a rule can pin your agent to a single pet or order rather than the whole catalogue. You also choose the exact operations it may call, so a destructive one like deleting a pet stays out of reach unless you add it.