# tnyvoice API - LLM Integration Guide

## Overview
tnyvoice is a minimalist feedback management system with a simple REST API. This document helps LLMs understand and interact with our API effectively.

## Base URL
Production: https://voice.sury.app/api/v1
Development: http://localhost:3001/api/v1

## Authentication
- Public endpoints: No authentication required
- Protected endpoints: Use API key in header: `X-API-Key: sk_test_...` or `X-API-Key: sk_live_...`

## Core Endpoints

### 1. List Feedback (Public)
GET /feedback?slug={account_slug}

Purpose: Retrieve all feedback items for an account
Response: Array of feedback items with title, description, status, vote_count, created_at

Example:
```
GET https://voice.sury.app/api/v1/feedback?slug=acme
```

### 2. Submit Feedback (Public)
POST /submit

Purpose: Submit new feedback from users
Body:
```json
{
  "slug": "acme",
  "title": "Add dark mode",
  "description": "Would love a dark theme option",
  "email": "user@example.com"
}
```

### 3. Vote on Feedback (Public)
POST /vote

Purpose: Add a vote to feedback item
Body:
```json
{
  "feedback_id": "uuid-here",
  "identifier": "user@example.com"
}
```

### 4. Create Feedback (Protected)
POST /feedback
Header: X-API-Key: your_api_key

Purpose: Create feedback programmatically
Body:
```json
{
  "title": "API-submitted feedback",
  "description": "Details here",
  "status": "new"
}
```

### 5. Update Feedback Status (Protected)
PATCH /feedback/{id}
Header: X-API-Key: your_api_key

Purpose: Update feedback status
Body:
```json
{
  "status": "planned"
}
```

Status values: new, planned, building, shipped, declined

### 6. Delete Feedback (Protected)
DELETE /feedback/{id}
Header: X-API-Key: your_api_key

Purpose: Remove feedback item

## MCP Server Integration

If you're using Model Context Protocol (MCP), tnyvoice provides an MCP server at:
npm: @tnyvoice/mcp-server

### MCP Tools Available:
- `list_feedback`: Get all feedback for an account
- `create_feedback`: Submit new feedback
- `update_status`: Change feedback status
- `vote`: Add vote to feedback
- `get_stats`: Get feedback statistics

### MCP Configuration:
```json
{
  "mcpServers": {
    "tnyvoice": {
      "command": "npx",
      "args": ["@tnyvoice/mcp-server"],
      "env": {
        "TNYFB_API_KEY": "sk_test_...",
        "TNYFB_ACCOUNT_SLUG": "acme"
      }
    }
  }
}
```

## Response Formats

### Success Response
```json
{
  "data": {...},
  "success": true
}
```

### Error Response
```json
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "status": 400
}
```

## Rate Limits
- Unauthenticated: 10 requests/minute
- Authenticated: 60 requests/minute

## Free Tier Limits
- 10 feedback items maximum
- Unlimited votes
- 1 admin user

## Common Use Cases for LLMs

### 1. Summarize Feedback
```
1. GET /feedback?slug=acme
2. Analyze patterns in titles/descriptions
3. Group by theme or feature area
4. Present summary to user
```

### 2. Track Feature Requests
```
1. POST /submit with user's feature request
2. Monitor status changes over time
3. Notify when status changes to "shipped"
```

### 3. Analyze Voting Patterns
```
1. GET /feedback?slug=acme
2. Sort by vote_count
3. Identify trending requests
4. Calculate velocity (votes over time)
```

### 4. Automated Status Updates
```
1. Monitor external systems (GitHub, Jira)
2. PATCH /feedback/{id} when related issue closes
3. Update status to "shipped" automatically
```

## Best Practices for LLMs

1. **Cache Responses**: Feedback lists change infrequently, cache for 1-5 minutes
2. **Batch Operations**: Use the API efficiently, avoid rapid successive calls
3. **Handle Errors Gracefully**: Respect rate limits, retry with exponential backoff
4. **Validate Input**: Ensure required fields are present before API calls
5. **Use Appropriate Status**: Map user intent to correct status values

## Error Codes
- `RATE_LIMIT_EXCEEDED`: Too many requests
- `INVALID_API_KEY`: Authentication failed
- `FREE_TIER_LIMIT`: Maximum items reached
- `NOT_FOUND`: Resource doesn't exist
- `VALIDATION_ERROR`: Invalid input data

## Data Schemas

### Feedback Object
```typescript
{
  id: string (UUID)
  account_id: string (UUID)
  title: string (max 200 chars)
  description?: string (max 1000 chars)
  status: 'new' | 'planned' | 'building' | 'shipped' | 'declined'
  vote_count: number
  submitter_email?: string
  created_at: string (ISO 8601)
  updated_at: string (ISO 8601)
}
```

### Account Object
```typescript
{
  id: string (UUID)
  slug: string (unique, lowercase, 3-50 chars)
  name: string
  tier: 'free' | 'paid'
  feedback_count: number
}
```

## Example Interactions

### "Show me the most requested features"
```javascript
// 1. Fetch feedback
const response = await fetch('https://voice.sury.app/api/v1/feedback?slug=acme');
const { data } = await response.json();

// 2. Sort by votes
const sorted = data.sort((a, b) => b.vote_count - a.vote_count);

// 3. Format top 5
const top5 = sorted.slice(0, 5).map(item =>
  `${item.title} (${item.vote_count} votes)`
);
```

### "Submit feedback about X"
```javascript
// 1. Create feedback
const response = await fetch('https://voice.sury.app/api/v1/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    slug: 'acme',
    title: userInput,
    description: details,
    email: userEmail
  })
});
```

### "What's the status of feature Y?"
```javascript
// 1. Search feedback
const response = await fetch('https://voice.sury.app/api/v1/feedback?slug=acme');
const { data } = await response.json();

// 2. Find matching item
const feature = data.find(item =>
  item.title.toLowerCase().includes(searchTerm.toLowerCase())
);

// 3. Report status
if (feature) {
  return `Status: ${feature.status}, Votes: ${feature.vote_count}`;
}
```

## Integration Tips

1. **For Customer Support Bots**: Use the API to check feature request status and submit new requests
2. **For Analytics Dashboards**: Poll feedback endpoint to track metrics and trends
3. **For Project Management**: Sync feedback status with your PM tools
4. **For Community Engagement**: Share most-voted features in newsletters

## Need Help?

- API Docs: https://voice.sury.app/api-docs
- MCP Server: https://github.com/tnyvoice/mcp-server
- Status Page: https://status.voice.sury.app
- Support: support@voice.sury.app

## Version
API Version: v1
Last Updated: 2025-09-10
Compatibility: OpenAI, Anthropic, Google, Local LLMs

---
Built to be simple. Built to be outgrown.