# Promptster API Documentation

Welcome to the Promptster Public API! Test and compare AI prompts programmatically across multiple providers (OpenAI, Anthropic, Google, DeepSeek, xAI, Groq, Mistral, Perplexity, Together AI) with a single unified API.

---

## Quick Start (5 Minutes)

### 1. Get Your API Key

Visit [/developer/api-keys](https://www.promptster.dev/developer/api-keys) and create a new API key:

- **Test keys**: Free, limited to 5 requests/minute (perfect for development)
- **Live keys**: Based on your plan (see Rate Limits below)

Copy your key immediately - you'll only see it once!

### 2. Get Provider API Keys

You'll need API keys from the AI providers you want to use:

- [OpenAI](https://platform.openai.com/api-keys) - For GPT models
- [Anthropic](https://console.anthropic.com/) - For Claude models
- [Google AI](https://makersuite.google.com/app/apikey) - For Gemini models
- [DeepSeek](https://platform.deepseek.com/api_keys) - For DeepSeek models
- [xAI](https://console.x.ai/) - For Grok models
- [Groq](https://console.groq.com/keys) - For Groq-hosted models
- [Mistral](https://console.mistral.ai/api-keys/) - For Mistral models
- [Perplexity](https://www.perplexity.ai/settings/api) - For Sonar models
- [Together AI](https://api.together.xyz/settings/api-keys) - For open-source models

### 3. Make Your First Request

```bash
curl -X POST https://www.promptster.dev/v1/prompts/test \
  -H "Authorization: Bearer YOUR_PROMPTSTER_KEY" \
  -H "X-ANTHROPIC-API-KEY: YOUR_ANTHROPIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "prompt": "Say hello in exactly 5 words"
  }'
```

### 4. See the Response

```json
{
  "id": "test_abc123def456",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "prompt": "Say hello in exactly 5 words",
  "response": "Hello there, how are you?",
  "metadata": {
    "input_tokens": 13,
    "output_tokens": 8,
    "total_tokens": 21,
    "response_time_ms": 1847,
    "tokens_per_second": 4.3,
    "estimated_cost": 0.000105
  },
  "created_at": "2026-01-25T12:34:56.789Z"
}
```

**That's it!** You just tested an AI prompt and got detailed performance metrics including cost estimation.

---

## Key Features

### 🎯 Single Unified API
One API for all 11 providers - no need to integrate with multiple different APIs

### 💰 Transparent Cost Tracking
Every response includes accurate cost estimates based on real provider pricing

### ⚡ Performance Metrics
Track response time, tokens/second, and token usage for every request

### 🔄 Easy Comparisons
Test the same prompt across multiple providers in parallel with a single API call

### 📊 Usage Analytics
Monitor your API usage, costs, and request history

### 🤖 MCP for AI Editors
Connect Claude Code, Cursor, or Windsurf to test prompts directly from your editor via MCP

### 🔒 Secure & Rate Limited
SHA-256 hashed API keys with tiered rate limiting to protect your quota

---

## Core Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| [/v1/prompts/test](endpoints/test-prompt.md) | POST | Test a single prompt with one provider |
| [/v1/prompts/compare](endpoints/compare-prompts.md) | POST | Compare the same prompt across multiple providers |
| [/v1/usage](endpoints/usage.md) | GET | Get your current usage statistics and limits |
| [/v1/history](endpoints/history.md) | GET | Retrieve your past API requests with filtering |
| [MCP Server](mcp-integration.md) | POST | Connect AI coding assistants via Model Context Protocol |

## Schedule Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| [/v1/schedules](endpoints/schedules.md) | GET | List all scheduled tests |
| [/v1/schedules](endpoints/schedules.md#post-v1schedules) | POST | Create a new scheduled test |
| [/v1/schedules/:id](endpoints/schedules.md#get-v1schedulesid) | GET | Get schedule details |
| [/v1/schedules/:id](endpoints/schedules.md#patch-v1schedulesid) | PATCH | Update a schedule |
| [/v1/schedules/:id](endpoints/schedules.md#delete-v1schedulesid) | DELETE | Delete a schedule |
| [/v1/schedules/:id/run](endpoints/schedules.md#post-v1schedulesidrun) | POST | Manually trigger execution |
| [/v1/schedules/:id/runs](endpoints/schedule-runs.md) | GET | Get run history for a schedule |

---

## Authentication

All API requests require two types of authentication:

### 1. Promptster API Key (Required)
Include in the `Authorization` header:
```
Authorization: Bearer pk_live_abc123...
```

### 2. Provider API Key (Required)
Include the provider's API key in a custom header based on the provider:

```
X-OPENAI-API-KEY: sk-proj-...           # For OpenAI
X-ANTHROPIC-API-KEY: sk-ant-...         # For Anthropic
X-GOOGLE-API-KEY: AIza...               # For Google
X-DEEPSEEK-API-KEY: ...                 # For DeepSeek
X-XAI-API-KEY: xai-...                  # For xAI (Grok)
X-GROQ-API-KEY: gsk_...                 # For Groq
X-MISTRAL-API-KEY: ...                  # For Mistral
X-PERPLEXITY-API-KEY: pplx-...          # For Perplexity
X-TOGETHER-API-KEY: ...                 # For Together AI
```

**Why both keys?**
- Your Promptster key tracks your usage and enforces rate limits
- Provider keys are passed directly to the AI services (we don't store them)

See [Authentication Guide](authentication.md) for details.

---

## Rate Limits

Rate limits and included calls are based on your subscription tier:

| Tier | Included Calls/Month | Rate Limit (per minute) | Price |
|------|---------------------|------------------------|-------|
| **Free** | 2,000 | 5 | $0 |
| **Builder** | 5,000 | 30 | $9/mo |
| **Scale** | 25,000 | 120 | $29/mo |

Every response includes rate limit and billing headers:
```
X-RateLimit-Remaining-Calls: 4953
X-Credit-Balance: 0
X-Billing-Source: plan_included
X-RateLimit-Tier: builder
```

When you exceed your per-minute rate limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header. When you exhaust your included calls, overages are billed per-call (Builder: $0.005, Scale: $0.003) or you can purchase credit packs.

---

## Error Handling

All errors follow a consistent format:

```json
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "You have exceeded your per-minute rate limit of 30 requests.",
    "retry_after": 3600
  }
}
```

See the [Error Reference](errors.md) for all error types and how to handle them.

---

## Code Examples

### JavaScript / Node.js

```javascript
const response = await fetch('https://www.promptster.dev/v1/prompts/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_abc123...',
    'X-ANTHROPIC-API-KEY': 'sk-ant-...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
    prompt: 'What is the capital of France?'
  })
});

const data = await response.json();
console.log('Response:', data.response);
console.log('Cost:', `$${data.metadata.estimated_cost}`);
```

### Python

```python
import requests

response = requests.post(
    'https://www.promptster.dev/v1/prompts/test',
    headers={
        'Authorization': 'Bearer pk_live_abc123...',
        'X-ANTHROPIC-API-KEY': 'sk-ant-...',
        'Content-Type': 'application/json'
    },
    json={
        'provider': 'anthropic',
        'model': 'claude-sonnet-4-20250514',
        'prompt': 'What is the capital of France?'
    }
)

data = response.json()
print(f"Response: {data['response']}")
print(f"Cost: ${data['metadata']['estimated_cost']}")
```

### cURL

```bash
curl -X POST https://www.promptster.dev/v1/prompts/test \
  -H "Authorization: Bearer pk_live_abc123..." \
  -H "X-ANTHROPIC-API-KEY: sk-ant-..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "prompt": "What is the capital of France?"
  }'
```

More examples in [Code Examples](examples.md).

---

## Base URL

**Production**: `https://www.promptster.dev`
**Development**: `http://localhost:5000` (if running locally)

All endpoints are versioned under `/v1/`.

> **⚠️ Important: Always use `www.promptster.dev`**
>
> Requests to `promptster.dev` (without `www`) will be 307-redirected to `www.promptster.dev`. This redirect **strips the `Authorization` header**, causing authentication failures. Always use the full `https://www.promptster.dev` base URL in your applications.

---

## Next Steps

1. **[Authentication](authentication.md)** - Learn about API key management
2. **[Test Endpoint](endpoints/test-prompt.md)** - Test a single prompt
3. **[Compare Endpoint](endpoints/compare-prompts.md)** - Compare multiple providers
4. **[Schedules](endpoints/schedules.md)** - Automate prompt testing
5. **[Examples](examples.md)** - See complete code examples
6. **[Error Reference](errors.md)** - Handle errors gracefully
7. **[MCP Integration](mcp-integration.md)** - Connect your AI coding assistant

---

## Support

- **Documentation**: You're reading it!
- **Issues**: [GitHub Issues](https://github.com/yourusername/promptster/issues)
- **Email**: support@promptster.dev

---

**API Version**: v1
**Last Updated**: February 8, 2026