Documentation

curl -X POST https://sutrena.com/api/trial

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"waitlist","createDashboard":true}'

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Signup",
    "fields": [
      {"name": "email", "label": "Email", "type": "email", "required": true},
      {"name": "company", "label": "Company", "type": "text", "required": false},
      {"name": "role", "label": "Role", "type": "select", "required": true, "options": ["Developer", "Designer", "PM", "Other"]}
    ]
  }'

curl -X POST https://sutrena.com/api/forms/FORM_ID/submit \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "company": "Acme", "role": "Developer"}'

Authorization: Bearer YOUR_KEY

POST /api/forms
{
  "name": "Contact Form",
  "fields": [
    {"name": "name", "label": "Name", "type": "text", "required": true},
    {"name": "email", "label": "Email", "type": "email", "required": true},
    {"name": "message", "label": "Message", "type": "textarea", "required": true}
  ],
  "successMessage": "Thanks! We'll be in touch.",
  "submitLabel": "Send",
  "createDashboard": true,
  "closesAt": "2026-12-31T23:59:59Z",
  "uniqueBy": ["email"],
  "maxSubmissions": 1000,
  "publicResults": false,
  "redirectUrl": "https://example.com/thanks",
  "webhookIds": ["uuid-of-webhook"]
}

PUT /api/forms/:id
{
  "fields": [...],
  "successMessage": "Updated message",
  "submitLabel": "Submit",
  "closesAt": null,
  "uniqueBy": null,
  "maxSubmissions": null,
  "publicResults": true,
  "redirectUrl": null,
  "webhookIds": ["uuid"]
}

curl -X POST https://sutrena.com/api/forms/FORM_ID/submit \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Alice"}'

curl "https://sutrena.com/api/forms/FORM_ID/submissions?field=email&[email protected]&limit=10" \
  -H "Authorization: Bearer YOUR_KEY"

curl -X DELETE "https://sutrena.com/api/forms/FORM_ID/[email protected]" \
  -H "Authorization: Bearer YOUR_KEY"

curl "https://sutrena.com/api/forms/FORM_ID/export" \
  -H "Authorization: Bearer YOUR_KEY" \
  -o submissions.csv

curl https://sutrena.com/api/forms/FORM_ID/results

{
  "total": 142,
  "fields": {
    "rating": [
      {"value": "5", "count": 58},
      {"value": "4", "count": 41},
      {"value": "3", "count": 28},
      {"value": "2", "count": 10},
      {"value": "1", "count": 5}
    ]
  }
}

curl -X POST https://sutrena.com/api/forms/FORM_ID/upload \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "resume.pdf",
    "contentType": "application/pdf",
    "fieldName": "resume"
  }'

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @resume.pdf

curl -X POST https://sutrena.com/api/forms/FORM_ID/submit \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]", "resume": "OBJECT_ID"}'

curl -X POST https://sutrena.com/api/pages \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-landing",
    "title": "My Landing Page",
    "html": "<h1>Welcome</h1><p>Sign up below.</p>",
    "css": "body { font-family: sans-serif; max-width: 600px; margin: 0 auto; padding: 2rem; }"
  }'

# Step 1: List all your subdomains
curl https://sutrena.com/api/account/subdomains \
  -H "Authorization: Bearer st_trial_xxx"

# Step 2: Create page with subdomainId
curl -X POST https://sutrena.com/api/pages \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-landing",
    "title": "My Landing Page",
    "html": "<h1>Welcome</h1>",
    "subdomainId": "sub_xyz"
  }'

curl https://sutrena.com/api/account/subdomains \
  -H "Authorization: Bearer YOUR_KEY"

curl -X POST https://sutrena.com/api/account/subdomains \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "blog"}'

curl -X PUT https://sutrena.com/api/account/subdomain \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "alice"}'

curl -X POST https://sutrena.com/api/account/domains \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "pages.example.com"}'

curl -X POST https://sutrena.com/api/pages/assets \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "hero.png", "contentType": "image/png"}'

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @hero.png

curl -X PUT https://sutrena.com/api/forms/FORM_ID/submissions/upsert \
  -H "Authorization: Bearer st_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "customer-123", "payload": {"name": "Jane", "score": 95}}'

# First call: { "data": submission, "created": true }
# Second call (same externalId): { "data": submission, "created": false }

POST /api/dashboards
{
  "title": "Waitlist Dashboard",
  "formId": "FORM_ID",
  "isPublic": true,
  "dsl": {
    "version": 1,
    "widgets": [
      {"type": "metric_card", "title": "Total Signups", "value": "count(*)"},
      {"type": "line_chart", "title": "Signups Over Time", "groupBy": "$submitted_at:day"},
      {"type": "pie_chart", "title": "By Role", "groupBy": "role"},
      {"type": "bar_chart", "title": "Weekly Trend", "groupBy": "$submitted_at:week"},
      {"type": "data_table", "title": "Recent Signups", "columns": ["email", "company", "role"], "limit": 20, "sort": "newest"}
    ]
  }
}

POST /api/dashboards
{
  "title": "Q1 Sales",
  "isPublic": true,
  "data": [
    {"region": "US", "revenue": 120000, "deals": 34},
    {"region": "EU", "revenue": 87000, "deals": 22},
    {"region": "APAC", "revenue": 45000, "deals": 11}
  ],
  "dsl": {
    "version": 1,
    "widgets": [
      {"type": "bar_chart", "title": "By Region", "groupBy": "region"},
      {"type": "data_table", "title": "Breakdown", "columns": ["region", "revenue", "deals"]}
    ]
  }
}

# Step 1: Presign upload
POST /api/dashboards/upload
{"filename": "metrics.csv", "sizeBytes": 524288}
# → {"csvObjectId": "obj_xyz", "uploadUrl": "https://..."}

# Step 2: PUT the file to uploadUrl

# Step 3: Create dashboard
POST /api/dashboards
{
  "title": "Monthly Metrics",
  "csvObjectId": "obj_xyz",
  "isPublic": true,
  "dsl": {
    "version": 1,
    "widgets": [
      {"type": "metric_card", "title": "Total Rows", "value": "count(*)"},
      {"type": "metric_card", "title": "Total Revenue", "value": "sum(amount)"},
      {"type": "line_chart", "title": "Trend", "groupBy": "$date:month"},
      {"type": "pie_chart", "title": "Revenue by Category", "groupBy": "category", "aggregate": "sum(amount)"}
    ]
  }
}

curl -X POST https://sutrena.com/api/templates/waitlist \
  -H "Authorization: Bearer YOUR_KEY"

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "feedback", "createDashboard": true}'

curl -X POST https://sutrena.com/api/webhooks \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hook",
    "events": ["form.submission"],
    "description": "Notify on new submissions",
    "template": "default",
    "fieldMapping": {"email": "user_email", "name": "user_name"}
  }'

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "contact",
    "webhookIds": ["WEBHOOK_ID"]
  }'

{
  "event": "form.submission",
  "formId": "abc-123",
  "submissionId": "sub-456",
  "payload": {
    "email": "[email protected]",
    "name": "Alice",
    "message": "Hello!"
  },
  "submittedAt": "2026-03-01T12:00:00Z"
}

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/hook", (req, res) => {
  const signature = req.headers["x-nishkala-signature-256"];
  const rawBody = JSON.stringify(req.body);
  if (!verifyWebhook(rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  // Process the webhook...
  res.sendStatus(200);
});

claude mcp add sutrena --transport streamable-http https://sutrena.com/api/mcp \
  --header "Authorization: Bearer YOUR_KEY"

{
  "mcpServers": {
    "sutrena": {
      "url": "https://sutrena.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

curl -H "Authorization: Bearer st_trial_xxx" \
  https://sutrena.com/api/account/usage

# Response:
{
  "data": {
    "plan": "free",
    "claimed": false,
    "usage": {
      "forms": { "current": 2, "limit": 3, "remaining": 1 },
      "pages": { "current": 1, "limit": 3, "remaining": 2 },
      "dashboards": { "current": 0, "limit": 3, "remaining": 3 },
      "webhooks": { "current": 0, "limit": 1, "remaining": 1 },
      "customDomains": { "current": 0, "limit": 0, "remaining": 0 },
      "storage": {
        "current": 0, "limit": 10485760, "remaining": 10485760,
        "currentFormatted": "0B", "limitFormatted": "10MB"
      }
    },
    "restrictions": ["no_export", "no_upsert"]
  },
  "_meta": { ... }
}

curl https://sutrena.com/api/account \
  -H "Authorization: Bearer YOUR_KEY"

{
  "data": {
    "plan": "pro",
    "email": "[email protected]",
    "name": "Alice",
    "provider": "github",
    "subscriptionStatus": "active",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "_meta": {
    "plan": "pro",
    "limits": {"forms": 20, "dashboards": 20, "webhooks": 3}
  }
}

curl -X POST https://sutrena.com/api/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: sutrena_session=SESSION_ID" \
  -d '{"label": "production"}'

curl -X POST https://sutrena.com/api/keys/KEY_ID/rotate \
  -H "Authorization: Bearer YOUR_KEY"

<div data-sutrena-form="FORM_ID"></div>
<script src="https://sutrena.com/embed.js"></script>

<div data-sutrena-form="FORM_ID" data-sutrena-host="https://your-domain.com"></div>
<script src="https://sutrena.com/embed.js"></script>

<form id="my-form">
  <input name="email" type="email" required />
  <input name="name" type="text" required />
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

<script>
  document.getElementById("my-form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(e.target));
    const res = await fetch("https://sutrena.com/api/forms/FORM_ID/submit", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    if (res.ok) {
      e.target.innerHTML = "<p>Thank you!</p>";
    }
  });
</script>

// Listen for embed events
window.addEventListener("message", (e) => {
  if (e.data?.type === "sutrena:submitted") {
    console.log("Form submitted!");
    // Track conversion, show thank-you, etc.
  }
});

document.querySelector("[data-sutrena-form]")
  .addEventListener("sutrena:submitted", () => {
    console.log("Form submitted!");
  });