# Using the CardSight AI API - Feedback API

## Overview
Submit feedback to help improve the CardSight AI catalog. Report data errors, suggest corrections, flag identification issues, or provide general feedback. Feedback can be submitted for specific entities (cards, sets, releases, manufacturers, segments) or for identification results.

## Endpoint Details
- **Base URL**: `https://api.cardsight.ai/v1/feedback/`
- **Authentication**: API Key required (X-Api-Key header)

## Endpoints

| Method | URL | Description |
|--------|-----|-------------|
| POST | /v1/feedback/card/{id} | Submit feedback for a specific card |
| POST | /v1/feedback/set/{id} | Submit feedback for a specific set |
| POST | /v1/feedback/release/{id} | Submit feedback for a specific release |
| POST | /v1/feedback/manufacturer/{id} | Submit feedback for a manufacturer |
| POST | /v1/feedback/segment/{id} | Submit feedback for a segment |
| POST | /v1/feedback/identify/{id} | Submit feedback for an identification result |
| POST | /v1/feedback/general | Submit general feedback (no entity ID required) |

## Request Parameters

### Path Parameters (for entity-specific endpoints)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | UUID | Yes | The unique identifier of the entity |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| feedback_type | string | No | Type of feedback (see values below) |
| message | string | Yes | Feedback message (1-1000 characters) |

### Feedback Types

| Value | Description |
|-------|-------------|
| data_error | Incorrect data (wrong name, year, stats, etc.) |
| missing_data | Missing information that should be included |
| suggestion | Suggestion for improvement |
| bug | Technical issue or bug |
| other | Other feedback not fitting above categories |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

// Submit feedback for a card
const cardFeedback = await client.feedback.card('550e8400-e29b-41d4-a716-446655440000', {
  feedback_type: 'data_error',
  message: 'Player name is misspelled - should be "Mike Trout" not "Mike Truot"'
})

if (cardFeedback.error) {
  console.error('Error:', cardFeedback.error)
} else {
  console.log('Feedback submitted successfully!')
  console.log(`Feedback ID: ${cardFeedback.data.data.unique_id}`)
  console.log(`Status: ${cardFeedback.data.data.status}`)
}

// Submit feedback for a set
const setFeedback = await client.feedback.set('550e8400-e29b-41d4-a716-446655440001', {
  feedback_type: 'missing_data',
  message: 'Set is missing cards #45-50 which exist in the physical product'
})

// Submit feedback for a release
const releaseFeedback = await client.feedback.release('550e8400-e29b-41d4-a716-446655440002', {
  feedback_type: 'data_error',
  message: 'Release year should be 2023, not 2022'
})

// Submit feedback for an identification result
const identifyFeedback = await client.feedback.identify('550e8400-e29b-41d4-a716-446655440003', {
  feedback_type: 'data_error',
  message: 'AI identified wrong card - this is actually a 1989 Topps, not 1990 Topps'
})

// Submit general feedback (no entity ID needed)
const generalFeedback = await client.feedback.general({
  feedback_type: 'suggestion',
  message: 'Would love to see support for graded card tracking'
})
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')

# Submit feedback for a card
response = client.feedback.card(
    '550e8400-e29b-41d4-a716-446655440000',
    feedback_type='data_error',
    message='Player name is misspelled - should be "Mike Trout" not "Mike Truot"'
)

print(f"Feedback ID: {response.data.unique_id}")
print(f"Status: {response.data.status}")

# Submit feedback for a set
client.feedback.set(
    '550e8400-e29b-41d4-a716-446655440001',
    feedback_type='missing_data',
    message='Set is missing cards #45-50'
)

# Submit feedback for identification
client.feedback.identify(
    '550e8400-e29b-41d4-a716-446655440003',
    feedback_type='data_error',
    message='AI identified wrong card'
)

# Submit general feedback
client.feedback.general(
    feedback_type='suggestion',
    message='Would love to see graded card tracking'
)
```

## Direct API Calls (cURL)

```bash
# Submit feedback for a card
curl -X POST "https://api.cardsight.ai/v1/feedback/card/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type": "data_error", "message": "Player name should be Mike Trout not Mike Truot"}'

# Submit feedback for a set
curl -X POST "https://api.cardsight.ai/v1/feedback/set/550e8400-e29b-41d4-a716-446655440001" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type": "missing_data", "message": "Set is missing cards #45-50"}'

# Submit feedback for a release
curl -X POST "https://api.cardsight.ai/v1/feedback/release/550e8400-e29b-41d4-a716-446655440002" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type": "data_error", "message": "Release year should be 2023, not 2022"}'

# Submit feedback for identification result
curl -X POST "https://api.cardsight.ai/v1/feedback/identify/550e8400-e29b-41d4-a716-446655440003" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type": "data_error", "message": "AI identified wrong card"}'

# Submit general feedback
curl -X POST "https://api.cardsight.ai/v1/feedback/general" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type": "suggestion", "message": "Would love to see graded card tracking"}'
```

## Example Response
```json
{
  "success": true,
  "message": "Feedback submitted successfully",
  "data": {
    "unique_id": "550e8400-e29b-41d4-a716-446655440099",
    "entity_type": "card",
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "feedback_type": "data_error",
    "message": "Player name should be Mike Trout not Mike Truot",
    "status": "not_reviewed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## Response Fields

### FeedbackSubmitResponse

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| success | boolean | Yes | Whether the submission was successful |
| message | string | Yes | Human-readable status message |
| data | object | Yes | The created feedback record |

### Feedback Object (data)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| unique_id | UUID | Yes | Unique identifier for this feedback |
| entity_type | string | Yes | Type of entity: card, set, release, manufacturer, segment, identify, general |
| entity_id | UUID | Yes | ID of the entity (null for general feedback) |
| feedback_type | string | No | Type of feedback submitted |
| message | string | Yes | The feedback message |
| status | string | Yes | Current review status |
| created_at | string | Yes | ISO 8601 timestamp when created |
| updated_at | string | Yes | ISO 8601 timestamp when last updated |

### Feedback Status Values

| Status | Description |
|--------|-------------|
| not_reviewed | Feedback has been received but not yet reviewed |
| under_review | Feedback is being reviewed by the team |
| fixed | The issue has been corrected |
| wont_fix | Issue will not be addressed (with explanation) |
| duplicate | Same issue already reported |
| need_info | More information needed from submitter |

## Rate Limiting

- Maximum **50 feedback submissions per day** per API key
- **Duplicate detection**: Same feedback message for the same entity within 1 hour will be rejected

## Common Use Cases
- Report incorrect player names, card numbers, or years
- Flag missing cards or sets in the catalog
- Report AI identification errors
- Suggest new features or improvements
- Report technical bugs or issues

## Tips for AI Assistants
- **Working with IDs:** The release, set, and card UUIDs you submit feedback for come from catalog, search, or identify calls. Caching them briefly to fulfill a user's request is expected and fine — it's why the image and other free endpoints exist. If you need to save cards for the long term, add them to a **list or collection**: those are your own stable resources, purpose-built for holding cards. If you need a bulk or offline copy of catalog data, reach out to us at `support@cardsight.ai` so we can help with your use case.
- The SDK returns `{ data, error }` - always check for errors first
- Entity-specific endpoints require a valid UUID for an existing entity
- The `feedback_type` field is optional but helps categorize feedback
- The `message` field is required and must be 1-1000 characters
- For identification feedback, use the `requestId` from the identify response as the `id`
- General feedback (`/v1/feedback/general`) doesn't require an entity ID
- Feedback is reviewed by the CardSight team and status updates over time
- Be specific in feedback messages to help the team understand the issue