# PlimverAI API

## Description
This is version `2.0.0` of this API documentation. Last update on Nov 14, 2025.
PlimverAI provides a unified AI API with multi-model support, persistent memory, RAG capabilities, and code execution.

## 🚀 Quick Start

Get started with PlimverAI in under 5 minutes using our official SDKs or REST API.

### Get Your API Key
1. Sign up at [PlimverAI Portal](https://github.com/Elliot-Elikplim/plimverai-developer-portal)
2. Navigate to Dashboard → API Keys
3. Click "Create New API Key"
4. Copy your key (starts with `pv_sk_`)

---

## 📦 Official SDKs

### Python SDK

**Installation:**
```bash
pip install plimverai-sdk
```

**Basic Usage:**
```python
from plimverai import PlimverAIClient

# Initialize client
client = PlimverAIClient(api_key="pv_sk_your_key")

# Simple chat
response = client.chat.messages.create(
    model="PV-TURBO",
    messages=[{"role": "user", "content": "Hello, how are you?"}],
    user_id="user_123"
)
print(response.choices[0]['message']['content'])
```

**Streaming:**
```python
# Stream responses in real-time
for chunk in client.chat.stream(
    model="PV-TURBO",
    messages=[{"role": "user", "content": "Tell me a story"}],
    user_id="user_123"
):
    print(chunk, end='', flush=True)
```

**With RAG:**
```python
# Search your documents with RAG
response = client.chat.messages.create(
    model="PV-STANDARD",
    messages=[{"role": "user", "content": "What's in our documentation about deployment?"}],
    user_id="user_123",
    use_rag=True,
    rag_k=10  # Retrieve top 10 relevant documents
)
```

**Code Execution:**
```python
# Execute Python code securely
result = client.code.execute(
    code="print('Hello from PlimverAI!')\nprint(2 + 2)",
    user_id="user_123",
    timeout=15
)
print(result['output'])  # Hello from PlimverAI!\n4
```

📚 [Full Python SDK Documentation](https://github.com/Elliot-Elikplim/plimverai-developer-portal/blob/master/docs/SDK_PYTHON.md)

---

### JavaScript/TypeScript SDK

**Installation:**
```bash
npm install @plimverai/sdk
# or
yarn add @plimverai/sdk
```

**Basic Usage:**
```javascript
import { PlimverAIClient } from '@plimverai/sdk';

// Initialize client
const client = new PlimverAIClient({ apiKey: 'pv_sk_your_key' });

// Simple chat
const response = await client.chat.create({
  model: 'PV-TURBO',
  messages: [{ role: 'user', content: 'Hello, how are you?' }],
  user_id: 'user_123'
});
console.log(response.choices[0].message.content);
```

**Streaming:**
```javascript
// Stream responses with async iterator
for await (const chunk of client.chat.stream({
  model: 'PV-TURBO',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  user_id: 'user_123'
})) {
  process.stdout.write(chunk);
}
```

**With RAG:**
```javascript
// Search your documents with RAG
const response = await client.chat.create({
  model: 'PV-STANDARD',
  messages: [{ role: 'user', content: 'What\'s in our docs about deployment?' }],
  user_id: 'user_123',
  use_rag: true,
  rag_k: 10  // Retrieve top 10 relevant documents
});
```

**TypeScript Support:**
```typescript
import { PlimverAIClient, ChatCompletionResponse } from '@plimverai/sdk';

const client = new PlimverAIClient({ apiKey: process.env.PLIMVERAI_API_KEY! });

const response: ChatCompletionResponse = await client.chat.create({
  model: 'PV-TURBO',
  messages: [{ role: 'user', content: 'Hello' }],
  user_id: 'user_123'
});
```

📚 [Full JavaScript SDK Documentation](https://github.com/Elliot-Elikplim/plimverai-developer-portal/blob/master/docs/SDK_JAVASCRIPT.md)

---

## 🌐 REST API

**Direct HTTP Requests:**
```bash
curl -X POST https://api.plimverai.tech/z1/chat/completions \
  -H "Authorization: Bearer pv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PV-TURBO",
    "messages": [{"role": "user", "content": "Hello"}],
    "user_id": "user_123"
  }'
```

---

## 🎯 Available Models

| Model | Speed | Quality | Credits/Request | Best For |
|-------|-------|---------|----------------|----------|
| **PV-TURBO** | ⚡ Fastest (<1s) | Good | 1 | Chat, quick answers, real-time |
| **PV-STANDARD** | 🚀 Fast (1-2s) | Better | 2 | General tasks, balanced performance |
| **PV-ADVANCED** | 🧠 Moderate (2-4s) | Best | 5 | Complex reasoning, analysis |
| **PV-CODEX** | 💻 Fast (1-2s) | Excellent | 3 | Code generation, debugging |

---

## 🔐 Authentication

All API requests require authentication using your API key:

**Option 1: Bearer Token (Recommended)**
```
Authorization: Bearer pv_sk_your_key
```

**Option 2: Custom Header**
```
X-API-Key: pv_sk_your_key
```

**Security Best Practices:**
- Never commit API keys to version control
- Use environment variables: `PLIMVERAI_API_KEY`
- Rotate keys regularly
- Use separate keys for development/production

---

## ⚡ Rate Limiting

PlimverAI uses a multi-tiered rate limiting strategy:

- **RPM (Requests Per Minute)**: Burst protection - 10 to 300 RPM
- **RPD (Requests Per Day)**: Daily usage caps - 100 to 10,000 requests
- **TPM (Total Per Month)**: Monthly limits aligned with your tier

Rate limit headers are included in every response:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1699564920
```

---

## 📊 Pricing Tiers

| Tier | Price | RPM | RPD | Features |
|------|-------|-----|-----|----------|
| **Free** | $0 | 10 | 100 | Basic models, 5s code timeout |
| **Startup** | $7/mo | 60 | 1,000 | All models, 15s code timeout, SLA monitoring |
| **Business** | $140/mo | 150 | 5,000 | Unlimited models, 60s timeout, custom RAG K, priority support |
| **Enterprise** | Custom | 300 | 10,000 | Everything + custom fine-tuning, dedicated support, 120s timeout |

---

## 🎨 Key Features

- 🚀 **Multi-Model Support**: Choose the right model for your use case
- 🧠 **Persistent Memory**: Conversations remember context across sessions
- 📚 **RAG**: Upload documents and search them with natural language
- ⚡ **Response Caching**: 13x faster responses (60-114ms for cached queries)
- 🌐 **Web Grounding**: Real-time web search via SearXNG
- 💻 **Code Execution**: Run Python code in secure sandboxed environment
- 📊 **SLA Guarantees**: 99%-99.95% uptime with monitoring dashboard
- 🔄 **Streaming**: Real-time token-by-token responses

---

## 📚 Additional Resources

- 📖 [Python SDK Documentation](https://github.com/Elliot-Elikplim/plimverai-developer-portal/blob/master/docs/SDK_PYTHON.md)
- 📖 [JavaScript SDK Documentation](https://github.com/Elliot-Elikplim/plimverai-developer-portal/blob/master/docs/SDK_JAVASCRIPT.md)
- 🔧 [API Reference](https://bump.sh/plimverai/hub/plimver-hub/doc/plimverai-api)
- 💬 [Developer Portal](https://github.com/Elliot-Elikplim/plimverai-developer-portal)
- 📧 [Support](mailto:support@plimverai.com)


## Servers
- Production server: https://api.plimverai.tech (Production server)
- Azure production server: https://zenux-api.redglacier-fb4abe56.southafricanorth.azurecontainerapps.io (Azure production server)

## Authentication
The API accepts 2 different authentication methods:
- Api key auth (http_api_key)
- Bearer auth (http)


## Endpoints
- [Chat](https://docs.plimverai.com/group/endpoint-chat.md)
- [Models](https://docs.plimverai.com/group/endpoint-models.md)
- [Usage](https://docs.plimverai.com/group/endpoint-usage.md)
- [Memory](https://docs.plimverai.com/group/endpoint-memory.md)
- [RAG](https://docs.plimverai.com/group/endpoint-rag.md)
- [Code](https://docs.plimverai.com/group/endpoint-code.md)
- [SLA](https://docs.plimverai.com/group/endpoint-sla.md)


[Powered by Bump.sh](https://bump.sh)