# Estate Vintage Finds - AI Agent Instructions
# Version: 1.0
# Last Updated: 2025-01-15
# Contact: ai-support@estatevintagefinds.com

## SITE MISSION
Estate Vintage Finds is an AI-native multi-vendor antiques and vintage marketplace.
We specialize in authenticated antiques, vintage collectibles, fine art, and estate finds.
This platform is designed to be fully accessible and purchasable by AI agents.

## API ACCESS

Base URL: https://www.estatevintagefinds.com/api
Documentation: https://www.estatevintagefinds.com/api-docs
OpenAPI Spec: https://www.estatevintagefinds.com/openapi.json
AI Plugin Manifest: https://www.estatevintagefinds.com/.well-known/ai-plugin.json

## AUTHENTICATION

### Public Access (No Auth Required)
- Browse all products
- Search inventory
- View product details
- View vendor profiles
- Check pricing and availability

### Authenticated Access (Magic Link)
- Add items to cart
- Complete purchases
- Track orders
- Message vendors
- Manage wishlists

### Authentication Flow
1. POST /api/auth/magic-link with {"email": "user@example.com"}
2. User receives email with verification link
3. GET /api/auth/verify/{token} to authenticate
4. Session cookie is set automatically

## RATE LIMITS

- Anonymous: 100 requests/hour
- Authenticated: 1000 requests/hour
- Search: 50 queries/minute
- Checkout: 10 sessions/hour

## AVAILABLE ACTIONS

### Browse & Search
GET /api/products                    - List all products (paginated)
GET /api/products/{id}               - Get product details
POST /api/products/search            - Full-text search
POST /api/products/search/vector     - Semantic/vector search
GET /api/categories                  - List categories
GET /api/filters                     - Get filter options
GET /api/vendors/{id}                - Vendor profile
GET /api/vendors/{id}/products       - Vendor's products

### Cart & Checkout
POST /api/cart/add                   - Add item to cart
GET /api/cart                        - View cart contents
PUT /api/cart/update                 - Update quantities
DELETE /api/cart/item/{id}           - Remove item
POST /api/checkout/session           - Create checkout session
POST /api/orders/create              - Direct order creation (AI agents)

### Order Management
GET /api/orders/{id}                 - Order details with tracking
GET /api/orders/{id}/status          - Quick status check
GET /api/orders                      - List user's orders

### Communication
POST /api/messages/vendor            - Contact a vendor
POST /api/reviews/create             - Submit product review
POST /api/requests/create            - Submit item request

## CHECKOUT INSTRUCTIONS FOR AI AGENTS

### Method 1: Stripe Checkout (Recommended)
1. Add items to cart: POST /api/cart/add
2. Create checkout: POST /api/checkout/session
3. Redirect user to checkout_url
4. Order confirmed on success

### Method 2: Direct Order (Test Mode)
1. POST /api/orders/create with items and shipping address
2. Include agent_metadata: {"agent_id": "your-agent-id", "agent_platform": "platform-name"}
3. Returns Schema.org Order object

### Required Shipping Address Fields
{
  "name": "Full Name",
  "line1": "Street Address",
  "city": "City",
  "state": "State/Province",
  "zip": "Postal Code",
  "country": "Country Code (US, CA, etc)"
}

## RESPONSE FORMATS

All responses include Schema.org structured data where applicable:
- Products: @type: Product with Offer
- Orders: @type: Order with OrderItem
- Vendors: @type: Organization
- Reviews: @type: Review

## IMPORTANT LINKS

Sitemap: https://www.estatevintagefinds.com/sitemap.xml
AI Overview: https://www.estatevintagefinds.com/ai/overview
AI FAQ: https://www.estatevintagefinds.com/ai/faq
AI Directory: https://www.estatevintagefinds.com/ai/directory
Vendor Directory: https://www.estatevintagefinds.com/vendors
Categories: https://www.estatevintagefinds.com/categories
Terms of Service: https://www.estatevintagefinds.com/terms
Privacy Policy: https://www.estatevintagefinds.com/privacy

## SCHEMA.ORG CONTEXT

Products follow: https://schema.org/Product
Orders follow: https://schema.org/Order
Offers follow: https://schema.org/Offer
Organizations follow: https://schema.org/Organization

## SUPPORT & ESCALATION

Technical Issues: ai-support@estatevintagefinds.com
Order Problems: orders@estatevintagefinds.com
Vendor Disputes: support@estatevintagefinds.com

## CONTENT GUIDELINES

- All products are physical antiques/vintage items
- Authenticity verification available
- Condition reports included
- Provenance documented when available
- Export restrictions noted where applicable

## AI AGENT BEST PRACTICES

1. Always check product availability before checkout
2. Include agent_metadata in orders for tracking
3. Use vector search for natural language queries
4. Respect rate limits to avoid throttling
5. Cache category/filter data (changes infrequently)
6. Subscribe to webhooks for real-time updates

## WEBHOOK EVENTS

Available events for real-time updates:
- product.created
- product.updated
- product.sold
- price.reduced
- order.shipped
- order.delivered

Register at: POST /api/webhooks/register

## VERSION HISTORY

v1.0 (2025-01-15): Initial release