Documentation

💡How Pollenate Works

Pollenate helps you hear from the people who use your product, visit your website, or walk through your door. It collects their feedback — ratings, comments, survey responses — and organizes it all in one dashboard so you can spot patterns and take action.

🚀Quick Start

Get up and running with Pollenate in under 5 minutes. Collect your first piece of feedback today.

<script 
  src="https://pollenate.dev/widget.js"
  data-inbox-key="YOUR_INBOX_KEY"
  data-api-key="YOUR_API_KEY"
  data-type="emoji"
  async
></script>

That's it! The widget will automatically appear on your page. You'll need both an inbox key (from the Inboxes page) and an API key with the "collect" scope (from Settings → API Keys).

🔐Authentication

Pollenate uses two authentication methods depending on your use case:

curl -X POST https://api.pollenate.dev/collect \
  -H "X-Pollenate-Key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "emoji", "score": 5, "comment": "Great!"}'

curl https://api.pollenate.dev/organizations \
  -H "Authorization: Bearer eyJhbGc..."

📦Embed Widget

The Pollenate widget can be embedded in any website with a single script tag.

Script Attributes

🎨Widget Types

Pollenate offers six different ways to ask for feedback. Choose the one that fits what you're trying to learn. Not sure which to pick? Emoji and Stars work great for most situations.

🎭Customization

Customize the widget appearance using CSS variables or create custom themes in the dashboard.

:root {
  --pollenate-primary: #f59e0b;
  --pollenate-primary-hover: #d97706;
  --pollenate-bg: #ffffff;
  --pollenate-text: #1e293b;
  --pollenate-border: #e2e8f0;
  --pollenate-radius: 12px;
}

⚛️React Package

For React apps, install @pollenate/react for a fully typed, native React component — no script tags or DOM manipulation needed.

Installation

npm install @pollenate/react
# or
pnpm add @pollenate/react
# or
yarn add @pollenate/react

Quick Start

import { PollenateWidget } from '@pollenate/react';

export function App() {
  return (
    <PollenateWidget
      inboxKey="YOUR_INBOX_KEY"
      apiKey="YOUR_API_KEY"
      type="stars"
      theme="auto"
      onSubmit={(event) => {
        console.log('Feedback submitted:', event.detail);
      }}
    />
  );
}

Inline Widget

Add inline to render the widget directly in your page flow instead of as a floating button:

<PollenateWidget
  inboxKey="my-inbox"
  apiKey="pk_live_xxx"
  type="thumbs"
  inline
  prompt="Was this page helpful?"
/>

Custom Themed

Override colors, border radius, fonts, and dark-mode colors:

<PollenateWidget
  inboxKey="my-inbox"
  apiKey="pk_live_xxx"
  type="nps"
  theme="auto"
  primaryColor="#6366f1"
  borderRadius={12}
  buttonText="Submit Score"
  darkPrimaryColor="#818cf8"
  darkBgColor="#1e1b4b"
  hideBranding
/>

Props Reference

🛠️Custom Widgets

Want complete control over your feedback UI? Build your own custom widget using our REST API. This allows you to match your brand perfectly and integrate feedback into any user flow. If you're using React, consider the @pollenate/react package first — it handles all the API calls and UI for you.

Basic Example

Here's a complete example of a custom feedback form using vanilla HTML/JavaScript:

<form id="custom-feedback">
  <p>How would you rate your experience?</p>
  <div class="rating-buttons">
    <button type="button" data-score="1">😞</button>
    <button type="button" data-score="2">😐</button>
    <button type="button" data-score="3">🙂</button>
    <button type="button" data-score="4">😄</button>
    <button type="button" data-score="5">🤩</button>
  </div>
  <textarea name="comment" placeholder="Any additional feedback?"></textarea>
  <button type="submit">Submit</button>
</form>

<script>
let selectedScore = null;

document.querySelectorAll('[data-score]').forEach(btn => {
  btn.onclick = () => selectedScore = parseInt(btn.dataset.score);
});

document.getElementById('custom-feedback').onsubmit = async (e) => {
  e.preventDefault();
  
  const response = await fetch('https://api.pollenate.dev/collect', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Pollenate-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      inboxKey: 'YOUR_INBOX_KEY',
      type: 'emoji',
      score: selectedScore,
      comment: e.target.comment.value,
      context: {
        page: window.location.pathname,
        userAgent: navigator.userAgent
      }
    })
  });
  
  if (response.ok) {
    alert('Thank you for your feedback!');
  }
};
</script>

React Example (DIY)

This shows how to build a completely custom feedback UI from scratch using the API directly. For a drop-in solution, see the React Package section above.

import { useState } from 'react';

export function CustomFeedback() {
  const [score, setScore] = useState(null);
  const [comment, setComment] = useState('');
  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = async () => {
    const response = await fetch('https://api.pollenate.dev/collect', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Pollenate-Key': process.env.POLLENATE_API_KEY
      },
      body: JSON.stringify({
        inboxKey: 'YOUR_INBOX_KEY',
        type: 'emoji',
        score,
        comment,
        context: { page: window.location.pathname }
      })
    });
    
    if (response.ok) setSubmitted(true);
  };

  if (submitted) return <p>Thanks for your feedback! 🎉</p>;

  return (
    <div className="feedback-widget">
      <p>How was your experience?</p>
      <div className="emojis">
        {['😞', '😐', '🙂', '😄', '🤩'].map((emoji, i) => (
          <button
            key={i}
            onClick={() => setScore(i + 1)}
            className={score === i + 1 ? 'selected' : ''}
          >
            {emoji}
          </button>
        ))}
      </div>
      <textarea
        value={comment}
        onChange={(e) => setComment(e.target.value)}
        placeholder="Tell us more..."
      />
      <button onClick={handleSubmit} disabled={!score}>
        Submit Feedback
      </button>
    </div>
  );
}

API Request Format

Score Ranges by Type

Using Context for Insights

The context field lets you attach metadata to each feedback submission. This enables powerful filtering and analysis in your dashboard.

// Example context object
{
  "context": {
    "page": "/checkout",
    "userId": "user_abc123",
    "plan": "pro",
    "feature": "dark-mode",
    "experiment": "new-pricing-v2",
    "sessionId": "sess_xyz789"
  }
}

📋Feedback Pages

Feedback Pages are standalone, branded feedback forms that you create through the Pollenate dashboard. Unlike widgets (which embed into existing pages), Feedback Pages are hosted at their own URL and can collect multi-question surveys from users.

Key Features

🔨Form Builder

The form builder lets you create multi-question feedback forms using a visual editor. Each question has a type, prompt, optional description, and can be marked as required.

Supported Question Types

Page Settings

🔗Sharing & Embedding

Once your Feedback Page is published, you have multiple ways to share it with respondents.

https://pollenate.dev/f/your-org/your-page-slug

GET https://api.pollenate.dev/qr?data=YOUR_PAGE_URL&size=256&format=png&margin=4

Parameters:
  data    - URL to encode (required)
  size    - Image size in pixels: 128, 256, 512, 1024 (default: 256)
  format  - Output format: png or svg (default: png)
  margin  - Quiet zone margin in modules (default: 4)

<table cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td style="padding: 10px 0;">
      <a href="https://pollenate.dev/f/your-org/your-page"
         style="display: inline-block; padding: 8px 16px;
                background-color: #f59e0b; color: #ffffff;
                text-decoration: none; border-radius: 6px;
                font-family: Arial, sans-serif; font-size: 14px;">
        Share Your Feedback
      </a>
    </td>
  </tr>
</table>

<iframe
  src="https://pollenate.dev/f/your-org/your-page?embed=true"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
  title="Feedback Form"
></iframe>

⚙️Pages API

Manage Feedback Pages programmatically via the REST API. All endpoints require JWT Bearer token authentication.

Submit Responses (Public)

{
  "answers": {
    "question-id-1": { "score": 5 },
    "question-id-2": { "textValue": "Great experience!" },
    "question-id-3": { "multiValues": ["Search", "Referral"] }
  },
  "respondentName": "Jane Doe",
  "respondentEmail": "[email protected]",
  "turnstileToken": "CAPTCHA_TOKEN"
}

⚡API Overview

The Pollenate API is a RESTful API that uses JSON for request and response bodies.

For the complete API specification, see our OpenAPI 3.1 spec.

📥Feedback Collection

{
  "type": "emoji",        // emoji, stars, thumbs, nps, csat, text
  "score": 5,             // 0-10 for nps, 1-5 for others
  "comment": "Loving it!",// Optional text feedback
  "context": {            // Optional metadata
    "page": "/checkout",
    "userId": "user_123"
  }
}

{
  "id": "fb_abc123",
  "createdAt": "2026-02-04T12:00:00Z"
}

📬Inboxes

Inboxes are containers for feedback. Each inbox has a unique key used to submit feedback.

🔍Semantic Search

Search feedback using natural language. Powered by AI embeddings for semantic understanding.

{
  "query": "users frustrated with checkout",
  "limit": 20,
  "filters": {
    "inboxId": "inbox_123",
    "minScore": 1,
    "maxScore": 3
  }
}

🤖AI Agent Integration

AI agents can submit feedback during conversations with users — capturing satisfaction, sentiment, and product feedback in real-time without interrupting the flow.

# Install the skill locally for your AI agent
mkdir -p ~/.agent/skills/pollenate
curl -s https://pollenate.dev/skill.md > ~/.agent/skills/pollenate/SKILL.md
curl -s https://pollenate.dev/skill.json > ~/.agent/skills/pollenate/skill.json

{
  "mcpServers": {
    "pollenate": {
      "type": "streamableHttp",
      "url": "https://api.pollenate.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "pollenate": {
      "type": "streamableHttp",
      "url": "https://api.pollenate.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_API_KEY"
      }
    }
  }
}

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "support-chat",
    "type": "thumbs",
    "score": 1,
    "comment": "User confirmed their issue was resolved",
    "context": {
      "source": "ai-agent",
      "agentName": "SupportBot",
      "topic": "password-reset"
    }
  }'

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "sentiment-tracker",
    "type": "emoji",
    "score": 4,
    "context": {
      "source": "ai-agent",
      "detectedSentiment": "positive",
      "conversationTurns": 8,
      "agentModel": "claude-sonnet-4"
    }
  }'

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "product-feedback",
    "type": "text",
    "comment": "User requested dark mode support — 3rd request this week",
    "context": {
      "source": "ai-agent",
      "category": "feature-request",
      "priority": "high"
    }
  }'

🛡️Content Security Policy (CSP)

If your website uses a Content Security Policy, you'll need to allow the Pollenate widget script and API endpoints. Without the correct CSP directives, the widget will load but fail to submit feedback or track impressions.

Refused to connect to 'https://api.pollenate.dev/collect' because it violates the document's Content Security Policy.

[Pollenate] Error: TypeError: Failed to fetch. Refused to connect because it violates the document's Content Security Policy.

Required CSP Directives

Add the following origins to your Content Security Policy to allow the Pollenate widget to function correctly:

Example: HTTP Header

If you set your CSP via an HTTP response header, add the Pollenate origins to the relevant directives:

Content-Security-Policy: 
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';

Example: HTML Meta Tag

If you set your CSP via a <meta> tag, include the Pollenate origins:

<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';
">

Example: Nginx

add_header Content-Security-Policy "
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';
" always;

Example: Apache

Header set Content-Security-Policy "  script-src 'self' https://pollenate.dev;   connect-src 'self' https://api.pollenate.dev;   style-src 'self' 'unsafe-inline';"

Example: Next.js

In your next.config.js:

const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: [
      "script-src 'self' https://pollenate.dev",
      "connect-src 'self' https://api.pollenate.dev",
      "style-src 'self' 'unsafe-inline'",
    ].join('; '),
  },
];

module.exports = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};