API Reference

Programmatic access to your ProofNudge account. Manage projects, testimonials, widgets, video uploads, and analytics via REST API.

Requires Scale plan

Authentication

All API requests require authentication via an API key. API access is available exclusively on the Scale plan.

Getting your API key

Go to Dashboard → Settings
Under “API Access”, click Generate API Key
Copy the key immediately — it's only shown once

Using your API key

Include your key in the Authorization header of every request:

bash

curl -H "Authorization: Bearer pn_live_a3f8b2c1d4e5f6..." \
  https://app.proofnudge.com/api/projects

Keep your API key secret. Never expose it in client-side code, public repositories, or browser requests. If compromised, revoke it immediately from Settings and generate a new one.

Rate Limits

API requests are rate-limited per user using a sliding window. When you exceed the limit, you'll receive a 429 response.

Tier	Limit	Window	Applies to
write	30 requests	60 seconds	POST, PUT, DELETE
read	60 requests	60 seconds	GET requests
ai	5 requests	60 seconds	AI generation

Rate limit headers

Every response includes:

http

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1719835260
Retry-After: 45  # (only on 429 responses)

Errors

All errors return a JSON object with an error field. Some include additional context.

Status	Meaning	Common causes
400	Bad Request	Invalid JSON, missing required fields, validation failure
401	Unauthorized	Missing or invalid API key
403	Forbidden	Plan limit reached, resource belongs to another user, feature not in plan
404	Not Found	Resource doesn't exist or belongs to another user
429	Too Many Requests	Rate limit exceeded. Check Retry-After header
500	Internal Error	Server-side issue. Retry or contact support

Error response format

json

{
  "error": "Testimonial limit reached",
  "message": "Your current plan allows 10 testimonials. Upgrade to Pro for unlimited.",
  "upgradeUrl": "/dashboard/billing"
}

Projects

Testimonials

Widgets

Video Upload

Analytics

Webhooks

Import

AI Generation

Export

Webhook Events

When configured, ProofNudge sends POST requests to your webhook URL for widget events. Each request is signed with HMAC SHA-256.

Verifying signatures

javascript

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// In your handler:
const sig = req.headers['x-proofnudge-signature'];
const isValid = verifyWebhook(rawBody, sig, webhookSecret);

Event payload

json

{
  "event": "event.conversion",
  "data": {
    "id": "evt_abc123",
    "type": "CONVERSION",
    "widgetId": "wdg_xyz",
    "widgetName": "Pricing Carousel",
    "referrer": "https://example.com/pricing"
  },
  "timestamp": "2026-07-01T10:30:00.000Z",
  "projectId": "prj_456"
}

Event Type	Trigger
event.view	Widget rendered on a page
event.click	User clicked on a testimonial or CTA
event.conversion	User clicked the CTA link (conversion tracked)

Quick Start (JavaScript)

A minimal example using fetch to list testimonials and create a new one:

javascript

const API_KEY = "pn_live_YOUR_KEY";
const BASE = "https://app.proofnudge.com";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// List testimonials
const testimonials = await fetch(
  `${BASE}/api/testimonials?projectId=prj_abc123`,
  { headers }
).then(r => r.json());

console.log(`Found ${testimonials.length} testimonials`);

// Create a testimonial
const newTestimonial = await fetch(`${BASE}/api/testimonials`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    projectId: "prj_abc123",
    content: "Absolutely love this product!",
    author: "Alex M.",
    rating: 5,
  }),
}).then(r => r.json());

console.log(`Created: ${newTestimonial.id}`);

// Approve a pending review
await fetch(`${BASE}/api/testimonials/${newTestimonial.id}/status`, {
  method: "PUT",
  headers,
  body: JSON.stringify({ status: "approved" }),
});