PEIP API Guide

Integrate PrimeWave infrastructure intelligence into your AI pipeline in minutes. Every workload you send through PEIP gets drift-scored, optimized, governed, and audited automatically.

Base URL: https://peip.desvy.com — TLS 1.3, HTTPS only.

5-Minute Quickstart

Three steps to get your first drift score:

Step 1 — Login and get your token

curl

curl -s -X POST https://peip.desvy.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourorg.com",
    "password": "yourpassword",
    "org_slug": "your-org-slug"
  }'

Response

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 3600,
  "org_id": "9aa2d70b-...",
  "role": "owner"
}

Step 2 — Submit your first workload

curl

curl -s -X POST https://peip.desvy.com/api/v1/workload/submit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workload_type": "inference",
    "model_requested": "primewave.standard",
    "raw_token_estimate": 15000,
    "retry_count": 3,
    "latency_ms": 2200,
    "orchestration_depth": 1
  }'

Response — your first drift score

{
  "workload_ref": "WL-00001",
  "drift_score": 0.138,
  "drift_level": "low",
  "stability_score": 0.862,
  "model_routed": "primewave.efficient",
  "token_reduction_pct": 15.0,
  "governance_action": "allowed",
  "normal_execution": { "tokens": 15000, "retries": 3 },
  "optimized_execution": { "tokens": 12750, "retries": 1 },
  "optimization_plan": { "optimization_count": 2, "actions": [...] }
}

Step 3 — Check your metrics

curl

curl -s https://peip.desvy.com/api/v1/metrics \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

PEIP supports two authentication methods. Both are org-scoped — your token or API key only accesses your organization's data.

Method 1 — JWT Bearer Token

Login with email + password + org_slug to get a JWT token. Include it in the Authorization header. Tokens expire after 60 minutes.

All languages

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Method 2 — API Key (recommended for integrations)

Generate an API key from your dashboard or onboarding flow. Use it in the X-API-Key header. API keys don't expire unless revoked.

All languages

X-API-Key: pk_91v3lYWAdOMbuTg_Bp-kM9xuxyspYtJl...

Security: API keys are shown only once at creation. Store them securely. Never expose them in client-side code or public repositories.

Generate an API Key

curl

curl -s -X POST https://peip.desvy.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-integration",
    "scopes": ["workloads", "reports", "metrics"]
  }'

Response — save raw_key immediately

{
  "id": "a1b2c3d4-...",
  "name": "production-integration",
  "prefix": "pk_91v3lYWAdO",
  "raw_key": "pk_91v3lYWAdOMbuTg_Bp-kM9xuxyspYtJl...",
  "note": "Store this key securely. It will not be shown again."
}

Submit Workload

The core PEIP endpoint. Send your AI workload metadata and receive a drift score, optimization plan, and before/after comparison.

POST /api/v1/workload/submit

Submit a workload through the PrimeWave optimization pipeline.

Request Body

Parameter	Type	Required	Description
workload_type	string	required	inference · classification · batch · orchestration · embedding · extraction
raw_token_estimate	integer	required	Estimated token count for this workload
retry_count	integer	optional	Number of retries already attempted (default: 0)
latency_ms	integer	optional	Current latency in milliseconds (default: 0)
orchestration_depth	integer	optional	Number of orchestration layers (1–20, default: 1)
model_requested	string	optional	Model you intend to use (e.g. primewave.standard)
prompt	string	optional	Prompt text for compression analysis

        import requests

API = "https://peip.desvy.com"
API_KEY = "pk_your_api_key_here"

headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

response = requests.post(
    f"{API}/api/v1/workload/submit",
    headers=headers,
    json={
        "workload_type": "inference",
        "raw_token_estimate": 15000,
        "retry_count": 3,
        "latency_ms": 2200,
        "model_requested": "primewave.standard",
        "orchestration_depth": 1,
    }
)

result = response.json()
print(f"Drift score: {result['drift_score']}")
print(f"Drift level: {result['drift_level']}")
print(f"Token reduction: {result['token_reduction_pct']}%")
print(f"Model routed to: {result['model_routed']}")
print(f"Governance: {result['governance_action']}")
      

        const API = 'https://peip.desvy.com';
const API_KEY = 'pk_your_api_key_here';

const response = await fetch(`${API}/api/v1/workload/submit`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workload_type: 'inference',
    raw_token_estimate: 15000,
    retry_count: 3,
    latency_ms: 2200,
    model_requested: 'primewave.standard',
    orchestration_depth: 1,
  }),
});

const result = await response.json();
console.log('Drift score:', result.drift_score);
console.log('Token reduction:', result.token_reduction_pct + '%');
console.log('Model routed:', result.model_routed);
console.log('Governance:', result.governance_action);
      

        curl -s -X POST https://peip.desvy.com/api/v1/workload/submit \
  -H "X-API-Key: pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workload_type": "inference",
    "raw_token_estimate": 15000,
    "retry_count": 3,
    "latency_ms": 2200,
    "model_requested": "primewave.standard",
    "orchestration_depth": 1
  }' | python3 -m json.tool
      

        $api = 'https://peip.desvy.com';
$key = 'pk_your_api_key_here';

$data = json_encode([
    'workload_type' => 'inference',
    'raw_token_estimate' => 15000,
    'retry_count' => 3,
    'latency_ms' => 2200,
    'model_requested' => 'primewave.standard',
]);

$ch = curl_init("$api/api/v1/workload/submit");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $key",
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = json_decode(curl_exec($ch), true);
echo "Drift: " . $result['drift_score'];
      

Analyze Drift (No DB Write)

Analyze a workload's drift score without submitting it to the pipeline. Useful for testing and real-time monitoring.

POST/api/v1/analyze

Python

response = requests.post(
    "https://peip.desvy.com/api/v1/analyze",
    headers=headers,
    json={
        "raw_token_count": 28000,
        "retry_count": 6,
        "latency_ms": 3500,
        "prompt_length": 4000,
        "orchestration_depth": 2,
        "baseline_token_count": 15000,
    }
)
d = response.json()
# Returns drift score without storing anything
print(d['drift_score'], d['drift_level'], d['signals'])

Get Metrics

Rolling 24-hour metrics for your organization — requests, optimization rate, drift score, retries suppressed, and estimated savings.

GET/api/v1/metrics

Python

metrics = requests.get(
    "https://peip.desvy.com/api/v1/metrics",
    headers=headers
).json()

print(f"Requests 24h: {metrics['total_requests_24h']}")
print(f"Optimization rate: {metrics['optimization_rate_pct']}%")
print(f"Avg drift score: {metrics['avg_drift_score']}")
print(f"Retries suppressed: {metrics['retries_suppressed_24h']}")
print(f"Est. monthly savings: ${metrics['est_monthly_savings_usd']}")

Run Benchmark Suite

Run one of 7 repeatable workload benchmark suites. Results are cryptographically signed.

POST/api/v1/benchmarks/run

Python

# Available suites: summarization · classification · orchestration
#                   retry_heavy · prompt_compression · api_chaining · high_token

result = requests.post(
    "https://peip.desvy.com/api/v1/benchmarks/run",
    headers=headers,
    json={"suite": "classification"}
).json()

print(f"Run ID: {result['run_id']}")
print(f"Avg token reduction: {result['summary']['avg_token_reduction_pct']}%")
print(f"Avg drift score: {result['summary']['avg_drift_score']}")
print(f"Signature: {result['signature'][:32]}...")

for wl in result['workloads']:
    print(f"  {wl['name']}: -{wl['token_reduction_pct']}% tokens, drift={wl['drift_score']}")

Replay Engine

Replay a workload N times with drift accumulation to observe how infrastructure degrades under repeated pressure.

POST/api/v1/replay

Python

result = requests.post(
    "https://peip.desvy.com/api/v1/replay",
    headers=headers,
    json={
        "workload_type": "inference",
        "base_tokens": 10000,
        "base_retries": 4,
        "iterations": 10,
        "drift_accumulation": True,
    }
).json()

print(f"Drift trend: {result['summary']['drift_trend']}")
print(f"Retries suppressed: {result['summary']['total_retries_suppressed']}")
print(f"Governance interventions: {result['summary']['governance_interventions']}")

# Plot drift evolution
print("Drift evolution:", result['drift_evolution'])

Cost Analysis

Get transparent infrastructure cost estimates for your organization. All estimates use public LLM API pricing — not hardware-measured.

GET/api/v1/cost/summary?days=30

Python

cost = requests.get(
    "https://peip.desvy.com/api/v1/cost/summary",
    headers=headers,
    params={"days": 30}
).json()

print(f"Total workloads: {cost['total_workloads']}")
print(f"Cost normal: ${cost['total_cost_normal_usd']}")
print(f"Cost optimized: ${cost['total_cost_optimized_usd']}")
print(f"Savings: ${cost['total_savings_usd']} ({cost['savings_pct']}%)")
print(f"Projected monthly: ${cost['projected_monthly_savings_usd']}")

Generate Reports

Generate signed optimization or drift reports in PDF, JSON, or CSV format.

POST/api/v1/reports/generate

Python

# Generate a signed PDF optimization report
report = requests.post(
    "https://peip.desvy.com/api/v1/reports/generate",
    headers=headers,
    json={
        "report_type": "optimization",  # or "drift"
        "format": "pdf",                  # or "json" / "csv"
        "period_days": 30,
    }
).json()

print(f"Report ID: {report['report_id']}")
print(f"Signature: {report['signature'][:32]}...")

# Download the report
pdf = requests.get(
    f"https://peip.desvy.com/api/v1/reports/{report['report_id']}/download",
    headers=headers,
    params={"fmt": "pdf"}
)
with open("peip-report.pdf", "wb") as f:
    f.write(pdf.content)
print("Report saved: peip-report.pdf")

Drift Level Reference

Level	Score Range	Meaning	Action
nominal	0.00 – 0.10	Infrastructure stable	No action required
low	0.10 – 0.20	Minor drift detected	Monitoring active
moderate	0.20 – 0.40	Optimization applied	Governance monitoring
elevated	0.40 – 0.65	Throttling applied	Governance escalated
critical	0.65 – 1.00	Infrastructure protection	Workload governed/blocked

Workload Types

Type	Description	Small Model	Large Model
inference	Standard LLM inference	primewave.efficient	primewave.standard
classification	Content classification	primewave.efficient	primewave.efficient
embedding	Vector embeddings	primewave.embedding.fast	primewave.embedding.precision
orchestration	Multi-agent pipelines	primewave.standard	primewave.advanced
batch	Batch processing	primewave.efficient	primewave.standard
extraction	Data extraction	primewave.efficient	primewave.standard

Error Codes

Code	Meaning	Fix
401	Invalid or expired credentials	Re-login or check API key
403	Insufficient permissions	Check your role (owner/admin/analyst/viewer)
400	Invalid request body	Check required fields and types
429	Quota exceeded	Upgrade plan or wait for next billing period
502	External service error	PayPal or external API unavailable
500	Internal server error	Check /status page or contact support

All error responses include a "detail" field with a human-readable message.