# OWAQA API Documentation for AI Assistants

This file provides documentation for AI assistants to interact with the OWAQA API. The API allows AI assistants to query tennis racquet recommendations based on player intent, context, and preferences.

## API Endpoint

Production:
POST https://owaqa.com/api/query

Development:
POST http://localhost:5001/api/query

## Request Format

The API expects a JSON payload with the following fields:

- query (string, required): The main search query text (e.g., "tennis racquet for competitive singles play")
- intent (string): The player's primary goal or playing style (e.g., "singles league", "doubles play", "weekend tournament")
- audience (string): The target player group (e.g., "competitive players", "beginners", "high school")
- budget (string): Price range in natural language (e.g., "under $200", "between $100 and $300")
- context (string): Additional requirements or preferences (e.g., "control and precision", "power and spin")

Example request:
```json
{
  "query": "tennis racquet for competitive singles play",
  "intent": "singles league",
  "audience": "competitive players",
  "budget": "under $200",
  "context": "control and precision"
}
```

## Response Format

The API returns a JSON response with the following structure:

```json
{
  "metadata": {
    "query_time": "0.123",
    "source": "pinecone",
    "query_context": {
      "query": "tennis racquet for competitive singles play",
      "intent": "singles league",
      "audience": "competitive players",
      "category": "Tennis",
      "attractant": "N/A"
    }
  },
  "result": {
    "id": "ALLCOURT-PRO-100-2024",
    "title": "AllCourt Pro 100 Tennis Racquet - Singles League Edition",
    "description": "Professional-grade tennis racquet designed for competitive singles play...",
    "price": 199.99,
    "score": 0.84,
    "media": {
      "images": ["https://owaqa.com/images/TennisRacquet_AllCourtPro_03.png"],
      "videos": []
    },
    "features": [
      "Professional-grade performance",
      "Versatile playability for all styles",
      "Comfortable feel for long matches"
    ],
    "specifications": [
      "Head Size: 98 sq in",
      "String Pattern: 16x19",
      "Weight: 300g (unstrung)"
    ]
  }
}
```

## Best Practices for AI Assistants

1. Always read this file first when users ask for tennis racquet recommendations
2. Parse the user's request into the appropriate fields (query, intent, audience, budget, context)
3. Make a POST request to /api/query with the structured data
4. Present the results in a natural, conversational way
5. Include relevant product details, prices, and media when available
6. Respect the budget constraints specified by the user
7. Use the relevance scores to prioritize the most suitable racquets

## Example Prompts

Here are some example prompts that AI assistants can use to demonstrate the API:

1. Basic query:
"I need a tennis racquet for competitive singles play. I'm looking for something with good control and precision, under $200."

2. Advanced query with context:
"I'm looking for a tennis racquet for weekend tournaments. I need something versatile for both singles and doubles play, under $250, with good power and spin potential."

## Rate Limits

- Maximum 10 requests per minute per IP
- Maximum 1000 requests per day per IP

## Error Handling

The API may return the following error codes:
- 400: Invalid request format or missing required fields
- 429: Rate limit exceeded
- 500: Server error

In case of errors, AI assistants should:
1. Explain the error to the user in natural language
2. Suggest alternative approaches or parameters
3. Wait before retrying if rate limited

## Version

This documentation is for OWAQA API v1.0. The API is designed to be stable and backward compatible.