# Playground API — Full AI Technical Reference Specification

Base API Endpoint: /api/v1
Documentation Site: https://playground-api-xi.vercel.app
Version: v1

## Resource: Users
Description: User profile records with names, usernames, emails, address details, and avatar seeds.
Base Path: /api/v1/users

### GET /users
Title: List All Users
Description: Retrieve a paginated list of users. Results merge shared global user records with session sandbox overlays (newly created users appear at the top).
Query Parameters:
  - page (integer): Page number (1-indexed).
  - limit (integer): Number of records per page (default 10, max 30).
  - q (string): Full-text search query term across name, username, email.
  - _sort (string): Field name to sort results by (name, username, email).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": "local-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Doe",
      "username": "janedoe",
      "email": "jane.doe@example.com",
      "_sandbox": "created"
    },
    {
      "id": 1,
      "name": "Leanne Graham",
      "username": "Bret",
      "email": "Sincere@april.biz",
      "phone": "+1-770-555-0123",
      "website": "hildegard.org"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

### GET /users/:id
Title: Get Single User
Description: Retrieve a single user by ID. Supports plain integer IDs for global records (e.g. 1) and string IDs formatted as local-<uuid> for sandbox records.
Query Parameters:
  - id (string | integer): User ID (global integer or local-<uuid>).
Response Example:
```json
{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "phone": "+1-770-555-0123",
  "website": "hildegard.org",
  "address": {
    "street": "Kulas Light",
    "city": "Gwenborough",
    "zipcode": "92998-3874"
  },
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net"
  }
}
```

### POST /users
Title: Create New User
Description: Create a new session sandbox user record. Returns a local-<uuid> formatted ID with _sandbox: "created". Capped at 30 custom created records per session.
Request Body Example:
```json
{
  "name": "Jane Doe",
  "username": "janedoe",
  "email": "jane.doe@example.com",
  "phone": "+1-555-01999",
  "website": "https://janedoe.dev"
}
```
Response Example:
```json
{
  "id": "local-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Jane Doe",
  "username": "janedoe",
  "email": "jane.doe@example.com",
  "_sandbox": "created"
}
```

### PUT /users/:id
Title: Replace User (PUT)
Description: Replace an existing user record in the session overlay. Global baseline records remain untouched for all other developers.
Request Body Example:
```json
{
  "name": "Leanne Graham (Updated)",
  "username": "Bret",
  "email": "bret.updated@april.biz",
  "website": "https://updated-user.dev"
}
```
Response Example:
```json
{
  "id": 1,
  "name": "Leanne Graham (Updated)",
  "username": "Bret",
  "email": "bret.updated@april.biz",
  "website": "https://updated-user.dev",
  "_sandbox": "updated"
}
```

### PATCH /users/:id
Title: Partial User Update (PATCH)
Description: Partially update specific profile fields of a user record in your session overlay.
Request Body Example:
```json
{
  "name": "Leanne Graham (Patched)",
  "website": "https://patched-user.dev"
}
```
Response Example:
```json
{
  "id": 1,
  "name": "Leanne Graham (Patched)",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "website": "https://patched-user.dev",
  "_sandbox": "updated"
}
```

### DELETE /users/:id
Title: Delete User
Description: Remove a user record from your session view. The underlying global baseline record is unaffected for other users.
Response Example:
```json
204 No Content
```

### GET /users/:userId/posts
Title: Get User Posts Sub-Resource
Description: Retrieve all blog posts authored by a specific user with full pagination, search query, and sorting support.
Query Parameters:
  - userId (string | integer): Author user ID (e.g. 1 or local-<uuid>).
  - page (integer): Page number (1-indexed).
  - limit (integer): Number of posts per page.
  - q (string): Search term across post title and body.
  - _sort (string): Field name to sort by (title, id, created_at).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
      "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum reprehenderit molestiae ut ut quas totam nostrum rerum est autem sunt rem eveniet architecto"
    },
    {
      "id": 2,
      "user_id": 1,
      "title": "qui est esse",
      "body": "est rerum tempore vitae sequi sint nihil reprehenderit dolor beatae ea dolores neque fugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 4,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
```

### GET /users/:userId/todos
Title: Get User Todos Sub-Resource
Description: Retrieve all task todos assigned to a specific user, with optional completion status filtering.
Query Parameters:
  - userId (string | integer): Owner user ID (e.g. 1 or local-<uuid>).
  - completed (boolean): Filter tasks by completion status (true or false).
  - page (integer): Page number (1-indexed).
  - limit (integer): Number of todos per page.
  - _sort (string): Field name to sort by (title, id, completed).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "title": "delectus aut autem",
      "completed": false
    },
    {
      "id": 2,
      "user_id": 1,
      "title": "quis ut nam facilis et officia qui",
      "completed": false
    },
    {
      "id": 3,
      "user_id": 1,
      "title": "fugiat veniam minus",
      "completed": false
    },
    {
      "id": 4,
      "user_id": 1,
      "title": "et porro tempora",
      "completed": true
    },
    {
      "id": 5,
      "user_id": 1,
      "title": "laboriosam mollitia et enim quasi adipisci quia provident illum",
      "completed": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
```

## Resource: Posts
Description: Blog post articles containing title, body, user association, created dates, and full-text search indexing.
Base Path: /api/v1/posts

### GET /posts
Title: List All Posts
Description: Retrieve a paginated list of posts. Results merge shared global posts with session sandbox overlays (newly created posts appear at the top).
Query Parameters:
  - page (integer): Page number (1-indexed).
  - limit (integer): Number of records per page (default 10, max 30).
  - user_id (integer): Filter posts authored by user ID (e.g. user_id=1).
  - q (string): Full-text search query term across title and body.
  - _sort (string): Field name to sort results by (title, id, created_at).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": "local-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "user_id": 1,
      "title": "Getting Started with Playground API",
      "body": "Playground API provides instant sandboxed mock endpoints...",
      "_sandbox": "created"
    },
    {
      "id": 1,
      "user_id": 1,
      "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
      "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

### GET /posts/:id
Title: Get Single Post
Description: Retrieve details of a specific post by integer ID or local sandbox string ID.
Query Parameters:
  - id (string | integer): Post ID (global integer or local-<uuid>).
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum reprehenderit molestiae ut ut quas totam nostrum rerum est autem sunt rem eveniet architecto"
}
```

### POST /posts
Title: Create Post
Description: Create a new post in your session overlay. Capped at 30 custom created records per session.
Request Body Example:
```json
{
  "user_id": 1,
  "title": "Getting Started with Playground API",
  "body": "Playground API provides instant sandboxed mock endpoints with per-session mutation overlays."
}
```
Response Example:
```json
{
  "id": "local-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "user_id": 1,
  "title": "Getting Started with Playground API",
  "body": "Playground API provides instant sandboxed mock endpoints with per-session mutation overlays.",
  "_sandbox": "created"
}
```

### PUT /posts/:id
Title: Replace Post (PUT)
Description: Replace an existing post record in the session overlay while preserving global baseline position.
Request Body Example:
```json
{
  "user_id": 1,
  "title": "Getting Started with Playground API (Updated Edition)",
  "body": "Full replacement content body text."
}
```
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "Getting Started with Playground API (Updated Edition)",
  "body": "Full replacement content body text.",
  "_sandbox": "updated"
}
```

### PATCH /posts/:id
Title: Partial Post Update (PATCH)
Description: Update specific fields (such as title or body text) of an existing post.
Request Body Example:
```json
{
  "title": "Getting Started with Playground API (Patched)"
}
```
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "Getting Started with Playground API (Patched)",
  "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum reprehenderit molestiae...",
  "_sandbox": "updated"
}
```

### DELETE /posts/:id
Title: Delete Post
Description: Remove a post record from your session overlay view.
Response Example:
```json
204 No Content
```

### GET /posts/:postId/comments
Title: Get Post Comments Sub-Resource
Description: Retrieve all comments linked relationally to a specific blog post.
Query Parameters:
  - postId (string | integer): Target post ID (e.g. 1 or local-<uuid>).
  - page (integer): Page number (1-indexed).
  - limit (integer): Number of comments per page.
  - q (string): Search term across comment body.
Response Example:
```json
{
  "data": [
    {
      "id": 1,
      "post_id": 1,
      "name": "id labore ex et quam laborum",
      "email": "Eliseo@gardner.biz",
      "body": "laudantium enim quasi est quidem magnam voluptate ipsam eos"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
```

## Resource: Comments
Description: Feedback comments linked relationally to blog posts.
Base Path: /api/v1/comments

### GET /comments
Title: List All Comments
Description: Retrieve a paginated list of comments across posts with full-text search and sorting.
Query Parameters:
  - post_id (integer): Filter comments linked to post ID.
  - page (integer): Page number.
  - limit (integer): Items per page (max 30).
  - q (string): Search term across name, email, body.
  - _sort (string): Field name to sort by (name, email, id).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": 1,
      "post_id": 1,
      "name": "id labore ex et quam laborum",
      "email": "Eliseo@gardner.biz",
      "body": "laudantium enim quasi est quidem magnam voluptate ipsam eos"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 300,
    "totalPages": 30,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

### GET /comments/:id
Title: Get Single Comment
Description: Retrieve a single comment by global integer ID or session sandbox local-<uuid> ID.
Query Parameters:
  - id (string | integer): Comment ID (global integer or local-<uuid>).
Response Example:
```json
{
  "id": 1,
  "post_id": 1,
  "name": "id labore ex et quam laborum",
  "email": "Eliseo@gardner.biz",
  "body": "laudantium enim quasi est quidem magnam voluptatem aut eveniet quas aliquid sint expedita consequuntur alias ea quam expedita possimus"
}
```

### POST /comments
Title: Create Comment
Description: Add a new comment overlay linked to a post in your session view.
Request Body Example:
```json
{
  "post_id": 1,
  "name": "Awesome API Prototyping Tool",
  "email": "developer@playground.dev",
  "body": "Saved time building my Next.js client app!"
}
```
Response Example:
```json
{
  "id": "local-9b1deb4d-3b7d-4bad",
  "post_id": 1,
  "name": "Awesome API Prototyping Tool",
  "email": "developer@playground.dev",
  "body": "Saved time building my Next.js client app!",
  "_sandbox": "created"
}
```

### PUT /comments/:id
Title: Replace Comment (PUT)
Description: Replace an existing comment record in your session overlay.
Request Body Example:
```json
{
  "post_id": 1,
  "name": "Updated Reviewer Name",
  "email": "reviewer.updated@example.com",
  "body": "Updated detailed comment feedback."
}
```
Response Example:
```json
{
  "id": 1,
  "post_id": 1,
  "name": "Updated Reviewer Name",
  "email": "reviewer.updated@example.com",
  "body": "Updated detailed comment feedback.",
  "_sandbox": "updated"
}
```

### PATCH /comments/:id
Title: Partial Comment Update (PATCH)
Description: Partially update selected fields (such as body text or reviewer name) of a comment.
Request Body Example:
```json
{
  "body": "Patched feedback comment body."
}
```
Response Example:
```json
{
  "id": 1,
  "post_id": 1,
  "name": "id labore ex et quam laborum",
  "email": "Eliseo@gardner.biz",
  "body": "Patched feedback comment body.",
  "_sandbox": "updated"
}
```

### DELETE /comments/:id
Title: Delete Comment
Description: Remove a comment from your session overlay view.
Response Example:
```json
204 No Content
```

## Resource: Todos
Description: Task item records with completion status.
Base Path: /api/v1/todos

### GET /todos
Title: List All Todos
Description: Retrieve a paginated list of task todos with user filtering, completion status, and sorting.
Query Parameters:
  - user_id (integer): Filter by owner user ID.
  - completed (boolean): Filter by completion state (true/false).
  - page (integer): Page number.
  - limit (integer): Items per page (max 30).
  - q (string): Full-text search query term across title.
  - _sort (string): Field name to sort by (title, id, completed).
  - _order (string): Sort direction: asc or desc.
Response Example:
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "title": "delectus aut autem",
      "completed": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 125,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

### GET /todos/:id
Title: Get Single Todo
Description: Retrieve a single todo item by integer ID or local sandbox string ID.
Query Parameters:
  - id (string | integer): Todo ID (global integer or local-<uuid>).
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "delectus aut autem",
  "completed": false
}
```

### POST /todos
Title: Create Todo Task
Description: Create a new todo item in your session sandbox overlay.
Request Body Example:
```json
{
  "user_id": 1,
  "title": "Build Next.js Frontend App",
  "completed": false
}
```
Response Example:
```json
{
  "id": "local-7a6b5c4d-3e2f",
  "user_id": 1,
  "title": "Build Next.js Frontend App",
  "completed": false,
  "_sandbox": "created"
}
```

### PUT /todos/:id
Title: Replace Todo (PUT)
Description: Replace an existing todo task record in your session overlay.
Request Body Example:
```json
{
  "user_id": 1,
  "title": "Build Next.js Frontend App (Completed)",
  "completed": true
}
```
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "Build Next.js Frontend App (Completed)",
  "completed": true,
  "_sandbox": "updated"
}
```

### PATCH /todos/:id
Title: Partial Todo Update (PATCH)
Description: Toggle completion status or edit the title of an existing todo.
Request Body Example:
```json
{
  "completed": true
}
```
Response Example:
```json
{
  "id": 1,
  "user_id": 1,
  "title": "delectus aut autem",
  "completed": true,
  "_sandbox": "updated"
}
```

### DELETE /todos/:id
Title: Delete Todo Task
Description: Remove a todo item from your session overlay view.
Response Example:
```json
204 No Content
```

## Resource: Authentication
Description: Fake JWT authentication login, user registration, token refresh, and profile inspection.
Base Path: /api/v1/auth

### POST /auth/login
Title: Fake JWT Login
Description: Authenticate user with username/email & password to receive signed JWT access and refresh tokens.
Request Body Example:
```json
{
  "username": "Bret",
  "password": "password123"
}
```
Response Example:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz"
  }
}
```

### POST /auth/register
Title: Register Mock User
Description: Register a new session user and immediately receive signed JWT tokens.
Request Body Example:
```json
{
  "name": "Alice Smith",
  "username": "alice",
  "email": "alice@example.com",
  "password": "password123"
}
```
Response Example:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "local-9b1deb4d",
    "name": "Alice Smith",
    "username": "alice",
    "email": "alice@example.com"
  }
}
```

### POST /auth/refresh
Title: Refresh Access Token
Description: Exchange a valid refresh token for a fresh 15-minute Bearer access token.
Request Body Example:
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEs..."
}
```
Response Example:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEs...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

### GET /auth/me
Title: Get Authenticated Profile
Description: Retrieve current authenticated user profile using Authorization: Bearer <access_token>.
Response Example:
```json
{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "phone": "+1-770-555-0123",
  "website": "hildegard.org"
}
```

### PATCH /auth/me
Title: Update Authenticated Profile (PATCH)
Description: Update profile information for the current user using Authorization: Bearer <access_token>.
Request Body Example:
```json
{
  "name": "Leanne Graham (Verified Developer)",
  "website": "https://developer-verified.io"
}
```
Response Example:
```json
{
  "id": 1,
  "name": "Leanne Graham (Verified Developer)",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "website": "https://developer-verified.io",
  "_sandbox": "updated"
}
```

## Resource: Custom Collections
Description: Dynamic custom resource collections (e.g. /custom/products, /custom/orders) created on the fly.
Base Path: /api/v1/custom

### GET /custom
Title: List Active Custom Collections
Description: Returns a summary of all active dynamic custom resource collections in your session sandbox with record counts.
Response Example:
```json
{
  "totalCollections": 2,
  "collections": [
    {
      "name": "products",
      "endpoint": "/custom/products",
      "count": 3,
      "lastUpdated": "2026-08-07T00:00:00.000Z"
    },
    {
      "name": "orders",
      "endpoint": "/custom/orders",
      "count": 2,
      "lastUpdated": "2026-08-07T00:00:00.000Z"
    }
  ]
}
```

### POST /custom/seed
Title: Seed Domain Mock Data Template
Description: Instantly populates pre-built domain collections into your session sandbox with one request (templates: ecommerce, saas, blog, crm).
Query Parameters:
  - template (string): Domain template name ("ecommerce", "saas", "blog", "crm").
Request Body Example:
```json
{
  "template": "ecommerce"
}
```
Response Example:
```json
{
  "message": "Seeded 5 records across custom collections: products, orders.",
  "template": "ecommerce",
  "collections": [
    "products",
    "orders"
  ],
  "totalSeeded": 5
}
```

### GET /custom/:collection
Title: Query Custom Collection Items
Description: Retrieves a paginated list of items from any dynamic custom collection with search and sorting.
Query Parameters:
  - collection (string): Custom collection name (e.g. products, orders, leads).
  - page (integer): Page number (default 1).
  - limit (integer): Records per page (default 10).
  - q (string): Case-insensitive full-text search term.
  - _sort (string): Field name to sort by.
  - _order (string): Sort direction (asc or desc).
Response Example:
```json
{
  "data": [
    {
      "id": "local-f9e8d7c6-5432-10ab",
      "name": "MacBook Pro M3 Max",
      "price": 3499,
      "category": "Laptops",
      "createdAt": "2026-08-07T00:00:00.000Z",
      "_sandbox": "created"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
```

### GET /custom/:collection/:id
Title: Get Single Custom Record
Description: Retrieve a single custom collection record by collection name and string or integer ID.
Query Parameters:
  - collection (string): Custom collection name.
  - id (string): Record ID.
Response Example:
```json
{
  "id": "local-f9e8d7c6-5432-10ab",
  "name": "MacBook Pro M3 Max",
  "price": 3499,
  "category": "Laptops",
  "createdAt": "2026-08-07T00:00:00.000Z",
  "_sandbox": "created"
}
```

### POST /custom/:collection
Title: Create Custom Collection Record
Description: Creates a new custom record in any arbitrary collection with automatic ID, createdAt, and updatedAt metadata attachment.
Query Parameters:
  - collection (string): Custom collection name (e.g. products, orders).
Request Body Example:
```json
{
  "name": "MacBook Pro M3",
  "price": 2499,
  "category": "Laptops"
}
```
Response Example:
```json
{
  "id": "local-f9e8d7c6-5432-10ab",
  "name": "MacBook Pro M3",
  "price": 2499,
  "category": "Laptops",
  "createdAt": "2026-08-07T00:00:00.000Z",
  "_sandbox": "created"
}
```

### PUT /custom/:collection/:id
Title: Replace Custom Record (PUT)
Description: Completely replace a custom record inside the specified collection.
Query Parameters:
  - collection (string): Custom collection name.
  - id (string): Record ID to replace.
Request Body Example:
```json
{
  "name": "MacBook Pro M3 (Updated Spec)",
  "price": 2699,
  "category": "Laptops",
  "ram": "64GB"
}
```
Response Example:
```json
{
  "id": "local-f9e8d7c6-5432-10ab",
  "name": "MacBook Pro M3 (Updated Spec)",
  "price": 2699,
  "category": "Laptops",
  "ram": "64GB",
  "updatedAt": "2026-08-07T00:01:00.000Z",
  "_sandbox": "updated"
}
```

### PATCH /custom/:collection/:id
Title: Partial Custom Update (PATCH)
Description: Partially merge specific fields into an existing custom collection record.
Query Parameters:
  - collection (string): Custom collection name.
  - id (string): Record ID to update.
Request Body Example:
```json
{
  "price": 2299,
  "onSale": true
}
```
Response Example:
```json
{
  "id": "local-f9e8d7c6-5432-10ab",
  "name": "MacBook Pro M3",
  "price": 2299,
  "category": "Laptops",
  "onSale": true,
  "updatedAt": "2026-08-07T00:02:00.000Z",
  "_sandbox": "updated"
}
```

### DELETE /custom/:collection/:id
Title: Delete Custom Collection Record
Description: Removes a custom record from your session sandbox collection.
Query Parameters:
  - collection (string): Custom collection name.
  - id (string): Record ID to delete.
Response Example:
```json
{
  "message": "Record 'local-f9e8d7c6-5432-10ab' removed from custom collection 'products'"
}
```

## Resource: Media & Avatars
Description: Dynamic SVG avatar vectors and landscape image thumbnail generators with deterministic gradient backgrounds.
Base Path: /api/v1/avatars

### GET /avatars/:seed
Title: Generate Dynamic SVG Avatar
Description: Generates a crisp, colorful vector SVG avatar based on a seed string (username, email, or ID) with deterministic gradient background and initials.
Query Parameters:
  - seed (string): Seed string used for color hashing and initials (e.g. Bret, jane.doe@example.com).
  - size (integer): Avatar size in pixels (32 to 512).
  - rounded (boolean): Whether to render circular or rounded squircle border.
Response Example:
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
  <defs>
    <linearGradient id="grad-12345" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#059669" />
      <stop offset="100%" stop-color="#0d9488" />
    </linearGradient>
  </defs>
  <rect width="128" height="128" rx="64" fill="url(#grad-12345)" />
  <text x="50%" y="54%" font-family="Inter, sans-serif" font-size="54" font-weight="700" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">BR</text>
</svg>
```

### GET /avatars/:seed.svg
Title: Generate Avatar with Explicit .svg Extension
Description: Alias endpoint allowing direct <img> tag embedding with explicit file extensions for HTML frameworks and Markdown files.
Query Parameters:
  - seed (string): Seed string (e.g. alice, user-1).
  - size (integer): Avatar dimensions in pixels.
Response Example:
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
  <defs>
    <linearGradient id="grad-67890" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#4f46e5" />
      <stop offset="100%" stop-color="#7c3aed" />
    </linearGradient>
  </defs>
  <rect width="128" height="128" rx="64" fill="url(#grad-67890)" />
  <text x="50%" y="54%" font-family="Inter, sans-serif" font-size="54" font-weight="700" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">AL</text>
</svg>
```

### GET /thumbnails/:seed
Title: Generate Dynamic Landscape Thumbnail
Description: Generates a vector SVG placeholder image with mesh gradient background, custom text, and dimension badge.
Query Parameters:
  - seed (string): Seed string for mesh gradient color hashing.
  - width (integer): Image width in pixels (100 to 1920).
  - height (integer): Image height in pixels (100 to 1080).
  - text (string): Custom text to display instead of formatted seed.
Response Example:
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400" width="600" height="400">
  <defs>
    <linearGradient id="thumb-grad-99" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#4f46e5" />
      <stop offset="100%" stop-color="#7c3aed" />
    </linearGradient>
  </defs>
  <rect width="600" height="400" fill="url(#thumb-grad-99)" />
  <text x="50%" y="46%" font-family="Inter, sans-serif" font-size="33" font-weight="700" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">Post #1</text>
  <rect x="255" y="210" width="90" height="22" rx="11" fill="rgba(0,0,0,0.25)" />
  <text x="50%" y="221" font-family="Inter, sans-serif" font-size="11" font-weight="600" fill="rgba(255,255,255,0.85)" text-anchor="middle" dominant-baseline="middle">600 × 400</text>
</svg>
```

### GET /thumbnails/:seed.svg
Title: Generate Landscape Thumbnail (.svg)
Description: Vector SVG landscape placeholder image with explicit .svg extension for direct embedding in cards and article previews.
Query Parameters:
  - seed (string): Seed string for color hashing.
  - width (integer): Width in pixels.
  - height (integer): Height in pixels.
  - text (string): Custom overlay label text.
Response Example:
```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 450" width="800" height="450">
  <defs>
    <linearGradient id="thumb-grad-77" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#059669" />
      <stop offset="100%" stop-color="#0d9488" />
    </linearGradient>
  </defs>
  <rect width="800" height="450" fill="url(#thumb-grad-77)" />
  <text x="50%" y="46%" font-family="Inter, sans-serif" font-size="44" font-weight="700" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">Featured Article</text>
</svg>
```

## Resource: Session Sandbox
Description: Export, import, and reset operations for identity session overlays.
Base Path: /api/v1/session

### GET /session/export
Title: Export Session Sandbox Snapshot JSON
Description: Serializes all session sandbox overlay records (creates, updates, deletes) into a downloadable JSON snapshot file for backups or team sharing.
Response Example:
```json
{
  "version": "1.0",
  "identityId": "550e8400-e29b-41d4-a716-446655440000",
  "stats": {
    "totalRecords": 2,
    "creates": 1,
    "updates": 1,
    "deletes": 0
  }
}
```

### DELETE /session/reset
Title: Purge Session Sandbox Overlay
Description: Purges all created, updated, and deleted overlay mutations for your session identity, resetting your view to clean baseline global data.
Response Example:
```json
{
  "message": "Session sandbox overlay purged successfully.",
  "purgedRecords": 3
}
```