Developer Guide

curl -X POST https://api.getpromptly.in/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "org_name": "My Company",
    "email": "dev@mycompany.com",
    "password": "securepassword",
    "account_type": "team"
  }'

{
  "token": "eyJhbGciOiJIUz...",
  "user": { "id": "uuid", "email": "dev@mycompany.com", "role": "admin" },
  "org": { "id": "uuid", "name": "My Company", "account_type": "team" },
  "api_key": "sk-promptly-abc123..."
}

curl -X POST https://api.getpromptly.in/api/keys/providers \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-your-openai-key"
  }'

import openai

client = openai.OpenAI(
    api_key="sk-promptly-abc123...",       # Your Promptly key
    base_url="https://api.getpromptly.in/v1"  # Point to Promptly
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is quantum computing?"}
    ]
)

print(response.choices[0].message.content)

Your App                      Promptly                      LLM Provider
   │                             │                              │
   │──── POST /v1/chat/... ─────▶│                              │
   │     (Promptly API key)      │                              │
   │                             │── 1. Validate API key        │
   │                             │── 2. Check semantic cache    │
   │                             │      (hit? return instant)   │
   │                             │── 3. Optimize prompt         │
   │                             │      • Whitespace removal    │
   │                             │      • Redundancy dedup      │
   │                             │      • System compression    │
   │                             │      • Context pruning       │
   │                             │── 4. Classify complexity     │
   │                             │      → Pick cheapest model   │
   │                             │── 5. Forward to provider ───▶│
   │                             │      (your OpenAI key)       │──► LLM processes
   │                             │◀── 6. Receive response ──────│
   │                             │── 7. Cache response          │
   │                             │── 8. Log everything          │
   │                             │── 9. Evaluate alerts         │
   │◀── Response + metadata ─────│                              │

Authorization: Bearer sk-promptly-abc123...

Authorization: Bearer eyJhbGciOiJIUz...

# GitHub OAuth - redirects to GitHub authorization page
GET /api/auth/oauth/github
# GitHub callback - exchanges code for JWT
GET /api/auth/oauth/github/callback?code=xxx

# Google OAuth - redirects to Google authorization page
GET /api/auth/oauth/google
# Google callback - exchanges code for JWT
GET /api/auth/oauth/google/callback?code=xxx

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Explain recursion in 2 sentences." }
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "stream": false
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709312000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Recursion is when a function calls itself..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 45,
    "total_tokens": 73
  },
  "promptly_metadata": {
    "baseline_model": "gpt-4o",
    "routed_model": "gpt-4o-mini",
    "original_tokens": 52,
    "optimized_tokens": 28,
    "savings": 0.00034,
    "cache_hit": false,
    "latency_ms": 834
  }
}

pip install promptly-sdk

from promptly import Promptly

client = Promptly(api_key="sk-promptly-abc123...")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

npm install promptly-sdk

import Promptly from "promptly-sdk";

const client = new Promptly({ apiKey: "sk-promptly-abc123..." });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

from promptly import wrap
from openai import OpenAI

client = wrap(OpenAI(api_key="sk-promptly-abc123..."))
# All existing code works unchanged

from openai import OpenAI

client = OpenAI(
    api_key="sk-promptly-abc123...",
    base_url="https://api.getpromptly.in/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-promptly-abc123...",
  baseURL: "https://api.getpromptly.in/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

curl https://api.getpromptly.in/v1/chat/completions \
  -H "Authorization: Bearer sk-promptly-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o",
    api_key="sk-promptly-abc123...",
    base_url="https://api.getpromptly.in/v1",
)

response = llm.invoke("Explain quantum computing.")

from llama_index.llms.openai import OpenAI

llm = OpenAI(
    model="gpt-4o",
    api_key="sk-promptly-abc123...",
    api_base="https://api.getpromptly.in/v1",
)

import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const result = await generateText({
  model: openai("gpt-4o", {
    baseURL: "https://api.getpromptly.in/v1",
    apiKey: "sk-promptly-abc123...",
  }),
  prompt: "Explain recursion.",
});

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a poem about code."}],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a poem about code." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

data: {"choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":" world"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

GET /api/optimization/settings

{
  "level": "moderate",
  "whitespace_removal": true,
  "redundancy_elimination": true,
  "system_prompt_compression": true,
  "context_pruning": true,
  "cache_enabled": true,
  "cache_similarity_threshold": 0.95,
  "cache_ttl_seconds": 3600,
  "routing_mode": "auto"
}

# View cache statistics
GET /api/optimization/cache/stats
# Response: { "exact_entries": 812, "semantic_entries": 435, "total_entries": 1247 }

# Clear all cached responses
POST /api/optimization/cache/clear

Request 1: "What's the capital of France?"        → Miss → calls LLM → caches
Request 2: "capital of france?"                    → Hit (0.97 similarity) → $0
Request 3: "What is France's capital city?"        → Hit (0.96 similarity) → $0
Request 4: "What's the capital of Germany?"        → Miss (0.72 similarity) → calls LLM

# 48-message conversation with aggressive pruning:

Before: 4,200 tokens (full history)
After:    980 tokens (6 latest messages + summary of dropped ones)

# Summary injected as system message:
"[Earlier context pruned: 8 user and 7 assistant messages were removed to save tokens.]"

{
  "name": "Code tasks use GPT-4o",
  "condition_type": "keyword",
  "condition_value": { "keywords": ["code", "debug", "refactor"] },
  "action": "use_model",
  "action_value": "gpt-4o",
  "priority": 10
}

{
  "name": "Short prompts → mini",
  "condition_type": "token_count",
  "condition_value": { "operator": "lt", "value": 50 },
  "action": "use_model",
  "action_value": "gpt-4o-mini",
  "priority": 20
}

{
  "name": "Default everything to Sonnet",
  "condition_type": "always",
  "condition_value": {},
  "action": "use_model",
  "action_value": "claude-sonnet",
  "priority": 0
}

# List all rules
GET /api/routing/rules

# Delete a rule
DELETE /api/routing/rules/{rule_id}

{
  "name": "High daily spend",
  "metric": "daily_spend",
  "operator": "gt",
  "threshold": 50.00,
  "channels": ["email"]
}

# List all alerts
GET /api/alerts/rules

# Update an alert
PUT /api/alerts/rules/{rule_id}
{ "threshold": 100.00, "is_active": true }

# Delete an alert
DELETE /api/alerts/rules/{rule_id}

GET /api/analytics/overview

GET /api/analytics/savings

GET /api/analytics/models

GET /api/analytics/levers

# List requests (paginated)
GET /api/requests

# Get a specific request
GET /api/requests/{request_id}

{
  "email": "teammate@company.com",
  "role": "viewer"
}

# List team members
GET /api/team/members

# Update a member's role
PUT /api/team/members/{user_id}
{ "role": "admin" }

# Remove a member
DELETE /api/team/members/{user_id}

{
  "detail": "No valid provider key found. Please connect an API key in the dashboard."
}

{ "detail": "No valid provider key found. Please connect an API key in the dashboard." }

PUT /api/optimization/settings
{ "level": "off", "routing_mode": "manual", "cache_enabled": false }