{ "openapi": "3.1.0", "info": { "title": "Mock API", "summary": "Full-featured mock REST API for testing, prototyping, and frontend development", "description": "## Overview\n\nZero-dependency, in-memory REST API with **11 interconnected resources**, authentication, webhooks, real-time events, and comprehensive query capabilities.\n\n## Features\n\n- **Full CRUD** on all resources with proper HTTP semantics\n- **Filtering** by any field with operators: `_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`\n- **Full-text search** via `?q=` across all fields\n- **Sorting**: `?_sort=field1,field2&_order=desc,asc`\n- **Pagination** with `Link` headers (page or slice-based)\n- **Relations**: `?_expand=user` (parent) and `?_embed=comments` (children)\n- **Field selection**: `?_fields=id,name,email`\n- **Authentication** with Bearer tokens (any password works)\n- **Webhooks** with event subscriptions and delivery history\n- **SSE streaming** for real-time events\n- **Batch operations** for multiple requests in one call\n- **Testing aids**: `?_error=500`, `?_delay=2000`, `/status/:code`, `/echo`\n- **ETag** conditional requests\n- **Rate limiting**: 120 req/60s per IP", "version": "2.0.1", "license": { "name": "MIT", "identifier": "MIT" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "externalDocs": { "description": "Interactive documentation", "url": "https://api.rodin.dev/mock/" }, "servers": [ { "url": "https://api.rodin.dev/mock", "description": "Production" }, { "url": "http://localhost:{port}", "description": "Local development", "variables": { "port": { "default": "3002", "description": "Server port", "enum": [ "3002", "3003", "3004" ] } } } ], "security": [ {}, { "bearerAuth": [] } ], "tags": [ { "name": "users", "description": "User accounts, profiles, authentication, and management. Each user has an address, company info, and role-based access.", "externalDocs": { "description": "Try users", "url": "https://api.rodin.dev/mock/users" } }, { "name": "posts", "description": "Blog posts and articles. Posts belong to users, can have comments, and support full-text search.", "externalDocs": { "description": "Try posts", "url": "https://api.rodin.dev/mock/posts" } }, { "name": "comments", "description": "Comments and discussions. Comments belong to both a post and a user.", "externalDocs": { "description": "Try comments", "url": "https://api.rodin.dev/mock/comments" } }, { "name": "todos", "description": "Task management and to-do tracking. Todos belong to users and support priority levels.", "externalDocs": { "description": "Try todos", "url": "https://api.rodin.dev/mock/todos" } }, { "name": "albums", "description": "Photo album collections. Albums belong to users and contain photos.", "externalDocs": { "description": "Try albums", "url": "https://api.rodin.dev/mock/albums" } }, { "name": "photos", "description": "Photos and image assets. Photos belong to albums.", "externalDocs": { "description": "Try photos", "url": "https://api.rodin.dev/mock/photos" } }, { "name": "categories", "description": "Product categorization and taxonomy. Categories contain products.", "externalDocs": { "description": "Try categories", "url": "https://api.rodin.dev/mock/categories" } }, { "name": "products", "description": "Product catalog with pricing, stock management, and image galleries. Products belong to categories.", "externalDocs": { "description": "Try products", "url": "https://api.rodin.dev/mock/products" } }, { "name": "orders", "description": "Order processing and fulfillment. Orders belong to users and contain product items.", "externalDocs": { "description": "Try orders", "url": "https://api.rodin.dev/mock/orders" } }, { "name": "reviews", "description": "Product reviews and ratings. Reviews belong to both a product and a user.", "externalDocs": { "description": "Try reviews", "url": "https://api.rodin.dev/mock/reviews" } }, { "name": "notifications", "description": "Notification management. Notifications belong to users.", "externalDocs": { "description": "Try notifications", "url": "https://api.rodin.dev/mock/notifications" } }, { "name": "webhooks", "description": "Event subscriptions. Register URLs to receive POST notifications on resource changes. Deliveries are simulated for safe testing.", "externalDocs": { "description": "Webhook management", "url": "https://api.rodin.dev/mock/webhooks" } }, { "name": "auth", "description": "Authentication and tokens. Mock — any password works. Tokens expire in 1 hour." }, { "name": "utils", "description": "Testing utilities: echo, delay, status codes, random data, SSE, batch, upload mock." }, { "name": "database", "description": "Database management: reset, re-seed, export, statistics." } ], "paths": { "/users": { "summary": "User collection", "get": { "operationId": "listUsers", "summary": "List all users", "tags": [ "users" ], "description": "Paginated list of users. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of users", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createUser", "summary": "Create user", "tags": [ "users" ], "description": "Create a new user. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `users.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" }, "examples": { "minimal": { "summary": "Minimal (required only)", "value": { "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com" } }, "full": { "summary": "Full profile", "value": { "firstName": "Alex", "lastName": "Morgan", "email": "alex.morgan@example.com", "username": "amorgan", "phone": "+1-555-123-4567", "role": "editor", "age": 32, "bio": "Full-stack dev. Caffeine-powered.", "isActive": true, "website": "https://morgan.dev" } }, "admin": { "summary": "Admin user", "value": { "firstName": "Sam", "lastName": "Admin", "email": "sam.admin@example.com", "role": "admin", "isActive": true } } } } } }, "responses": { "201": { "description": "User created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "links": { "GetUserById": { "$ref": "#/components/links/GetUserById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "users.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/users/{id}": { "summary": "Single user", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getUser", "summary": "Get user by ID", "tags": [ "users" ], "description": "Retrieve a single user. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The user", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceUser", "summary": "Replace user", "tags": [ "users" ], "description": "Full replacement. All mutable fields overwritten. Triggers `users.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" }, "examples": { "minimal": { "summary": "Minimal (required only)", "value": { "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com" } }, "full": { "summary": "Full profile", "value": { "firstName": "Alex", "lastName": "Morgan", "email": "alex.morgan@example.com", "username": "amorgan", "phone": "+1-555-123-4567", "role": "editor", "age": 32, "bio": "Full-stack dev. Caffeine-powered.", "isActive": true, "website": "https://morgan.dev" } }, "admin": { "summary": "Admin user", "value": { "firstName": "Sam", "lastName": "Admin", "email": "sam.admin@example.com", "role": "admin", "isActive": true } } } } } }, "responses": { "200": { "description": "User replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "users.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } }, "deprecated": true }, "patch": { "operationId": "updateUser", "summary": "Partially update user", "tags": [ "users" ], "description": "Partial update — only provided fields change. Triggers `users.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" }, "examples": { "deactivate": { "summary": "Deactivate account", "value": { "isActive": false } }, "promote": { "summary": "Promote to admin", "value": { "role": "admin" } }, "updateBio": { "summary": "Update bio", "value": { "bio": "Back to shipping." } } } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "users.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteUser", "summary": "Delete user", "tags": [ "users" ], "description": "Permanently remove a user. Returns deleted resource. Triggers `users.deleted` webhook.", "responses": { "200": { "description": "Deleted user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "users.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/posts": { "summary": "Post collection", "get": { "operationId": "listPosts", "summary": "List all posts", "tags": [ "posts" ], "description": "Paginated list of posts. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of posts", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createPost", "summary": "Create post", "tags": [ "posts" ], "description": "Create a new post. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `posts.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" }, "examples": { "draft": { "summary": "New draft", "value": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft" } }, "published": { "summary": "Published with metadata", "value": { "userId": 1, "title": "Shipping a mock API in 500 lines", "body": "Zero dependencies, full REST semantics…", "excerpt": "How to build a fake backend that teaches real habits.", "tags": [ "node", "api", "mock" ], "status": "published", "featured": true, "coverImage": "https://picsum.photos/1200/600?random=1", "readingTime": 7 } } } } } }, "responses": { "201": { "description": "Post created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } }, "links": { "GetPostById": { "$ref": "#/components/links/GetPostById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "posts.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/posts/{id}": { "summary": "Single post", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getPost", "summary": "Get post by ID", "tags": [ "posts" ], "description": "Retrieve a single post. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The post", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replacePost", "summary": "Replace post", "tags": [ "posts" ], "description": "Full replacement. All mutable fields overwritten. Triggers `posts.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" }, "examples": { "draft": { "summary": "New draft", "value": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft" } }, "published": { "summary": "Published with metadata", "value": { "userId": 1, "title": "Shipping a mock API in 500 lines", "body": "Zero dependencies, full REST semantics…", "excerpt": "How to build a fake backend that teaches real habits.", "tags": [ "node", "api", "mock" ], "status": "published", "featured": true, "coverImage": "https://picsum.photos/1200/600?random=1", "readingTime": 7 } } } } } }, "responses": { "200": { "description": "Post replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "posts.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } }, "deprecated": true }, "patch": { "operationId": "updatePost", "summary": "Partially update post", "tags": [ "posts" ], "description": "Partial update — only provided fields change. Triggers `posts.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" }, "examples": { "publish": { "summary": "Publish draft", "value": { "status": "published" } }, "feature": { "summary": "Feature it", "value": { "featured": true } }, "archive": { "summary": "Archive", "value": { "status": "archived" } } } } } }, "responses": { "200": { "description": "Post updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "posts.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete post", "tags": [ "posts" ], "description": "Permanently remove a post. Returns deleted resource. Triggers `posts.deleted` webhook.", "responses": { "200": { "description": "Deleted post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "posts.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/comments": { "summary": "Comment collection", "get": { "operationId": "listComments", "summary": "List all comments", "tags": [ "comments" ], "description": "Paginated list of comments. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of comments", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createComment", "summary": "Create comment", "tags": [ "comments" ], "description": "Create a new comment. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `comments.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentInput" }, "examples": { "basic": { "summary": "Plain comment", "value": { "postId": 1, "userId": 2, "body": "Great write-up — saved me an hour of debugging." } }, "reply": { "summary": "Reply with likes pre-set", "value": { "postId": 1, "userId": 3, "body": "Agreed. The `_like` operator alone is worth it.", "likes": 5 } } } } } }, "responses": { "201": { "description": "Comment created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } }, "links": { "GetCommentById": { "$ref": "#/components/links/GetCommentById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "comments.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/comments/{id}": { "summary": "Single comment", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getComment", "summary": "Get comment by ID", "tags": [ "comments" ], "description": "Retrieve a single comment. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The comment", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceComment", "summary": "Replace comment", "tags": [ "comments" ], "description": "Full replacement. All mutable fields overwritten. Triggers `comments.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentInput" }, "examples": { "basic": { "summary": "Plain comment", "value": { "postId": 1, "userId": 2, "body": "Great write-up — saved me an hour of debugging." } }, "reply": { "summary": "Reply with likes pre-set", "value": { "postId": 1, "userId": 3, "body": "Agreed. The `_like` operator alone is worth it.", "likes": 5 } } } } } }, "responses": { "200": { "description": "Comment replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "comments.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateComment", "summary": "Partially update comment", "tags": [ "comments" ], "description": "Partial update — only provided fields change. Triggers `comments.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentInput" }, "examples": { "edit": { "summary": "Edit body", "value": { "body": "Edited: actually the _like operator is the killer feature." } }, "upvote": { "summary": "Bump likes", "value": { "likes": 10 } } } } } }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "comments.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteComment", "summary": "Delete comment", "tags": [ "comments" ], "description": "Permanently remove a comment. Returns deleted resource. Triggers `comments.deleted` webhook.", "responses": { "200": { "description": "Deleted comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "comments.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/todos": { "summary": "Todo collection", "get": { "operationId": "listTodos", "summary": "List all todos", "tags": [ "todos" ], "description": "Paginated list of todos. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of todos", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Todo" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createTodo", "summary": "Create todo", "tags": [ "todos" ], "description": "Create a new todo. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `todos.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoInput" }, "examples": { "quick": { "summary": "Quick task", "value": { "userId": 1, "title": "Reply to launch-day emails" } }, "scheduled": { "summary": "Scheduled with priority", "value": { "userId": 1, "title": "Prepare Q3 roadmap deck", "priority": "high", "dueDate": "2026-07-01T17:00:00.000Z", "tags": [ "planning", "quarterly" ] } }, "done": { "summary": "Completed already", "value": { "userId": 1, "title": "Deploy v2.1.0", "priority": "medium", "completed": true } } } } } }, "responses": { "201": { "description": "Todo created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } }, "links": { "GetTodoById": { "$ref": "#/components/links/GetTodoById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "todos.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/todos/{id}": { "summary": "Single todo", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getTodo", "summary": "Get todo by ID", "tags": [ "todos" ], "description": "Retrieve a single todo. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The todo", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceTodo", "summary": "Replace todo", "tags": [ "todos" ], "description": "Full replacement. All mutable fields overwritten. Triggers `todos.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoInput" }, "examples": { "quick": { "summary": "Quick task", "value": { "userId": 1, "title": "Reply to launch-day emails" } }, "scheduled": { "summary": "Scheduled with priority", "value": { "userId": 1, "title": "Prepare Q3 roadmap deck", "priority": "high", "dueDate": "2026-07-01T17:00:00.000Z", "tags": [ "planning", "quarterly" ] } }, "done": { "summary": "Completed already", "value": { "userId": 1, "title": "Deploy v2.1.0", "priority": "medium", "completed": true } } } } } }, "responses": { "200": { "description": "Todo replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "todos.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateTodo", "summary": "Partially update todo", "tags": [ "todos" ], "description": "Partial update — only provided fields change. Triggers `todos.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoInput" }, "examples": { "complete": { "summary": "Mark done", "value": { "completed": true } }, "reprioritize": { "summary": "Bump priority", "value": { "priority": "critical" } }, "reschedule": { "summary": "Push due date", "value": { "dueDate": "2026-09-01T17:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Todo updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "todos.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteTodo", "summary": "Delete todo", "tags": [ "todos" ], "description": "Permanently remove a todo. Returns deleted resource. Triggers `todos.deleted` webhook.", "responses": { "200": { "description": "Deleted todo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "todos.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/albums": { "summary": "Album collection", "get": { "operationId": "listAlbums", "summary": "List all albums", "tags": [ "albums" ], "description": "Paginated list of albums. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of albums", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Album" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createAlbum", "summary": "Create album", "tags": [ "albums" ], "description": "Create a new album. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `albums.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumInput" }, "examples": { "basic": { "summary": "Simple album", "value": { "userId": 1, "title": "Summer 2026" } }, "rich": { "summary": "Rich album with cover", "value": { "userId": 1, "title": "Iceland road trip", "description": "Ten days chasing waterfalls and sheep.", "coverImage": "https://picsum.photos/800/600?random=42", "isPublic": true } } } } } }, "responses": { "201": { "description": "Album created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } }, "links": { "GetAlbumById": { "$ref": "#/components/links/GetAlbumById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "albums.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/albums/{id}": { "summary": "Single album", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getAlbum", "summary": "Get album by ID", "tags": [ "albums" ], "description": "Retrieve a single album. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The album", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceAlbum", "summary": "Replace album", "tags": [ "albums" ], "description": "Full replacement. All mutable fields overwritten. Triggers `albums.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumInput" }, "examples": { "basic": { "summary": "Simple album", "value": { "userId": 1, "title": "Summer 2026" } }, "rich": { "summary": "Rich album with cover", "value": { "userId": 1, "title": "Iceland road trip", "description": "Ten days chasing waterfalls and sheep.", "coverImage": "https://picsum.photos/800/600?random=42", "isPublic": true } } } } } }, "responses": { "200": { "description": "Album replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "albums.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateAlbum", "summary": "Partially update album", "tags": [ "albums" ], "description": "Partial update — only provided fields change. Triggers `albums.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumInput" }, "examples": { "makePrivate": { "summary": "Make private", "value": { "isPublic": false } }, "rename": { "summary": "Rename", "value": { "title": "Iceland 2026 — final cut" } } } } } }, "responses": { "200": { "description": "Album updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "albums.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteAlbum", "summary": "Delete album", "tags": [ "albums" ], "description": "Permanently remove a album. Returns deleted resource. Triggers `albums.deleted` webhook.", "responses": { "200": { "description": "Deleted album", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "albums.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/photos": { "summary": "Photo collection", "get": { "operationId": "listPhotos", "summary": "List all photos", "tags": [ "photos" ], "description": "Paginated list of photos. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of photos", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createPhoto", "summary": "Create photo", "tags": [ "photos" ], "description": "Create a new photo. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `photos.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoInput" }, "examples": { "single": { "summary": "One photo", "value": { "albumId": 1, "title": "Sunset at Vík", "url": "https://picsum.photos/1600/1067?random=1", "thumbnailUrl": "https://picsum.photos/150/150?random=1", "width": 1600, "height": 1067, "format": "jpeg", "size": 284532 } } } } } }, "responses": { "201": { "description": "Photo created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } }, "links": { "GetPhotoById": { "$ref": "#/components/links/GetPhotoById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "photos.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/photos/{id}": { "summary": "Single photo", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getPhoto", "summary": "Get photo by ID", "tags": [ "photos" ], "description": "Retrieve a single photo. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The photo", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replacePhoto", "summary": "Replace photo", "tags": [ "photos" ], "description": "Full replacement. All mutable fields overwritten. Triggers `photos.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoInput" }, "examples": { "single": { "summary": "One photo", "value": { "albumId": 1, "title": "Sunset at Vík", "url": "https://picsum.photos/1600/1067?random=1", "thumbnailUrl": "https://picsum.photos/150/150?random=1", "width": 1600, "height": 1067, "format": "jpeg", "size": 284532 } } } } } }, "responses": { "200": { "description": "Photo replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "photos.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updatePhoto", "summary": "Partially update photo", "tags": [ "photos" ], "description": "Partial update — only provided fields change. Triggers `photos.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoInput" }, "examples": { "retitle": { "summary": "Rename photo", "value": { "title": "Vík í Mýrdal — golden hour" } } } } } }, "responses": { "200": { "description": "Photo updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "photos.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deletePhoto", "summary": "Delete photo", "tags": [ "photos" ], "description": "Permanently remove a photo. Returns deleted resource. Triggers `photos.deleted` webhook.", "responses": { "200": { "description": "Deleted photo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "photos.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/categories": { "summary": "Category collection", "get": { "operationId": "listCategorys", "summary": "List all categories", "tags": [ "categories" ], "description": "Paginated list of categories. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of categories", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createCategory", "summary": "Create category", "tags": [ "categories" ], "description": "Create a new category. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `categories.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryInput" }, "examples": { "minimal": { "summary": "Minimal", "value": { "name": "Electronics", "slug": "electronics" } }, "full": { "summary": "With description and image", "value": { "name": "Outdoor gear", "slug": "outdoor-gear", "description": "Tents, packs, stoves, everything that holds up in the rain.", "image": "https://picsum.photos/800/400?random=7" } } } } } }, "responses": { "201": { "description": "Category created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } }, "links": { "GetCategoryById": { "$ref": "#/components/links/GetCategoryById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "categories.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/categories/{id}": { "summary": "Single category", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getCategory", "summary": "Get category by ID", "tags": [ "categories" ], "description": "Retrieve a single category. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The category", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceCategory", "summary": "Replace category", "tags": [ "categories" ], "description": "Full replacement. All mutable fields overwritten. Triggers `categories.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryInput" }, "examples": { "minimal": { "summary": "Minimal", "value": { "name": "Electronics", "slug": "electronics" } }, "full": { "summary": "With description and image", "value": { "name": "Outdoor gear", "slug": "outdoor-gear", "description": "Tents, packs, stoves, everything that holds up in the rain.", "image": "https://picsum.photos/800/400?random=7" } } } } } }, "responses": { "200": { "description": "Category replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "categories.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateCategory", "summary": "Partially update category", "tags": [ "categories" ], "description": "Partial update — only provided fields change. Triggers `categories.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryInput" }, "examples": { "rename": { "summary": "Rename category", "value": { "name": "Consumer electronics" } }, "rebrand": { "summary": "Update image", "value": { "image": "https://picsum.photos/800/400?random=17" } } } } } }, "responses": { "200": { "description": "Category updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "categories.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteCategory", "summary": "Delete category", "tags": [ "categories" ], "description": "Permanently remove a category. Returns deleted resource. Triggers `categories.deleted` webhook.", "responses": { "200": { "description": "Deleted category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "categories.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/products": { "summary": "Product collection", "get": { "operationId": "listProducts", "summary": "List all products", "tags": [ "products" ], "description": "Paginated list of products. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of products", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createProduct", "summary": "Create product", "tags": [ "products" ], "description": "Create a new product. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `products.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" }, "examples": { "minimal": { "summary": "Minimal product", "value": { "categoryId": 1, "name": "Wireless earbuds", "price": 79.99, "sku": "SKU-01001", "stock": 100 } }, "sale": { "summary": "On sale, featured", "value": { "categoryId": 1, "name": "Ultra-light backpack", "description": "28 L, waterproof, 650 g.", "price": 89, "originalPrice": 120, "currency": "USD", "sku": "SKU-02042", "stock": 40, "rating": 4.8, "reviewCount": 312, "isFeatured": true, "tags": [ "backpack", "outdoor", "sale" ] } } } } } }, "responses": { "201": { "description": "Product created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "links": { "GetProductById": { "$ref": "#/components/links/GetProductById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "products.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/products/{id}": { "summary": "Single product", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getProduct", "summary": "Get product by ID", "tags": [ "products" ], "description": "Retrieve a single product. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The product", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceProduct", "summary": "Replace product", "tags": [ "products" ], "description": "Full replacement. All mutable fields overwritten. Triggers `products.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" }, "examples": { "minimal": { "summary": "Minimal product", "value": { "categoryId": 1, "name": "Wireless earbuds", "price": 79.99, "sku": "SKU-01001", "stock": 100 } }, "sale": { "summary": "On sale, featured", "value": { "categoryId": 1, "name": "Ultra-light backpack", "description": "28 L, waterproof, 650 g.", "price": 89, "originalPrice": 120, "currency": "USD", "sku": "SKU-02042", "stock": 40, "rating": 4.8, "reviewCount": 312, "isFeatured": true, "tags": [ "backpack", "outdoor", "sale" ] } } } } } }, "responses": { "200": { "description": "Product replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "products.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateProduct", "summary": "Partially update product", "tags": [ "products" ], "description": "Partial update — only provided fields change. Triggers `products.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" }, "examples": { "markdown": { "summary": "Drop the price", "value": { "price": 59.99 } }, "restock": { "summary": "Restock inventory", "value": { "stock": 500 } }, "feature": { "summary": "Feature product", "value": { "isFeatured": true } } } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "products.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteProduct", "summary": "Delete product", "tags": [ "products" ], "description": "Permanently remove a product. Returns deleted resource. Triggers `products.deleted` webhook.", "responses": { "200": { "description": "Deleted product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "products.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/orders": { "summary": "Order collection", "get": { "operationId": "listOrders", "summary": "List all orders", "tags": [ "orders" ], "description": "Paginated list of orders. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of orders", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createOrder", "summary": "Create order", "tags": [ "orders" ], "description": "Create a new order. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `orders.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" }, "examples": { "twoItems": { "summary": "Two-item order", "value": { "userId": 1, "items": [ { "productId": 1, "quantity": 2, "price": 79.99 }, { "productId": 2, "quantity": 1, "price": 89 } ], "subtotal": 248.98, "tax": 19.92, "shipping": 0, "total": 268.9, "currency": "USD", "paymentMethod": "credit_card", "shippingAddress": { "street": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701", "country": "US" } } } } } } }, "responses": { "201": { "description": "Order created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "links": { "GetOrderById": { "$ref": "#/components/links/GetOrderById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "orders.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/orders/{id}": { "summary": "Single order", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getOrder", "summary": "Get order by ID", "tags": [ "orders" ], "description": "Retrieve a single order. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The order", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceOrder", "summary": "Replace order", "tags": [ "orders" ], "description": "Full replacement. All mutable fields overwritten. Triggers `orders.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" }, "examples": { "twoItems": { "summary": "Two-item order", "value": { "userId": 1, "items": [ { "productId": 1, "quantity": 2, "price": 79.99 }, { "productId": 2, "quantity": 1, "price": 89 } ], "subtotal": 248.98, "tax": 19.92, "shipping": 0, "total": 268.9, "currency": "USD", "paymentMethod": "credit_card", "shippingAddress": { "street": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701", "country": "US" } } } } } } }, "responses": { "200": { "description": "Order replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "orders.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateOrder", "summary": "Partially update order", "tags": [ "orders" ], "description": "Partial update — only provided fields change. Triggers `orders.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" }, "examples": { "ship": { "summary": "Mark shipped", "value": { "status": "shipped", "trackingNumber": "1Z999AA10123456784" } }, "deliver": { "summary": "Mark delivered", "value": { "status": "delivered" } }, "cancel": { "summary": "Cancel order", "value": { "status": "cancelled" } } } } } }, "responses": { "200": { "description": "Order updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "orders.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteOrder", "summary": "Delete order", "tags": [ "orders" ], "description": "Permanently remove a order. Returns deleted resource. Triggers `orders.deleted` webhook.", "responses": { "200": { "description": "Deleted order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "orders.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/reviews": { "summary": "Review collection", "get": { "operationId": "listReviews", "summary": "List all reviews", "tags": [ "reviews" ], "description": "Paginated list of reviews. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of reviews", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Review" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createReview", "summary": "Create review", "tags": [ "reviews" ], "description": "Create a new review. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `reviews.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInput" }, "examples": { "positive": { "summary": "Five-star review", "value": { "productId": 1, "userId": 1, "rating": 5, "title": "Better than I expected", "body": "Quality is on par with gear twice the price. Would buy again.", "isVerified": true, "helpful": 12 } }, "critical": { "summary": "Two-star review", "value": { "productId": 1, "userId": 2, "rating": 2, "title": "Nice idea, weak execution", "body": "Stitching frayed after two weeks. Returning.", "isVerified": true, "helpful": 3 } } } } } }, "responses": { "201": { "description": "Review created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } }, "links": { "GetReviewById": { "$ref": "#/components/links/GetReviewById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "reviews.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/reviews/{id}": { "summary": "Single review", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getReview", "summary": "Get review by ID", "tags": [ "reviews" ], "description": "Retrieve a single review. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The review", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceReview", "summary": "Replace review", "tags": [ "reviews" ], "description": "Full replacement. All mutable fields overwritten. Triggers `reviews.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInput" }, "examples": { "positive": { "summary": "Five-star review", "value": { "productId": 1, "userId": 1, "rating": 5, "title": "Better than I expected", "body": "Quality is on par with gear twice the price. Would buy again.", "isVerified": true, "helpful": 12 } }, "critical": { "summary": "Two-star review", "value": { "productId": 1, "userId": 2, "rating": 2, "title": "Nice idea, weak execution", "body": "Stitching frayed after two weeks. Returning.", "isVerified": true, "helpful": 3 } } } } } }, "responses": { "200": { "description": "Review replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "reviews.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateReview", "summary": "Partially update review", "tags": [ "reviews" ], "description": "Partial update — only provided fields change. Triggers `reviews.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInput" }, "examples": { "upvote": { "summary": "Mark more helpful", "value": { "helpful": 42 } }, "verify": { "summary": "Mark verified", "value": { "isVerified": true } } } } } }, "responses": { "200": { "description": "Review updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "reviews.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteReview", "summary": "Delete review", "tags": [ "reviews" ], "description": "Permanently remove a review. Returns deleted resource. Triggers `reviews.deleted` webhook.", "responses": { "200": { "description": "Deleted review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "reviews.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/notifications": { "summary": "Notification collection", "get": { "operationId": "listNotifications", "summary": "List all notifications", "tags": [ "notifications" ], "description": "Paginated list of notifications. Supports filtering, range operators (`_gte`, `_lte`, `_gt`, `_lt`, `_ne`, `_like`), full-text search, sorting, field selection, and relation expansion.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Paginated array of notifications", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" }, "X-Page": { "$ref": "#/components/headers/X-Page" }, "X-Per-Page": { "$ref": "#/components/headers/X-Per-Page" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" }, "maxItems": 100 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createNotification", "summary": "Create notification", "tags": [ "notifications" ], "description": "Create a new notification. Fields `id`, `createdAt`, `updatedAt` are auto-generated. Triggers `notifications.created` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationInput" }, "examples": { "info": { "summary": "Info notification", "value": { "userId": 1, "type": "info", "title": "New feature available", "message": "Batch operations are now live — run up to 20 writes in one call.", "link": "/guide/batch" } }, "success": { "summary": "Success notification", "value": { "userId": 1, "type": "success", "title": "Payment received", "message": "Your order #4217 is confirmed.", "link": "/orders/4217" } }, "error": { "summary": "Error notification", "value": { "userId": 1, "type": "error", "title": "Deploy failed", "message": "CI failed on step: build. Click to view logs.", "link": "https://ci.example.com/runs/982" } } } } } }, "responses": { "201": { "description": "Notification created", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } }, "links": { "GetNotificationById": { "$ref": "#/components/links/GetNotificationById" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "notifications.created webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/notifications/{id}": { "summary": "Single notification", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getNotification", "summary": "Get notification by ID", "tags": [ "notifications" ], "description": "Retrieve a single notification. Supports ETag conditional requests via `If-None-Match`.", "parameters": [ { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" } ], "responses": { "200": { "description": "The notification", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "304": { "description": "Not Modified (ETag matched)" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceNotification", "summary": "Replace notification", "tags": [ "notifications" ], "description": "Full replacement. All mutable fields overwritten. Triggers `notifications.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationInput" }, "examples": { "info": { "summary": "Info notification", "value": { "userId": 1, "type": "info", "title": "New feature available", "message": "Batch operations are now live — run up to 20 writes in one call.", "link": "/guide/batch" } }, "success": { "summary": "Success notification", "value": { "userId": 1, "type": "success", "title": "Payment received", "message": "Your order #4217 is confirmed.", "link": "/orders/4217" } }, "error": { "summary": "Error notification", "value": { "userId": 1, "type": "error", "title": "Deploy failed", "message": "CI failed on step: build. Click to view logs.", "link": "https://ci.example.com/runs/982" } } } } } }, "responses": { "200": { "description": "Notification replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "notifications.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "patch": { "operationId": "updateNotification", "summary": "Partially update notification", "tags": [ "notifications" ], "description": "Partial update — only provided fields change. Triggers `notifications.updated` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationInput" }, "examples": { "markRead": { "summary": "Mark as read", "value": { "read": true } }, "retitle": { "summary": "Update title", "value": { "title": "Action required" } } } } } }, "responses": { "200": { "description": "Notification updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "notifications.updated webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } }, "delete": { "operationId": "deleteNotification", "summary": "Delete notification", "tags": [ "notifications" ], "description": "Permanently remove a notification. Returns deleted resource. Triggers `notifications.deleted` webhook.", "responses": { "200": { "description": "Deleted notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "callbacks": { "onEvent": { "{$request.body#/callbackUrl}": { "post": { "summary": "notifications.deleted webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "410": { "description": "Endpoint gone" }, "2XX": { "description": "Webhook accepted" } } } } } } } }, "/users/{id}/posts": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserPosts", "summary": "List user's posts", "tags": [ "users", "posts" ], "description": "Retrieve user's posts. Same filtering, sorting, and pagination as `/posts`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of posts", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/comments": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserComments", "summary": "List user's comments", "tags": [ "users", "comments" ], "description": "Retrieve user's comments. Same filtering, sorting, and pagination as `/comments`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of comments", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/todos": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserTodos", "summary": "List user's tasks", "tags": [ "users", "todos" ], "description": "Retrieve user's tasks. Same filtering, sorting, and pagination as `/todos`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of todos", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Todo" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/albums": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserAlbums", "summary": "List user's albums", "tags": [ "users", "albums" ], "description": "Retrieve user's albums. Same filtering, sorting, and pagination as `/albums`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of albums", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Album" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/orders": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserOrders", "summary": "List user's orders", "tags": [ "users", "orders" ], "description": "Retrieve user's orders. Same filtering, sorting, and pagination as `/orders`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of orders", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/reviews": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserReviews", "summary": "List user's reviews", "tags": [ "users", "reviews" ], "description": "Retrieve user's reviews. Same filtering, sorting, and pagination as `/reviews`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of reviews", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/{id}/notifications": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listUserNotifications", "summary": "List user's notifications", "tags": [ "users", "notifications" ], "description": "Retrieve user's notifications. Same filtering, sorting, and pagination as `/notifications`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of notifications", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/posts/{id}/comments": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listPostComments", "summary": "List post's comments", "tags": [ "posts", "comments" ], "description": "Retrieve post's comments. Same filtering, sorting, and pagination as `/comments`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of comments", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/albums/{id}/photos": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listAlbumPhotos", "summary": "List album's photos", "tags": [ "albums", "photos" ], "description": "Retrieve album's photos. Same filtering, sorting, and pagination as `/photos`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of photos", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/categories/{id}/products": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listCategoryProducts", "summary": "List category's products", "tags": [ "categories", "products" ], "description": "Retrieve category's products. Same filtering, sorting, and pagination as `/products`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of products", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products/{id}/reviews": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listProductReviews", "summary": "List product's reviews", "tags": [ "products", "reviews" ], "description": "Retrieve product's reviews. Same filtering, sorting, and pagination as `/reviews`.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/SortParam" }, { "$ref": "#/components/parameters/OrderParam" }, { "$ref": "#/components/parameters/SearchParam" }, { "$ref": "#/components/parameters/FieldsParam" }, { "$ref": "#/components/parameters/ExpandParam" }, { "$ref": "#/components/parameters/EmbedParam" }, { "$ref": "#/components/parameters/DelayParam" }, { "$ref": "#/components/parameters/ErrorParam" } ], "responses": { "200": { "description": "Array of reviews", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/auth/register": { "post": { "operationId": "register", "summary": "Register new user", "tags": [ "auth" ], "description": "Create account and receive token. Returns 409 if email exists.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCredentials" }, "examples": { "basic": { "summary": "Minimal signup", "value": { "email": "new.user@example.com", "password": "correcthorsebatterystaple", "firstName": "New", "lastName": "User" } }, "withUsername": { "summary": "With username", "value": { "email": "new.user@example.com", "password": "correcthorsebatterystaple", "firstName": "New", "lastName": "User", "username": "newuser" } } } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [] } }, "/auth/login": { "post": { "operationId": "login", "summary": "Log in", "tags": [ "auth" ], "description": "Authenticate with email/password. **Mock: any password works for any seeded email.** The demo account `demo@example.com` is always present and carries admin role — use it for docs Try-It. Token valid 1 hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCredentials" }, "example": { "email": "demo@example.com", "password": "any" } } } }, "responses": { "200": { "description": "Logged in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [] } }, "/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Refresh token", "tags": [ "auth" ], "description": "Exchange valid token for new one. Old token revoked.", "responses": { "200": { "description": "New token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/me": { "get": { "operationId": "getCurrentUser", "summary": "Get current user", "tags": [ "auth" ], "description": "Returns profile for the provided Bearer token.", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/logout": { "post": { "operationId": "logout", "summary": "Log out", "tags": [ "auth" ], "description": "Revoke the Bearer token.", "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Logged out" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/basic-demo": { "get": { "operationId": "basicAuthDemo", "summary": "HTTP Basic demo", "tags": [ "auth" ], "description": "Demonstrates HTTP Basic — intentionally present so API docs generators can render the Basic auth block. Any credentials accepted. Echoes the username back so you can confirm the header reached the server.", "responses": { "200": { "description": "Authenticated with Basic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicDemoResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "basicAuth": [] } ] } }, "/webhooks": { "summary": "Webhook subscriptions", "get": { "operationId": "listWebhooks", "summary": "List webhooks", "tags": [ "webhooks" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Webhook list", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "post": { "operationId": "createWebhook", "summary": "Register webhook", "tags": [ "webhooks" ], "description": "Subscribe URL to events. Patterns: `*` (all), `users.*`, `*.created`, `users.created`. Deliveries are simulated (logged, not sent).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "examples": { "all": { "summary": "All events", "value": { "url": "https://example.com/wh", "events": [ "*" ] } }, "specific": { "summary": "Specific events", "value": { "url": "https://example.com/wh", "events": [ "users.created", "orders.*" ], "secret": "whsec_abc" } } } } } }, "responses": { "201": { "description": "Registered", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "links": { "GetWebhookById": { "$ref": "#/components/links/GetWebhookById" }, "GetWebhookDeliveries": { "$ref": "#/components/links/GetWebhookDeliveries" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/webhooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "getWebhook", "summary": "Get webhook", "tags": [ "webhooks" ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateWebhook", "summary": "Update webhook", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "examples": { "pause": { "summary": "Pause deliveries", "value": { "isActive": false } }, "retarget": { "summary": "Change target URL", "value": { "url": "https://new.example.com/hooks/mock" } }, "resubscribe": { "summary": "Narrow events", "value": { "events": [ "orders.created", "orders.updated" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete webhook", "tags": [ "webhooks" ], "description": "Remove webhook and all delivery records.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "operationId": "listWebhookDeliveries", "summary": "Delivery history", "tags": [ "webhooks" ], "description": "Delivery log for a webhook — event, payload, simulated response, timing.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Deliveries", "headers": { "X-Total-Count": { "$ref": "#/components/headers/X-Total-Count" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{id}/test": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "operationId": "testWebhook", "summary": "Send test event", "tags": [ "webhooks" ], "description": "Trigger simulated `webhook.test` event.", "responses": { "200": { "description": "Test delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "tags": [ "utils" ], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheck" } } } } }, "security": [] } }, "/echo": { "get": { "operationId": "echo", "summary": "Echo request", "tags": [ "utils" ], "description": "Mirror request back as JSON.", "responses": { "200": { "description": "Request mirror", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EchoResponse" } } } } }, "security": [] }, "post": { "operationId": "echoPost", "summary": "Echo POST", "tags": [ "utils" ], "description": "Mirror the request body, query, and headers back — handy when you want to see exactly what your client is sending.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ping": "pong", "nested": { "works": true }, "array": [ 1, 2, 3 ] } } } }, "responses": { "200": { "description": "Request mirror", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EchoResponse" } } } } }, "security": [] } }, "/status/{code}": { "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 100, "maximum": 599 }, "example": 418 } ], "get": { "operationId": "getStatus", "summary": "Return HTTP status code", "tags": [ "utils" ], "description": "Test error handling with any status code.", "responses": { "200": { "description": "Status response" }, "204": { "description": "No Content" }, "4XX": { "description": "Client error" }, "5XX": { "description": "Server error" } }, "security": [] } }, "/delay/{ms}": { "parameters": [ { "name": "ms", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 10000 }, "example": 2000 } ], "get": { "operationId": "delay", "summary": "Delayed response", "tags": [ "utils" ], "description": "Wait N ms before responding. Test timeouts and loading states.", "responses": { "200": { "description": "Delayed response", "content": { "application/json": { "schema": { "type": "object", "properties": { "delayed": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } }, "security": [] } }, "/random/uuid": { "get": { "operationId": "randomUuid", "summary": "Random UUID(s)", "tags": [ "utils" ], "parameters": [ { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } } ], "responses": { "200": { "description": "UUID(s)", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, { "type": "object", "properties": { "uuids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } ] } } } } }, "security": [] } }, "/random/number": { "get": { "operationId": "randomNumber", "summary": "Random number(s)", "tags": [ "utils" ], "parameters": [ { "name": "min", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "max", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } } ], "responses": { "200": { "description": "Number(s)" } }, "security": [] } }, "/random/text": { "get": { "operationId": "randomText", "summary": "Lorem Ipsum", "tags": [ "utils" ], "parameters": [ { "name": "paragraphs", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 } } ], "responses": { "200": { "description": "Generated text" } }, "security": [] } }, "/upload": { "post": { "operationId": "mockUpload", "summary": "Mock file upload", "tags": [ "utils" ], "description": "Simulates upload — no actual file storage. Accepts raw binary, multipart form, or JSON with a filename hint. Returns a fake CDN URL so your frontend can wire the full happy path without real object storage.", "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" } } }, "example": { "filename": "document.pdf" } } } }, "responses": { "201": { "description": "Upload response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } } }, "security": [] } }, "/stream": { "get": { "operationId": "eventStream", "summary": "SSE event stream", "tags": [ "utils" ], "description": "Server-Sent Events — 1 event/sec, max 50. Test real-time UI and EventSource.", "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } } }, "security": [] } }, "/batch": { "post": { "operationId": "batchOperations", "summary": "Batch operations", "tags": [ "utils" ], "description": "Up to 20 operations in one request, executed sequentially.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchOperation" }, "minItems": 1, "maxItems": 20 }, "example": [ { "method": "GET", "url": "/users/1" }, { "method": "GET", "url": "/users/1/posts" } ] } } }, "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResult" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [] } }, "/db/reset": { "post": { "operationId": "resetDatabase", "summary": "Reset database", "tags": [ "database" ], "description": "Regenerate all data, clear tokens/webhooks/deliveries.", "responses": { "200": { "description": "Reset complete" } }, "security": [] } }, "/db/stats": { "get": { "operationId": "getDatabaseStats", "summary": "Database stats", "tags": [ "database" ], "responses": { "200": { "description": "Statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbStats" } } } } }, "security": [] } }, "/db/seed": { "post": { "operationId": "seedDatabase", "summary": "Re-seed database", "tags": [ "database" ], "description": "Regenerate with custom counts.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedRequest" }, "example": { "users": 100, "posts": 500 } } } }, "responses": { "200": { "description": "Re-seeded" } }, "security": [] } }, "/db/export": { "get": { "operationId": "exportDatabase", "summary": "Export database", "tags": [ "database" ], "description": "Full database as JSON. May be large.", "responses": { "200": { "description": "Full dump", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } } } } } } }, "security": [] } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "OpenAPI spec", "tags": [ "database" ], "responses": { "200": { "description": "This specification" } }, "security": [] } }, "/admin/report": { "get": { "operationId": "getAdminReport", "summary": "Admin aggregate report", "tags": [ "database" ], "description": "Read-only snapshot of record counts, active webhooks, and token count. Accepts either Bearer or Basic — the auth block in docs should show both alternatives.", "responses": { "200": { "description": "Report payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ] } } }, "webhooks": { "users.created": { "post": { "summary": "User created", "description": "Fired when a user is created.", "operationId": "onWebhook_users_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "users.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "users", "resourceId": 1, "data": { "id": 1, "firstName": "Demo", "lastName": "User", "email": "demo@example.com", "username": "demo", "avatar": "https://i.pravatar.cc/150?u=demo", "phone": "+1-555-000-0001", "address": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } }, "company": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." }, "website": "https://example.com/demo", "role": "admin", "age": 30, "bio": "Seeded demo account. Log in with any password.", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2026-04-21T00:00:00.000Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "users.updated": { "post": { "summary": "User updated", "description": "Fired when a user is updated.", "operationId": "onWebhook_users_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "users.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "users", "resourceId": 1, "data": { "id": 1, "firstName": "Demo", "lastName": "User", "email": "demo@example.com", "username": "demo", "avatar": "https://i.pravatar.cc/150?u=demo", "phone": "+1-555-000-0001", "address": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } }, "company": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." }, "website": "https://example.com/demo", "role": "admin", "age": 30, "bio": "Seeded demo account. Log in with any password.", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2026-04-21T00:00:00.000Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "users.deleted": { "post": { "summary": "User deleted", "description": "Fired when a user is deleted.", "operationId": "onWebhook_users_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "users.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "users", "resourceId": 1, "data": { "id": 1, "firstName": "Demo", "lastName": "User", "email": "demo@example.com", "username": "demo", "avatar": "https://i.pravatar.cc/150?u=demo", "phone": "+1-555-000-0001", "address": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } }, "company": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." }, "website": "https://example.com/demo", "role": "admin", "age": 30, "bio": "Seeded demo account. Log in with any password.", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2026-04-21T00:00:00.000Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "posts.created": { "post": { "summary": "Post created", "description": "Fired when a post is created.", "operationId": "onWebhook_posts_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "posts.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "posts", "resourceId": 1, "data": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft", "id": 1, "createdAt": "2026-01-21T19:36:04.116Z", "updatedAt": "2026-05-01T05:55:47.527Z", "deletedAt": "2026-05-01T05:55:47.527Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "posts.updated": { "post": { "summary": "Post updated", "description": "Fired when a post is updated.", "operationId": "onWebhook_posts_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "posts.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "posts", "resourceId": 1, "data": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft", "id": 1, "createdAt": "2026-01-21T19:36:04.116Z", "updatedAt": "2026-05-01T05:55:47.527Z", "deletedAt": "2026-05-01T05:55:47.527Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "posts.deleted": { "post": { "summary": "Post deleted", "description": "Fired when a post is deleted.", "operationId": "onWebhook_posts_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "posts.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "posts", "resourceId": 1, "data": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft", "id": 1, "createdAt": "2026-01-21T19:36:04.116Z", "updatedAt": "2026-05-01T05:55:47.527Z", "deletedAt": "2026-05-01T05:55:47.527Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "comments.created": { "post": { "summary": "Comment created", "description": "Fired when a comment is created.", "operationId": "onWebhook_comments_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "comments.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "comments", "resourceId": 1, "data": { "id": 1, "postId": 1, "userId": 1, "body": "How does this compare to the approach described in the official docs?", "likes": 16, "createdAt": "2023-04-28T06:59:47.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "comments.updated": { "post": { "summary": "Comment updated", "description": "Fired when a comment is updated.", "operationId": "onWebhook_comments_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "comments.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "comments", "resourceId": 1, "data": { "id": 1, "postId": 1, "userId": 1, "body": "How does this compare to the approach described in the official docs?", "likes": 16, "createdAt": "2023-04-28T06:59:47.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "comments.deleted": { "post": { "summary": "Comment deleted", "description": "Fired when a comment is deleted.", "operationId": "onWebhook_comments_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "comments.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "comments", "resourceId": 1, "data": { "id": 1, "postId": 1, "userId": 1, "body": "How does this compare to the approach described in the official docs?", "likes": 16, "createdAt": "2023-04-28T06:59:47.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "todos.created": { "post": { "summary": "Todo created", "description": "Fired when a todo is created.", "operationId": "onWebhook_todos_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "todos.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "todos", "resourceId": 1, "data": { "id": 1, "userId": 1, "title": "Configure monitoring", "completed": true, "priority": "low", "dueDate": null, "tags": [], "createdAt": "2024-01-25T00:38:32.919Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "todos.updated": { "post": { "summary": "Todo updated", "description": "Fired when a todo is updated.", "operationId": "onWebhook_todos_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "todos.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "todos", "resourceId": 1, "data": { "id": 1, "userId": 1, "title": "Configure monitoring", "completed": true, "priority": "low", "dueDate": null, "tags": [], "createdAt": "2024-01-25T00:38:32.919Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "todos.deleted": { "post": { "summary": "Todo deleted", "description": "Fired when a todo is deleted.", "operationId": "onWebhook_todos_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "todos.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "todos", "resourceId": 1, "data": { "id": 1, "userId": 1, "title": "Configure monitoring", "completed": true, "priority": "low", "dueDate": null, "tags": [], "createdAt": "2024-01-25T00:38:32.919Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "albums.created": { "post": { "summary": "Album created", "description": "Fired when a album is created.", "operationId": "onWebhook_albums_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "albums.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "albums", "resourceId": 1, "data": { "userId": 1, "title": "Summer 2026", "id": 1, "createdAt": "2024-07-02T09:01:49.954Z", "updatedAt": "2026-04-23T08:07:12.520Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "albums.updated": { "post": { "summary": "Album updated", "description": "Fired when a album is updated.", "operationId": "onWebhook_albums_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "albums.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "albums", "resourceId": 1, "data": { "userId": 1, "title": "Summer 2026", "id": 1, "createdAt": "2024-07-02T09:01:49.954Z", "updatedAt": "2026-04-23T08:07:12.520Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "albums.deleted": { "post": { "summary": "Album deleted", "description": "Fired when a album is deleted.", "operationId": "onWebhook_albums_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "albums.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "albums", "resourceId": 1, "data": { "userId": 1, "title": "Summer 2026", "id": 1, "createdAt": "2024-07-02T09:01:49.954Z", "updatedAt": "2026-04-23T08:07:12.520Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "photos.created": { "post": { "summary": "Photo created", "description": "Fired when a photo is created.", "operationId": "onWebhook_photos_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "photos.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "photos", "resourceId": 1, "data": { "id": 1, "albumId": 1, "title": "Photo 1", "url": "https://picsum.photos/seed/1/800/960", "thumbnailUrl": "https://picsum.photos/seed/1/150/150", "width": 800, "height": 960, "size": 4803273, "format": "jpeg", "createdAt": "2026-07-24T20:47:13.121Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "photos.updated": { "post": { "summary": "Photo updated", "description": "Fired when a photo is updated.", "operationId": "onWebhook_photos_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "photos.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "photos", "resourceId": 1, "data": { "id": 1, "albumId": 1, "title": "Photo 1", "url": "https://picsum.photos/seed/1/800/960", "thumbnailUrl": "https://picsum.photos/seed/1/150/150", "width": 800, "height": 960, "size": 4803273, "format": "jpeg", "createdAt": "2026-07-24T20:47:13.121Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "photos.deleted": { "post": { "summary": "Photo deleted", "description": "Fired when a photo is deleted.", "operationId": "onWebhook_photos_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "photos.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "photos", "resourceId": 1, "data": { "id": 1, "albumId": 1, "title": "Photo 1", "url": "https://picsum.photos/seed/1/800/960", "thumbnailUrl": "https://picsum.photos/seed/1/150/150", "width": 800, "height": 960, "size": 4803273, "format": "jpeg", "createdAt": "2026-07-24T20:47:13.121Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "categories.created": { "post": { "summary": "Category created", "description": "Fired when a category is created.", "operationId": "onWebhook_categories_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "categories.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "categories", "resourceId": 1, "data": { "id": 1, "name": "Electronics", "slug": "electronics", "description": "Gadgets, devices, and electronic accessories", "image": "https://picsum.photos/seed/cat1/300/200", "productCount": 5, "createdAt": "2022-01-06T04:19:58.076Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "categories.updated": { "post": { "summary": "Category updated", "description": "Fired when a category is updated.", "operationId": "onWebhook_categories_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "categories.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "categories", "resourceId": 1, "data": { "id": 1, "name": "Electronics", "slug": "electronics", "description": "Gadgets, devices, and electronic accessories", "image": "https://picsum.photos/seed/cat1/300/200", "productCount": 5, "createdAt": "2022-01-06T04:19:58.076Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "categories.deleted": { "post": { "summary": "Category deleted", "description": "Fired when a category is deleted.", "operationId": "onWebhook_categories_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "categories.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "categories", "resourceId": 1, "data": { "id": 1, "name": "Electronics", "slug": "electronics", "description": "Gadgets, devices, and electronic accessories", "image": "https://picsum.photos/seed/cat1/300/200", "productCount": 5, "createdAt": "2022-01-06T04:19:58.076Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "products.created": { "post": { "summary": "Product created", "description": "Fired when a product is created.", "operationId": "onWebhook_products_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "products.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "products", "resourceId": 1, "data": { "id": 1, "categoryId": 4, "name": "Desk Lamp", "description": "Ultra-fast connectivity with rock-solid reliability.", "price": 161.28, "originalPrice": 231.38, "currency": "USD", "stock": 257, "sku": "SKU-00001", "rating": 4.4, "reviewCount": 188, "image": "https://picsum.photos/seed/prod1/400/400", "images": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ], "weight": 9.19, "dimensions": { "width": 33.4, "height": 40, "depth": 14.6 }, "isAvailable": true, "isFeatured": false, "tags": [ "backend" ], "createdAt": "2024-05-30T01:37:26.059Z", "updatedAt": "2026-12-15T02:55:19.943Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "products.updated": { "post": { "summary": "Product updated", "description": "Fired when a product is updated.", "operationId": "onWebhook_products_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "products.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "products", "resourceId": 1, "data": { "id": 1, "categoryId": 4, "name": "Desk Lamp", "description": "Ultra-fast connectivity with rock-solid reliability.", "price": 161.28, "originalPrice": 231.38, "currency": "USD", "stock": 257, "sku": "SKU-00001", "rating": 4.4, "reviewCount": 188, "image": "https://picsum.photos/seed/prod1/400/400", "images": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ], "weight": 9.19, "dimensions": { "width": 33.4, "height": 40, "depth": 14.6 }, "isAvailable": true, "isFeatured": false, "tags": [ "backend" ], "createdAt": "2024-05-30T01:37:26.059Z", "updatedAt": "2026-12-15T02:55:19.943Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "products.deleted": { "post": { "summary": "Product deleted", "description": "Fired when a product is deleted.", "operationId": "onWebhook_products_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "products.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "products", "resourceId": 1, "data": { "id": 1, "categoryId": 4, "name": "Desk Lamp", "description": "Ultra-fast connectivity with rock-solid reliability.", "price": 161.28, "originalPrice": 231.38, "currency": "USD", "stock": 257, "sku": "SKU-00001", "rating": 4.4, "reviewCount": 188, "image": "https://picsum.photos/seed/prod1/400/400", "images": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ], "weight": 9.19, "dimensions": { "width": 33.4, "height": 40, "depth": 14.6 }, "isAvailable": true, "isFeatured": false, "tags": [ "backend" ], "createdAt": "2024-05-30T01:37:26.059Z", "updatedAt": "2026-12-15T02:55:19.943Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "orders.created": { "post": { "summary": "Order created", "description": "Fired when a order is created.", "operationId": "onWebhook_orders_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "orders.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "orders", "resourceId": 1, "data": { "id": 1, "userId": 1, "items": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ], "subtotal": 1791.68, "tax": 143.33, "shipping": 0, "total": 1935.01, "currency": "USD", "status": "pending", "paymentMethod": "credit_card", "shippingAddress": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" }, "trackingNumber": "TRK442765071", "notes": null, "createdAt": "2026-04-19T12:16:46.226Z", "updatedAt": "2025-01-30T04:10:54.855Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "orders.updated": { "post": { "summary": "Order updated", "description": "Fired when a order is updated.", "operationId": "onWebhook_orders_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "orders.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "orders", "resourceId": 1, "data": { "id": 1, "userId": 1, "items": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ], "subtotal": 1791.68, "tax": 143.33, "shipping": 0, "total": 1935.01, "currency": "USD", "status": "pending", "paymentMethod": "credit_card", "shippingAddress": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" }, "trackingNumber": "TRK442765071", "notes": null, "createdAt": "2026-04-19T12:16:46.226Z", "updatedAt": "2025-01-30T04:10:54.855Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "orders.deleted": { "post": { "summary": "Order deleted", "description": "Fired when a order is deleted.", "operationId": "onWebhook_orders_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "orders.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "orders", "resourceId": 1, "data": { "id": 1, "userId": 1, "items": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ], "subtotal": 1791.68, "tax": 143.33, "shipping": 0, "total": 1935.01, "currency": "USD", "status": "pending", "paymentMethod": "credit_card", "shippingAddress": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" }, "trackingNumber": "TRK442765071", "notes": null, "createdAt": "2026-04-19T12:16:46.226Z", "updatedAt": "2025-01-30T04:10:54.855Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "reviews.created": { "post": { "summary": "Review created", "description": "Fired when a review is created.", "operationId": "onWebhook_reviews_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "reviews.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "reviews", "resourceId": 1, "data": { "id": 1, "productId": 1, "userId": 1, "rating": 4, "title": "Works as advertised", "body": "Great article! Really helped me understand the concept better.", "isVerified": true, "helpful": 1, "createdAt": "2025-08-29T18:25:55.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "reviews.updated": { "post": { "summary": "Review updated", "description": "Fired when a review is updated.", "operationId": "onWebhook_reviews_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "reviews.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "reviews", "resourceId": 1, "data": { "id": 1, "productId": 1, "userId": 1, "rating": 4, "title": "Works as advertised", "body": "Great article! Really helped me understand the concept better.", "isVerified": true, "helpful": 1, "createdAt": "2025-08-29T18:25:55.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "reviews.deleted": { "post": { "summary": "Review deleted", "description": "Fired when a review is deleted.", "operationId": "onWebhook_reviews_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "reviews.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "reviews", "resourceId": 1, "data": { "id": 1, "productId": 1, "userId": 1, "rating": 4, "title": "Works as advertised", "body": "Great article! Really helped me understand the concept better.", "isVerified": true, "helpful": 1, "createdAt": "2025-08-29T18:25:55.906Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "notifications.created": { "post": { "summary": "Notification created", "description": "Fired when a notification is created.", "operationId": "onWebhook_notifications_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "notifications.created", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "notifications", "resourceId": 1, "data": { "id": 1, "userId": 1, "type": "error", "title": "Error notification", "message": "New follower on your profile.", "read": true, "link": null, "createdAt": "2026-03-23T15:22:15.402Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "notifications.updated": { "post": { "summary": "Notification updated", "description": "Fired when a notification is updated.", "operationId": "onWebhook_notifications_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "notifications.updated", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "notifications", "resourceId": 1, "data": { "id": 1, "userId": 1, "type": "error", "title": "Error notification", "message": "New follower on your profile.", "read": true, "link": null, "createdAt": "2026-03-23T15:22:15.402Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "notifications.deleted": { "post": { "summary": "Notification deleted", "description": "Fired when a notification is deleted.", "operationId": "onWebhook_notifications_deleted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "example": { "event": "notifications.deleted", "timestamp": "2025-01-15T12:00:00.000Z", "resource": "notifications", "resourceId": 1, "data": { "id": 1, "userId": 1, "type": "error", "title": "Error notification", "message": "New follower on your profile.", "read": true, "link": null, "createdAt": "2026-03-23T15:22:15.402Z" } } } } }, "responses": { "410": { "description": "Endpoint gone — subscription may be deactivated" }, "2XX": { "description": "Event processed" } } } }, "webhook.test": { "post": { "summary": "Test ping", "description": "Fired via `POST /webhooks/{id}/test`.", "operationId": "onWebhook_test", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Test received" } } } } }, "components": { "schemas": { "User": { "type": "object", "description": "Platform users with profiles, addresses, and company information", "required": [ "firstName", "lastName", "email" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique user identifier", "example": 1 }, "firstName": { "type": "string", "description": "First name", "minLength": 1, "maxLength": 50, "examples": [ "James", "Mary" ], "example": "Demo" }, "lastName": { "type": "string", "description": "Last name", "minLength": 1, "maxLength": 50, "example": "User" }, "email": { "type": "string", "format": "email", "description": "Email address (unique per user)", "example": "demo@example.com" }, "username": { "type": "string", "description": "Unique username", "minLength": 3, "maxLength": 30, "example": "demo" }, "avatar": { "type": "string", "format": "uri", "description": "Profile picture URL", "example": "https://i.pravatar.cc/150?u=demo" }, "phone": { "type": "string", "description": "Phone in international format", "pattern": "^\\+\\d{1,3}-\\d{3}-\\d{3}-\\d{4}$", "example": "+1-555-000-0001" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "1 Demo Way" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zipCode": { "type": "string", "example": "78701" }, "country": { "type": "string", "example": "US" }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "example": 30.2672 }, "lng": { "type": "number", "format": "double", "example": -97.7431 } }, "example": { "lat": 30.2672, "lng": -97.7431 } } }, "description": "Physical mailing address", "example": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } } }, "company": { "type": "object", "properties": { "name": { "type": "string", "example": "Demo Corp" }, "catchPhrase": { "type": "string", "example": "Seeded for docs and testing." } }, "description": "Employment information", "example": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." } }, "website": { "type": "string", "format": "uri", "description": "Personal website URL", "example": "https://example.com/demo" }, "role": { "type": "string", "description": "Access control role", "enum": [ "admin", "user", "moderator", "editor", "viewer" ], "default": "user", "example": "admin" }, "age": { "type": "integer", "format": "int32", "description": "Age in years", "minimum": 0, "maximum": 150, "example": 30 }, "bio": { "type": "string", "description": "Short biography", "example": "Seeded demo account. Log in with any password." }, "isActive": { "type": "boolean", "description": "Whether the account is active", "default": true, "example": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-21T00:00:00.000Z" } }, "example": { "id": 1, "firstName": "Demo", "lastName": "User", "email": "demo@example.com", "username": "demo", "avatar": "https://i.pravatar.cc/150?u=demo", "phone": "+1-555-000-0001", "address": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } }, "company": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." }, "website": "https://example.com/demo", "role": "admin", "age": 30, "bio": "Seeded demo account. Log in with any password.", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2026-04-21T00:00:00.000Z" } }, "UserInput": { "type": "object", "description": "Input for creating or updating a user", "required": [ "firstName", "lastName", "email" ], "properties": { "firstName": { "type": "string", "description": "First name", "minLength": 1, "maxLength": 50, "examples": [ "James", "Mary" ], "example": "Demo" }, "lastName": { "type": "string", "description": "Last name", "minLength": 1, "maxLength": 50, "example": "User" }, "email": { "type": "string", "format": "email", "description": "Email address (unique per user)", "example": "demo@example.com" }, "username": { "type": "string", "description": "Unique username", "minLength": 3, "maxLength": 30, "example": "demo" }, "avatar": { "type": "string", "format": "uri", "description": "Profile picture URL", "example": "https://i.pravatar.cc/150?u=demo" }, "phone": { "type": "string", "description": "Phone in international format", "pattern": "^\\+\\d{1,3}-\\d{3}-\\d{3}-\\d{4}$", "example": "+1-555-000-0001" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "1 Demo Way" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zipCode": { "type": "string", "example": "78701" }, "country": { "type": "string", "example": "US" }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "example": 30.2672 }, "lng": { "type": "number", "format": "double", "example": -97.7431 } }, "example": { "lat": 30.2672, "lng": -97.7431 } } }, "description": "Physical mailing address", "example": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } } }, "company": { "type": "object", "properties": { "name": { "type": "string", "example": "Demo Corp" }, "catchPhrase": { "type": "string", "example": "Seeded for docs and testing." } }, "description": "Employment information", "example": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." } }, "website": { "type": "string", "format": "uri", "description": "Personal website URL", "example": "https://example.com/demo" }, "role": { "type": "string", "description": "Access control role", "enum": [ "admin", "user", "moderator", "editor", "viewer" ], "default": "user", "example": "admin" }, "age": { "type": "integer", "format": "int32", "description": "Age in years", "minimum": 0, "maximum": 150, "example": 30 }, "bio": { "type": "string", "description": "Short biography", "example": "Seeded demo account. Log in with any password." }, "isActive": { "type": "boolean", "description": "Whether the account is active", "default": true, "example": true } }, "example": { "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com" } }, "Post": { "type": "object", "description": "Blog posts with rich content, tags, and engagement metrics", "required": [ "title", "body" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Author user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Post title", "minLength": 1, "maxLength": 200, "example": "TypeScript tips I learned the hard way" }, "body": { "type": "string", "description": "Full post content in plain text", "example": "First, never use `any`…" }, "excerpt": { "type": "string", "description": "Short preview text", "maxLength": 300, "example": "Ten hard-won lessons from the trenches." }, "tags": { "type": "array", "items": { "type": "string", "example": "typescript" }, "description": "Categorization tags", "uniqueItems": true, "example": [ "typescript", "engineering" ] }, "status": { "type": "string", "description": "Publication status", "enum": [ "draft", "published", "archived" ], "default": "draft", "example": "draft" }, "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique post identifier", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-01-21T19:36:04.116Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-05-01T05:55:47.527Z" }, "deletedAt": { "type": "string", "format": "date-time", "example": "2026-05-01T05:55:47.527Z" } }, "example": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft", "id": 1, "createdAt": "2026-01-21T19:36:04.116Z", "updatedAt": "2026-05-01T05:55:47.527Z", "deletedAt": "2026-05-01T05:55:47.527Z" } }, "PostInput": { "type": "object", "description": "Input for creating or updating a post", "required": [ "title", "body" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Author user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Post title", "minLength": 1, "maxLength": 200, "example": "TypeScript tips I learned the hard way" }, "body": { "type": "string", "description": "Full post content in plain text", "example": "First, never use `any`…" }, "excerpt": { "type": "string", "description": "Short preview text", "maxLength": 300, "example": "Ten hard-won lessons from the trenches." }, "tags": { "type": "array", "items": { "type": "string", "example": "typescript" }, "description": "Categorization tags", "uniqueItems": true, "example": [ "typescript", "engineering" ] }, "status": { "type": "string", "description": "Publication status", "enum": [ "draft", "published", "archived" ], "default": "draft", "example": "draft" }, "deletedAt": { "type": "string", "format": "date-time", "example": "2026-05-01T05:55:47.527Z" } }, "example": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft" } }, "Comment": { "type": "object", "description": "User comments on blog posts", "required": [ "postId", "body" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique comment identifier", "example": 1 }, "postId": { "type": "integer", "format": "int32", "description": "Parent post ID", "minimum": 1, "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Author user ID", "minimum": 1, "example": 1 }, "body": { "type": "string", "description": "Comment text content", "example": "How does this compare to the approach described in the official docs?" }, "likes": { "type": "integer", "format": "int32", "description": "Number of likes", "minimum": 0, "example": 16 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2023-04-28T06:59:47.906Z" } }, "example": { "id": 1, "postId": 1, "userId": 1, "body": "How does this compare to the approach described in the official docs?", "likes": 16, "createdAt": "2023-04-28T06:59:47.906Z" } }, "CommentInput": { "type": "object", "description": "Input for creating or updating a comment", "required": [ "postId", "body" ], "properties": { "postId": { "type": "integer", "format": "int32", "description": "Parent post ID", "minimum": 1, "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Author user ID", "minimum": 1, "example": 1 }, "body": { "type": "string", "description": "Comment text content", "example": "How does this compare to the approach described in the official docs?" }, "likes": { "type": "integer", "format": "int32", "description": "Number of likes", "minimum": 0, "example": 16 } }, "example": { "postId": 1, "userId": 2, "body": "Great write-up — saved me an hour of debugging." } }, "Todo": { "type": "object", "description": "Task items with priorities, due dates, and tags", "required": [ "title" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique todo identifier", "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Owner user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Task description", "minLength": 1, "maxLength": 200, "example": "Configure monitoring" }, "completed": { "type": "boolean", "description": "Whether the task is done", "default": false, "example": true }, "priority": { "type": "string", "description": "Task priority level", "enum": [ "low", "medium", "high", "critical" ], "default": "medium", "example": "low" }, "dueDate": { "type": [ "string", "null" ], "description": "Due date (null if no deadline)", "format": "date-time", "example": null }, "tags": { "type": "array", "items": {}, "description": "Categorization tags", "uniqueItems": true, "example": [] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-25T00:38:32.919Z" } }, "example": { "id": 1, "userId": 1, "title": "Configure monitoring", "completed": true, "priority": "low", "dueDate": null, "tags": [], "createdAt": "2024-01-25T00:38:32.919Z" } }, "TodoInput": { "type": "object", "description": "Input for creating or updating a todo", "required": [ "title" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Owner user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Task description", "minLength": 1, "maxLength": 200, "example": "Configure monitoring" }, "completed": { "type": "boolean", "description": "Whether the task is done", "default": false, "example": true }, "priority": { "type": "string", "description": "Task priority level", "enum": [ "low", "medium", "high", "critical" ], "default": "medium", "example": "low" }, "dueDate": { "type": [ "string", "null" ], "description": "Due date (null if no deadline)", "format": "date-time", "example": null }, "tags": { "type": "array", "items": {}, "description": "Categorization tags", "uniqueItems": true, "example": [] } }, "example": { "userId": 1, "title": "Reply to launch-day emails" } }, "Album": { "type": "object", "description": "Photo albums for organizing image collections", "required": [ "title" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Owner user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Album title", "minLength": 1, "example": "Summer 2026" }, "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique album identifier", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-07-02T09:01:49.954Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-23T08:07:12.520Z" } }, "example": { "userId": 1, "title": "Summer 2026", "id": 1, "createdAt": "2024-07-02T09:01:49.954Z", "updatedAt": "2026-04-23T08:07:12.520Z" } }, "AlbumInput": { "type": "object", "description": "Input for creating or updating a album", "required": [ "title" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Owner user ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Album title", "minLength": 1, "example": "Summer 2026" } }, "example": { "userId": 1, "title": "Summer 2026" } }, "Photo": { "type": "object", "description": "Individual photos within albums", "required": [ "albumId", "url" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique photo identifier", "example": 1 }, "albumId": { "type": "integer", "format": "int32", "description": "Parent album ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Photo title or caption", "example": "Photo 1" }, "url": { "type": "string", "format": "uri", "description": "Full-size image URL", "example": "https://picsum.photos/seed/1/800/960" }, "thumbnailUrl": { "type": "string", "format": "uri", "description": "Thumbnail URL (150x150)", "example": "https://picsum.photos/seed/1/150/150" }, "width": { "type": "integer", "format": "int32", "description": "Image width in pixels", "minimum": 1, "example": 800 }, "height": { "type": "integer", "format": "int32", "description": "Image height in pixels", "minimum": 1, "example": 960 }, "size": { "type": "integer", "format": "int32", "description": "File size in bytes", "minimum": 0, "example": 4803273 }, "format": { "type": "string", "description": "Image format", "enum": [ "jpeg", "png", "webp" ], "example": "jpeg" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-07-24T20:47:13.121Z" } }, "example": { "id": 1, "albumId": 1, "title": "Photo 1", "url": "https://picsum.photos/seed/1/800/960", "thumbnailUrl": "https://picsum.photos/seed/1/150/150", "width": 800, "height": 960, "size": 4803273, "format": "jpeg", "createdAt": "2026-07-24T20:47:13.121Z" } }, "PhotoInput": { "type": "object", "description": "Input for creating or updating a photo", "required": [ "albumId", "url" ], "properties": { "albumId": { "type": "integer", "format": "int32", "description": "Parent album ID", "minimum": 1, "example": 1 }, "title": { "type": "string", "description": "Photo title or caption", "example": "Photo 1" }, "url": { "type": "string", "format": "uri", "description": "Full-size image URL", "example": "https://picsum.photos/seed/1/800/960" }, "thumbnailUrl": { "type": "string", "format": "uri", "description": "Thumbnail URL (150x150)", "example": "https://picsum.photos/seed/1/150/150" }, "width": { "type": "integer", "format": "int32", "description": "Image width in pixels", "minimum": 1, "example": 800 }, "height": { "type": "integer", "format": "int32", "description": "Image height in pixels", "minimum": 1, "example": 960 }, "size": { "type": "integer", "format": "int32", "description": "File size in bytes", "minimum": 0, "example": 4803273 }, "format": { "type": "string", "description": "Image format", "enum": [ "jpeg", "png", "webp" ], "example": "jpeg" } }, "example": { "albumId": 1, "title": "Sunset at Vík", "url": "https://picsum.photos/1600/1067?random=1", "thumbnailUrl": "https://picsum.photos/150/150?random=1", "width": 1600, "height": 1067, "format": "jpeg", "size": 284532 } }, "Category": { "type": "object", "description": "Product categories for taxonomy and organization", "required": [ "name", "slug" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique category identifier", "example": 1 }, "name": { "type": "string", "description": "Category display name", "minLength": 1, "example": "Electronics" }, "slug": { "type": "string", "description": "URL-friendly slug", "pattern": "^[a-z0-9-]+$", "example": "electronics" }, "description": { "type": "string", "description": "Category description", "example": "Gadgets, devices, and electronic accessories" }, "image": { "type": "string", "format": "uri", "description": "Category image URL", "example": "https://picsum.photos/seed/cat1/300/200" }, "productCount": { "type": "integer", "format": "int32", "description": "Products in this category", "minimum": 0, "example": 5 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2022-01-06T04:19:58.076Z" } }, "example": { "id": 1, "name": "Electronics", "slug": "electronics", "description": "Gadgets, devices, and electronic accessories", "image": "https://picsum.photos/seed/cat1/300/200", "productCount": 5, "createdAt": "2022-01-06T04:19:58.076Z" } }, "CategoryInput": { "type": "object", "description": "Input for creating or updating a category", "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "description": "Category display name", "minLength": 1, "example": "Electronics" }, "slug": { "type": "string", "description": "URL-friendly slug", "pattern": "^[a-z0-9-]+$", "example": "electronics" }, "description": { "type": "string", "description": "Category description", "example": "Gadgets, devices, and electronic accessories" }, "image": { "type": "string", "format": "uri", "description": "Category image URL", "example": "https://picsum.photos/seed/cat1/300/200" }, "productCount": { "type": "integer", "format": "int32", "description": "Products in this category", "minimum": 0, "example": 5 } }, "example": { "name": "Electronics", "slug": "electronics" } }, "Product": { "type": "object", "description": "E-commerce products with pricing, inventory, and images", "required": [ "name", "price" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique product identifier", "example": 1 }, "categoryId": { "type": "integer", "format": "int32", "description": "Parent category ID", "minimum": 1, "example": 4 }, "name": { "type": "string", "description": "Product name", "minLength": 1, "maxLength": 200, "example": "Desk Lamp" }, "description": { "type": "string", "description": "Product description", "example": "Ultra-fast connectivity with rock-solid reliability." }, "price": { "type": "number", "format": "double", "description": "Current price in USD", "minimum": 0, "example": 161.28 }, "originalPrice": { "type": "number", "format": "double", "description": "Original price before discount (null if none)", "example": 231.38 }, "currency": { "type": "string", "description": "ISO 4217 currency code", "enum": [ "USD" ], "default": "USD", "example": "USD" }, "stock": { "type": "integer", "format": "int32", "description": "Available inventory count", "minimum": 0, "example": 257 }, "sku": { "type": "string", "description": "Stock keeping unit", "pattern": "^SKU-\\d{5}$", "example": "SKU-00001" }, "rating": { "type": "number", "format": "double", "description": "Average customer rating", "minimum": 1, "maximum": 5, "example": 4.4 }, "reviewCount": { "type": "integer", "format": "int32", "description": "Total reviews", "minimum": 0, "example": 188 }, "image": { "type": "string", "format": "uri", "description": "Primary image URL", "example": "https://picsum.photos/seed/prod1/400/400" }, "images": { "type": "array", "items": { "type": "string", "example": "https://picsum.photos/seed/prod1-0/400/400" }, "description": "Image gallery URLs", "minItems": 1, "example": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ] }, "weight": { "type": "number", "format": "double", "description": "Weight in kg", "minimum": 0, "example": 9.19 }, "dimensions": { "type": "object", "properties": { "width": { "type": "number", "format": "double", "example": 33.4 }, "height": { "type": "integer", "format": "int32", "example": 40 }, "depth": { "type": "number", "format": "double", "example": 14.6 } }, "description": "Dimensions in cm", "example": { "width": 33.4, "height": 40, "depth": 14.6 } }, "isAvailable": { "type": "boolean", "description": "Can be purchased", "default": true, "example": true }, "isFeatured": { "type": "boolean", "description": "Editorially featured", "default": false, "example": false }, "tags": { "type": "array", "items": { "type": "string", "example": "backend" }, "description": "Search and filter tags", "uniqueItems": true, "example": [ "backend" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-05-30T01:37:26.059Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-12-15T02:55:19.943Z" } }, "example": { "id": 1, "categoryId": 4, "name": "Desk Lamp", "description": "Ultra-fast connectivity with rock-solid reliability.", "price": 161.28, "originalPrice": 231.38, "currency": "USD", "stock": 257, "sku": "SKU-00001", "rating": 4.4, "reviewCount": 188, "image": "https://picsum.photos/seed/prod1/400/400", "images": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ], "weight": 9.19, "dimensions": { "width": 33.4, "height": 40, "depth": 14.6 }, "isAvailable": true, "isFeatured": false, "tags": [ "backend" ], "createdAt": "2024-05-30T01:37:26.059Z", "updatedAt": "2026-12-15T02:55:19.943Z" } }, "ProductInput": { "type": "object", "description": "Input for creating or updating a product", "required": [ "name", "price" ], "properties": { "categoryId": { "type": "integer", "format": "int32", "description": "Parent category ID", "minimum": 1, "example": 4 }, "name": { "type": "string", "description": "Product name", "minLength": 1, "maxLength": 200, "example": "Desk Lamp" }, "description": { "type": "string", "description": "Product description", "example": "Ultra-fast connectivity with rock-solid reliability." }, "price": { "type": "number", "format": "double", "description": "Current price in USD", "minimum": 0, "example": 161.28 }, "originalPrice": { "type": "number", "format": "double", "description": "Original price before discount (null if none)", "example": 231.38 }, "currency": { "type": "string", "description": "ISO 4217 currency code", "enum": [ "USD" ], "default": "USD", "example": "USD" }, "stock": { "type": "integer", "format": "int32", "description": "Available inventory count", "minimum": 0, "example": 257 }, "sku": { "type": "string", "description": "Stock keeping unit", "pattern": "^SKU-\\d{5}$", "example": "SKU-00001" }, "rating": { "type": "number", "format": "double", "description": "Average customer rating", "minimum": 1, "maximum": 5, "example": 4.4 }, "reviewCount": { "type": "integer", "format": "int32", "description": "Total reviews", "minimum": 0, "example": 188 }, "image": { "type": "string", "format": "uri", "description": "Primary image URL", "example": "https://picsum.photos/seed/prod1/400/400" }, "images": { "type": "array", "items": { "type": "string", "example": "https://picsum.photos/seed/prod1-0/400/400" }, "description": "Image gallery URLs", "minItems": 1, "example": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ] }, "weight": { "type": "number", "format": "double", "description": "Weight in kg", "minimum": 0, "example": 9.19 }, "dimensions": { "type": "object", "properties": { "width": { "type": "number", "format": "double", "example": 33.4 }, "height": { "type": "integer", "format": "int32", "example": 40 }, "depth": { "type": "number", "format": "double", "example": 14.6 } }, "description": "Dimensions in cm", "example": { "width": 33.4, "height": 40, "depth": 14.6 } }, "isAvailable": { "type": "boolean", "description": "Can be purchased", "default": true, "example": true }, "isFeatured": { "type": "boolean", "description": "Editorially featured", "default": false, "example": false }, "tags": { "type": "array", "items": { "type": "string", "example": "backend" }, "description": "Search and filter tags", "uniqueItems": true, "example": [ "backend" ] } }, "example": { "categoryId": 1, "name": "Wireless earbuds", "price": 79.99, "sku": "SKU-01001", "stock": 100 } }, "Order": { "type": "object", "description": "Customer orders with line items, shipping, and payment", "required": [ "userId", "items" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique order identifier", "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Customer user ID", "minimum": 1, "example": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "format": "int32", "example": 37 }, "quantity": { "type": "integer", "format": "int32", "example": 2 }, "price": { "type": "number", "format": "double", "example": 416.97 } } }, "description": "Ordered line items", "minItems": 1, "example": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ] }, "subtotal": { "type": "number", "format": "double", "description": "Items total before tax/shipping", "minimum": 0, "example": 1791.68 }, "tax": { "type": "number", "format": "double", "description": "Tax amount", "minimum": 0, "example": 143.33 }, "shipping": { "type": "integer", "format": "int32", "description": "Shipping cost (free over $100)", "minimum": 0, "example": 0 }, "total": { "type": "number", "format": "double", "description": "Grand total", "minimum": 0, "example": 1935.01 }, "currency": { "type": "string", "description": "Order currency", "enum": [ "USD" ], "example": "USD" }, "status": { "type": "string", "description": "Fulfillment status", "enum": [ "pending", "processing", "shipped", "delivered", "cancelled", "refunded" ], "default": "pending", "example": "pending" }, "paymentMethod": { "type": "string", "description": "Payment method", "enum": [ "credit_card", "debit_card", "paypal", "apple_pay", "google_pay" ], "example": "credit_card" }, "shippingAddress": { "type": "object", "properties": { "street": { "type": "string", "example": "6620 Maple Dr" }, "city": { "type": "string", "example": "Fort Worth" }, "state": { "type": "string", "example": "MI" }, "zipCode": { "type": "string", "example": "16372" }, "country": { "type": "string", "example": "US" } }, "description": "Delivery address", "example": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" } }, "trackingNumber": { "type": "string", "description": "Tracking number (null if not shipped)", "example": "TRK442765071" }, "notes": { "type": [ "string", "null" ], "description": "Customer notes", "example": null }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-19T12:16:46.226Z" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2025-01-30T04:10:54.855Z" } }, "example": { "id": 1, "userId": 1, "items": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ], "subtotal": 1791.68, "tax": 143.33, "shipping": 0, "total": 1935.01, "currency": "USD", "status": "pending", "paymentMethod": "credit_card", "shippingAddress": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" }, "trackingNumber": "TRK442765071", "notes": null, "createdAt": "2026-04-19T12:16:46.226Z", "updatedAt": "2025-01-30T04:10:54.855Z" } }, "OrderInput": { "type": "object", "description": "Input for creating or updating a order", "required": [ "userId", "items" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Customer user ID", "minimum": 1, "example": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "format": "int32", "example": 37 }, "quantity": { "type": "integer", "format": "int32", "example": 2 }, "price": { "type": "number", "format": "double", "example": 416.97 } } }, "description": "Ordered line items", "minItems": 1, "example": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ] }, "subtotal": { "type": "number", "format": "double", "description": "Items total before tax/shipping", "minimum": 0, "example": 1791.68 }, "tax": { "type": "number", "format": "double", "description": "Tax amount", "minimum": 0, "example": 143.33 }, "shipping": { "type": "integer", "format": "int32", "description": "Shipping cost (free over $100)", "minimum": 0, "example": 0 }, "total": { "type": "number", "format": "double", "description": "Grand total", "minimum": 0, "example": 1935.01 }, "currency": { "type": "string", "description": "Order currency", "enum": [ "USD" ], "example": "USD" }, "status": { "type": "string", "description": "Fulfillment status", "enum": [ "pending", "processing", "shipped", "delivered", "cancelled", "refunded" ], "default": "pending", "example": "pending" }, "paymentMethod": { "type": "string", "description": "Payment method", "enum": [ "credit_card", "debit_card", "paypal", "apple_pay", "google_pay" ], "example": "credit_card" }, "shippingAddress": { "type": "object", "properties": { "street": { "type": "string", "example": "6620 Maple Dr" }, "city": { "type": "string", "example": "Fort Worth" }, "state": { "type": "string", "example": "MI" }, "zipCode": { "type": "string", "example": "16372" }, "country": { "type": "string", "example": "US" } }, "description": "Delivery address", "example": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" } }, "trackingNumber": { "type": "string", "description": "Tracking number (null if not shipped)", "example": "TRK442765071" }, "notes": { "type": [ "string", "null" ], "description": "Customer notes", "example": null } }, "example": { "userId": 1, "items": [ { "productId": 1, "quantity": 2, "price": 79.99 }, { "productId": 2, "quantity": 1, "price": 89 } ], "subtotal": 248.98, "tax": 19.92, "shipping": 0, "total": 268.9, "currency": "USD", "paymentMethod": "credit_card", "shippingAddress": { "street": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701", "country": "US" } } }, "Review": { "type": "object", "description": "Product reviews with ratings and verification", "required": [ "productId", "rating" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique review identifier", "example": 1 }, "productId": { "type": "integer", "format": "int32", "description": "Reviewed product ID", "minimum": 1, "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Reviewer user ID", "minimum": 1, "example": 1 }, "rating": { "type": "integer", "format": "int32", "description": "Star rating", "minimum": 1, "maximum": 5, "example": 4 }, "title": { "type": "string", "description": "Review headline", "example": "Works as advertised" }, "body": { "type": "string", "description": "Full review text", "example": "Great article! Really helped me understand the concept better." }, "isVerified": { "type": "boolean", "description": "Verified purchaser", "example": true }, "helpful": { "type": "integer", "format": "int32", "description": "\"Helpful\" votes", "minimum": 0, "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2025-08-29T18:25:55.906Z" } }, "example": { "id": 1, "productId": 1, "userId": 1, "rating": 4, "title": "Works as advertised", "body": "Great article! Really helped me understand the concept better.", "isVerified": true, "helpful": 1, "createdAt": "2025-08-29T18:25:55.906Z" } }, "ReviewInput": { "type": "object", "description": "Input for creating or updating a review", "required": [ "productId", "rating" ], "properties": { "productId": { "type": "integer", "format": "int32", "description": "Reviewed product ID", "minimum": 1, "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Reviewer user ID", "minimum": 1, "example": 1 }, "rating": { "type": "integer", "format": "int32", "description": "Star rating", "minimum": 1, "maximum": 5, "example": 4 }, "title": { "type": "string", "description": "Review headline", "example": "Works as advertised" }, "body": { "type": "string", "description": "Full review text", "example": "Great article! Really helped me understand the concept better." }, "isVerified": { "type": "boolean", "description": "Verified purchaser", "example": true }, "helpful": { "type": "integer", "format": "int32", "description": "\"Helpful\" votes", "minimum": 0, "example": 1 } }, "example": { "productId": 1, "userId": 1, "rating": 5, "title": "Better than I expected", "body": "Quality is on par with gear twice the price. Would buy again.", "isVerified": true, "helpful": 12 } }, "Notification": { "type": "object", "description": "User notifications and system alerts", "required": [ "userId", "type", "message" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique notification identifier", "example": 1 }, "userId": { "type": "integer", "format": "int32", "description": "Recipient user ID", "minimum": 1, "example": 1 }, "type": { "type": "string", "description": "Notification category", "enum": [ "info", "warning", "success", "error", "system" ], "example": "error" }, "title": { "type": "string", "description": "Notification title", "example": "Error notification" }, "message": { "type": "string", "description": "Notification body text", "example": "New follower on your profile." }, "read": { "type": "boolean", "description": "Has been read", "default": false, "example": true }, "link": { "type": [ "string", "null" ], "description": "Related resource URL", "format": "uri-reference", "example": null }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-03-23T15:22:15.402Z" } }, "example": { "id": 1, "userId": 1, "type": "error", "title": "Error notification", "message": "New follower on your profile.", "read": true, "link": null, "createdAt": "2026-03-23T15:22:15.402Z" } }, "NotificationInput": { "type": "object", "description": "Input for creating or updating a notification", "required": [ "userId", "type", "message" ], "properties": { "userId": { "type": "integer", "format": "int32", "description": "Recipient user ID", "minimum": 1, "example": 1 }, "type": { "type": "string", "description": "Notification category", "enum": [ "info", "warning", "success", "error", "system" ], "example": "error" }, "title": { "type": "string", "description": "Notification title", "example": "Error notification" }, "message": { "type": "string", "description": "Notification body text", "example": "New follower on your profile." }, "read": { "type": "boolean", "description": "Has been read", "default": false, "example": true }, "link": { "type": [ "string", "null" ], "description": "Related resource URL", "format": "uri-reference", "example": null } }, "example": { "userId": 1, "type": "info", "title": "New feature available", "message": "Batch operations are now live — run up to 20 writes in one call.", "link": "/guide/batch" } }, "Webhook": { "type": "object", "description": "Webhook subscription for receiving event notifications via HTTP POST callbacks", "required": [ "id", "url", "events" ], "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Unique webhook identifier", "example": 1 }, "url": { "type": "string", "format": "uri", "description": "Endpoint URL to receive webhook POST requests", "example": "https://example.com/webhooks/receiver" }, "events": { "type": "array", "items": { "type": "string", "pattern": "^(\\*|[a-z]+\\.(created|updated|deleted|\\*)|\\*\\.(created|updated|deleted))$" }, "description": "Event patterns: `*` (all), `users.*`, `*.created`, `users.created`", "example": [ "users.created", "orders.*" ], "minItems": 1, "uniqueItems": true }, "secret": { "type": [ "string", "null" ], "description": "Shared secret for HMAC-SHA256 signature verification", "writeOnly": true, "example": "whsec_abc123" }, "isActive": { "type": "boolean", "description": "Whether the webhook is active", "default": true, "example": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Registration timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Last modification timestamp" } } }, "WebhookInput": { "type": "object", "description": "Data for creating or updating a webhook", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Endpoint URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event patterns to subscribe to", "minItems": 1, "uniqueItems": true }, "secret": { "type": "string", "description": "Shared secret for signature verification", "writeOnly": true }, "isActive": { "type": "boolean", "description": "Whether the webhook is active", "default": true } } }, "WebhookDelivery": { "type": "object", "description": "Record of a webhook delivery attempt (simulated — no actual HTTP requests)", "properties": { "id": { "type": "integer", "format": "int32", "readOnly": true, "description": "Delivery identifier", "example": 1 }, "webhookId": { "type": "integer", "format": "int32", "description": "Associated webhook ID", "example": 1 }, "event": { "type": "string", "description": "Triggering event", "example": "users.created" }, "resource": { "type": "string", "description": "Resource type", "example": "users" }, "resourceId": { "type": "integer", "format": "int32", "description": "Resource ID", "example": 51 }, "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "payload": { "$ref": "#/components/schemas/WebhookPayload" }, "success": { "type": "boolean", "description": "Delivery succeeded", "example": true }, "statusCode": { "type": "integer", "format": "int32", "description": "Simulated HTTP status", "example": 200 }, "duration": { "type": "integer", "format": "int32", "description": "Simulated duration in ms", "example": 42 }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true } } }, "WebhookPayload": { "type": "object", "description": "Payload sent to webhook endpoints", "required": [ "event", "timestamp", "data" ], "properties": { "event": { "type": "string", "description": "Fully qualified event name", "example": "users.created" }, "timestamp": { "type": "string", "format": "date-time", "description": "Event occurrence timestamp" }, "resource": { "type": "string", "description": "Resource type", "example": "users" }, "resourceId": { "type": "integer", "format": "int32", "description": "Resource ID", "example": 51 }, "data": { "type": "object", "description": "Full resource object at time of event", "additionalProperties": true } } }, "Error": { "type": "object", "description": "Standard error response envelope", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "integer", "format": "int32", "description": "HTTP status code", "example": 404, "minimum": 100, "maximum": 599 }, "message": { "type": "string", "description": "Human-readable error message", "example": "Resource not found" }, "details": { "description": "Additional context or validation details", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" }, { "type": "null" } ] } } } } }, "AuthCredentials": { "type": "object", "description": "Login or registration credentials", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "description": "User email", "example": "demo@example.com" }, "password": { "type": "string", "format": "password", "writeOnly": true, "description": "Password (any value accepted in mock)", "example": "any", "minLength": 1 }, "firstName": { "type": "string", "description": "First name (registration only)" }, "lastName": { "type": "string", "description": "Last name (registration only)" }, "username": { "type": "string", "description": "Username (registration only)" } } }, "AuthResponse": { "type": "object", "description": "Authentication response with user profile and token", "required": [ "user", "token", "expiresAt" ], "properties": { "user": { "$ref": "#/components/schemas/User" }, "token": { "type": "string", "description": "Bearer access token (64 hex chars)", "minLength": 64, "maxLength": 64 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration (1 hour)" } } }, "TokenResponse": { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string", "description": "New bearer token", "minLength": 64, "maxLength": 64 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "HealthCheck": { "type": "object", "required": [ "status", "uptime", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "uptime": { "type": "number", "format": "double", "description": "Uptime in seconds" }, "timestamp": { "type": "string", "format": "date-time" }, "memory": { "type": "object", "properties": { "rss": { "type": "string", "example": "45.2 MB" }, "heapUsed": { "type": "string", "example": "22.1 MB" }, "heapTotal": { "type": "string", "example": "30.5 MB" } } }, "data": { "type": "object", "description": "Record counts", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "BatchOperation": { "type": "object", "required": [ "method", "url" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string", "description": "Relative URL path", "example": "/users/1" }, "body": { "type": "object", "description": "Request body (POST/PUT/PATCH)", "additionalProperties": true } } }, "BatchResult": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32", "example": 200 }, "body": { "type": "object", "additionalProperties": true } } }, "UploadResponse": { "type": "object", "required": [ "id", "filename", "url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "example": "document.pdf" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "mimeType": { "type": "string", "example": "application/pdf" }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } } }, "EchoResponse": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "query": { "type": "object", "additionalProperties": true }, "body": { "oneOf": [ { "type": "object" }, { "type": "null" } ] }, "ip": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "DbStats": { "type": "object", "properties": { "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "webhooks": { "type": "integer", "minimum": 0 }, "deliveries": { "type": "integer", "minimum": 0 }, "tokens": { "type": "integer", "minimum": 0 }, "uptime": { "type": "number", "format": "double" }, "memory": { "type": "string", "example": "22.1 MB" } } }, "SeedRequest": { "type": "object", "description": "Custom counts for re-seeding. Omitted resources use defaults.", "properties": { "users": { "type": "integer", "minimum": 0, "description": "Number of users" }, "posts": { "type": "integer", "minimum": 0, "description": "Number of posts" }, "comments": { "type": "integer", "minimum": 0, "description": "Number of comments" }, "todos": { "type": "integer", "minimum": 0, "description": "Number of todos" }, "albums": { "type": "integer", "minimum": 0, "description": "Number of albums" }, "photos": { "type": "integer", "minimum": 0, "description": "Number of photos" }, "categories": { "type": "integer", "minimum": 0, "description": "Number of categories" }, "products": { "type": "integer", "minimum": 0, "description": "Number of products" }, "orders": { "type": "integer", "minimum": 0, "description": "Number of orders" }, "reviews": { "type": "integer", "minimum": 0, "description": "Number of reviews" }, "notifications": { "type": "integer", "minimum": 0, "description": "Number of notifications" } } }, "BasicDemoResponse": { "type": "object", "description": "Response from the HTTP Basic auth demo endpoint", "required": [ "authenticated", "scheme" ], "properties": { "authenticated": { "type": "boolean", "example": true }, "scheme": { "type": "string", "enum": [ "basic" ], "example": "basic" }, "user": { "type": "string", "description": "Username supplied in the Basic header", "example": "demo" } } }, "AdminReport": { "type": "object", "description": "Read-only aggregate report for administrators", "required": [ "generatedAt", "scheme", "totals" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "scheme": { "type": "string", "enum": [ "bearer", "basic" ], "description": "Which auth scheme the caller used" }, "totals": { "type": "object", "description": "Record counts per resource", "additionalProperties": { "type": "integer", "minimum": 0 } }, "webhooks": { "type": "integer", "minimum": 0, "description": "Active webhook subscriptions" }, "activeTokens": { "type": "integer", "minimum": 0, "description": "Bearer tokens currently valid" } } } }, "parameters": { "PathId": { "name": "id", "in": "path", "required": true, "description": "Resource identifier", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "example": 1 }, "PageParam": { "name": "_page", "in": "query", "description": "Page number (1-based)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "LimitParam": { "name": "_limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "StartParam": { "name": "_start", "in": "query", "description": "Slice start index (alternative to page-based)", "schema": { "type": "integer", "minimum": 0 } }, "EndParam": { "name": "_end", "in": "query", "description": "Slice end index (exclusive)", "schema": { "type": "integer", "minimum": 0 } }, "SortParam": { "name": "_sort", "in": "query", "description": "Comma-separated fields to sort by", "schema": { "type": "string" }, "examples": { "single": { "summary": "Single field", "value": "createdAt" }, "multi": { "summary": "Multi-field", "value": "lastName,firstName" } } }, "OrderParam": { "name": "_order", "in": "query", "description": "Sort direction(s), comma-separated", "schema": { "type": "string" }, "examples": { "asc": { "value": "asc" }, "desc": { "value": "desc" }, "mixed": { "summary": "Mixed", "value": "desc,asc" } } }, "SearchParam": { "name": "q", "in": "query", "description": "Full-text search across all string/number/array fields. Leave blank to list everything.", "schema": { "type": "string" }, "examples": { "all": { "summary": "List all (no filter)", "value": "" }, "javascript": { "summary": "Find records containing \"javascript\"", "value": "javascript" } } }, "FieldsParam": { "name": "_fields", "in": "query", "description": "Sparse fieldset — comma-separated fields to return. Leave blank for the full object.", "schema": { "type": "string" }, "examples": { "full": { "summary": "Full object (all fields)", "value": "" }, "slim": { "summary": "id + timestamps only", "value": "id,createdAt,updatedAt" } } }, "ExpandParam": { "name": "_expand", "in": "query", "description": "Expand parent relations inline. Applies only when the resource has a matching parent (e.g. `user` on posts).", "schema": { "type": "string" }, "examples": { "none": { "summary": "No expansion", "value": "" }, "parent": { "summary": "Expand parent where available", "value": "user" } } }, "EmbedParam": { "name": "_embed", "in": "query", "description": "Embed child collections. Applies only when the resource has a matching child (e.g. `comments` on posts).", "schema": { "type": "string" }, "examples": { "none": { "summary": "No embed", "value": "" }, "comments": { "summary": "Embed comments where available", "value": "comments" } } }, "DelayParam": { "name": "_delay", "in": "query", "description": "Artificial delay in ms (max 10000) — test loading states", "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "ErrorParam": { "name": "_error", "in": "query", "description": "Force error response (400–599) — test error handling", "schema": { "type": "integer", "minimum": 400, "maximum": 599 } } }, "headers": { "X-Total-Count": { "description": "Total items matching query (before pagination)", "schema": { "type": "integer" }, "example": 150 }, "X-Page": { "description": "Current page number", "schema": { "type": "integer" } }, "X-Per-Page": { "description": "Items per page", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Unique request identifier (UUID v4)", "schema": { "type": "string", "format": "uuid" } }, "X-Response-Time": { "description": "Server processing time", "schema": { "type": "string", "pattern": "^\\d+ms$" }, "example": "12ms" }, "X-RateLimit-Limit": { "description": "Max requests per window", "schema": { "type": "integer" }, "example": 120 }, "X-RateLimit-Remaining": { "description": "Remaining requests", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Window reset timestamp (ms)", "schema": { "type": "integer", "format": "int64" } }, "Link": { "description": "Pagination links per RFC 8288 (first, prev, next, last)", "schema": { "type": "string" }, "example": "; rel=\"next\"" }, "ETag": { "description": "Entity tag for conditional requests (MD5)", "schema": { "type": "string" }, "example": "\"a1b2c3d4e5f6\"" }, "Location": { "description": "URL of newly created resource", "schema": { "type": "string", "format": "uri-reference" } } }, "responses": { "BadRequest": { "description": "**400** — invalid input or malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 400, "message": "Request body required" } } } } }, "Unauthorized": { "description": "**401** — missing or expired Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 401, "message": "Authentication required" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } } }, "NotFound": { "description": "**404** — resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 404, "message": "users #999 not found" } } } } }, "Conflict": { "description": "**409** — duplicate resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 409, "message": "Email already registered" } } } } }, "PayloadTooLarge": { "description": "**413** — body exceeds 64 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 413, "message": "Request body too large", "details": { "maxSize": "64 KB" } } } } } }, "TooManyRequests": { "description": "**429** — rate limit exceeded (120/60s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "status": 429, "message": "Too many requests", "details": { "retryAfter": 45 } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "InternalError": { "description": "**500** — unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "hex-token", "description": "Obtain via `POST /auth/login`. Include as `Authorization: Bearer `. Expires in 1 hour. Most endpoints work without auth." }, "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic. Mock — any username and password are accepted. Present so docs generators can render the Basic auth block." } }, "links": { "GetUserById": { "operationId": "getUser", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created user" }, "GetPostById": { "operationId": "getPost", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created post" }, "GetCommentById": { "operationId": "getComment", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created comment" }, "GetTodoById": { "operationId": "getTodo", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created todo" }, "GetAlbumById": { "operationId": "getAlbum", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created album" }, "GetPhotoById": { "operationId": "getPhoto", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created photo" }, "GetCategoryById": { "operationId": "getCategory", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created category" }, "GetProductById": { "operationId": "getProduct", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created product" }, "GetOrderById": { "operationId": "getOrder", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created order" }, "GetReviewById": { "operationId": "getReview", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created review" }, "GetNotificationById": { "operationId": "getNotification", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created notification" }, "GetWebhookById": { "operationId": "getWebhook", "parameters": { "id": "$response.body#/id" }, "description": "Retrieve the created webhook" }, "GetWebhookDeliveries": { "operationId": "listWebhookDeliveries", "parameters": { "id": "$response.body#/id" }, "description": "List deliveries for this webhook" } }, "examples": { "UserExample": { "summary": "Example user", "value": { "id": 1, "firstName": "Demo", "lastName": "User", "email": "demo@example.com", "username": "demo", "avatar": "https://i.pravatar.cc/150?u=demo", "phone": "+1-555-000-0001", "address": { "street": "1 Demo Way", "city": "Austin", "state": "TX", "zipCode": "78701", "country": "US", "geo": { "lat": 30.2672, "lng": -97.7431 } }, "company": { "name": "Demo Corp", "catchPhrase": "Seeded for docs and testing." }, "website": "https://example.com/demo", "role": "admin", "age": 30, "bio": "Seeded demo account. Log in with any password.", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2026-04-21T00:00:00.000Z" } }, "PostExample": { "summary": "Example post", "value": { "userId": 1, "title": "TypeScript tips I learned the hard way", "body": "First, never use `any`…", "excerpt": "Ten hard-won lessons from the trenches.", "tags": [ "typescript", "engineering" ], "status": "draft", "id": 1, "createdAt": "2026-01-21T19:36:04.116Z", "updatedAt": "2026-05-01T05:55:47.527Z", "deletedAt": "2026-05-01T05:55:47.527Z" } }, "CommentExample": { "summary": "Example comment", "value": { "id": 1, "postId": 1, "userId": 1, "body": "How does this compare to the approach described in the official docs?", "likes": 16, "createdAt": "2023-04-28T06:59:47.906Z" } }, "TodoExample": { "summary": "Example todo", "value": { "id": 1, "userId": 1, "title": "Configure monitoring", "completed": true, "priority": "low", "dueDate": null, "tags": [], "createdAt": "2024-01-25T00:38:32.919Z" } }, "AlbumExample": { "summary": "Example album", "value": { "userId": 1, "title": "Summer 2026", "id": 1, "createdAt": "2024-07-02T09:01:49.954Z", "updatedAt": "2026-04-23T08:07:12.520Z" } }, "PhotoExample": { "summary": "Example photo", "value": { "id": 1, "albumId": 1, "title": "Photo 1", "url": "https://picsum.photos/seed/1/800/960", "thumbnailUrl": "https://picsum.photos/seed/1/150/150", "width": 800, "height": 960, "size": 4803273, "format": "jpeg", "createdAt": "2026-07-24T20:47:13.121Z" } }, "CategoryExample": { "summary": "Example category", "value": { "id": 1, "name": "Electronics", "slug": "electronics", "description": "Gadgets, devices, and electronic accessories", "image": "https://picsum.photos/seed/cat1/300/200", "productCount": 5, "createdAt": "2022-01-06T04:19:58.076Z" } }, "ProductExample": { "summary": "Example product", "value": { "id": 1, "categoryId": 4, "name": "Desk Lamp", "description": "Ultra-fast connectivity with rock-solid reliability.", "price": 161.28, "originalPrice": 231.38, "currency": "USD", "stock": 257, "sku": "SKU-00001", "rating": 4.4, "reviewCount": 188, "image": "https://picsum.photos/seed/prod1/400/400", "images": [ "https://picsum.photos/seed/prod1-0/400/400", "https://picsum.photos/seed/prod1-1/400/400", "https://picsum.photos/seed/prod1-2/400/400", "https://picsum.photos/seed/prod1-3/400/400", "https://picsum.photos/seed/prod1-4/400/400" ], "weight": 9.19, "dimensions": { "width": 33.4, "height": 40, "depth": 14.6 }, "isAvailable": true, "isFeatured": false, "tags": [ "backend" ], "createdAt": "2024-05-30T01:37:26.059Z", "updatedAt": "2026-12-15T02:55:19.943Z" } }, "OrderExample": { "summary": "Example order", "value": { "id": 1, "userId": 1, "items": [ { "productId": 37, "quantity": 2, "price": 416.97 }, { "productId": 16, "quantity": 2, "price": 478.87 } ], "subtotal": 1791.68, "tax": 143.33, "shipping": 0, "total": 1935.01, "currency": "USD", "status": "pending", "paymentMethod": "credit_card", "shippingAddress": { "street": "6620 Maple Dr", "city": "Fort Worth", "state": "MI", "zipCode": "16372", "country": "US" }, "trackingNumber": "TRK442765071", "notes": null, "createdAt": "2026-04-19T12:16:46.226Z", "updatedAt": "2025-01-30T04:10:54.855Z" } }, "ReviewExample": { "summary": "Example review", "value": { "id": 1, "productId": 1, "userId": 1, "rating": 4, "title": "Works as advertised", "body": "Great article! Really helped me understand the concept better.", "isVerified": true, "helpful": 1, "createdAt": "2025-08-29T18:25:55.906Z" } }, "NotificationExample": { "summary": "Example notification", "value": { "id": 1, "userId": 1, "type": "error", "title": "Error notification", "message": "New follower on your profile.", "read": true, "link": null, "createdAt": "2026-03-23T15:22:15.402Z" } } } } }