Submit Rating

Overview

This endpoint accepts binary ratings (thumbs up/down, helpful/not helpful) from users. It’s designed for quick sentiment capture without requiring detailed feedback text.

Authentication

No authentication required. The endpoint uses the project_key to associate ratings with your project.

Ensure your project key is kept secure and only used on your own domains. Configure allowed origins in your project settings to prevent unauthorized submissions.

Request

project_key

string

required

Your project’s unique identifier (UUID format)Example: ee74a646-0761-4642-ba86-d8754622cdeb

value

boolean

required

The rating value

true - Positive rating (helpful, thumbs up)
false - Negative rating (not helpful, thumbs down)

path

string

required

The page path where the rating was submittedExample: /docs/getting-startedBest Practice: Use window.location.pathname to capture the current page

version

string

Application or content version (optional)Helps correlate ratings with specific releases or content updates.Examples: 1.2.3, v2.0.0-beta, 2024-12-03

submitted_by

string

User identifier (optional)Validation:

Max 255 characters
Alphanumeric characters, hyphens, and underscores only
Pattern: ^[a-zA-Z0-9_-]+$

Examples: user_12345, cust-abc-123, USR_98765

Only pass user IDs, not personally identifiable information (PII) like emails or names. This maintains GDPR compliance while allowing you to track ratings by user.

Response

status

number

HTTP status code

204 - Rating submitted successfully (No Content)
400 - Invalid request (missing required fields, invalid format)
404 - Project not found
429 - Rate limit exceeded

Success Response

HTTP/1.1 204 No Content

The response body is empty on success. A 204 No Content status indicates the rating was recorded.

Error Responses

{
  "error": "Invalid request",
  "details": "Missing required field: project_key"
}

Examples

Basic Rating Submission

const response = await fetch('https://seggwat.com/api/v1/rating/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project_key: 'ee74a646-0761-4642-ba86-d8754622cdeb',
    value: true,  // Helpful
    path: window.location.pathname
  })
});

if (response.ok) {
  console.log('Rating submitted successfully');
} else {
  console.error('Failed to submit rating');
}

With Version Tracking

await fetch('https://seggwat.com/api/v1/rating/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project_key: 'ee74a646-0761-4642-ba86-d8754622cdeb',
    value: false,  // Not helpful
    path: '/docs/api-reference',
    version: '2.1.0'
  })
});

With User Tracking

await fetch('https://seggwat.com/api/v1/rating/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project_key: 'ee74a646-0761-4642-ba86-d8754622cdeb',
    value: true,
    path: '/help/troubleshooting',
    submitted_by: 'user_12345'
  })
});

React Component Example

import { useState } from 'react';

function HelpfulRating({ projectKey }) {
  const [state, setState] = useState('idle'); // idle | yes | no | error

  const submitRating = async (helpful) => {
    setState('loading');

    try {
      const response = await fetch('https://seggwat.com/api/v1/rating/submit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          project_key: projectKey,
          value: helpful,
          path: window.location.pathname,
        }),
      });

      if (response.ok) {
        setState(helpful ? 'yes' : 'no');
      } else {
        setState('error');
      }
    } catch (error) {
      console.error('Error submitting rating:', error);
      setState('error');
    }
  };

  return (
    <div>
      <p>Was this page helpful?</p>
      {state === 'idle' && (
        <div>
          <button onClick={() => submitRating(true)}>Yes</button>
          <button onClick={() => submitRating(false)}>No</button>
        </div>
      )}
      {state === 'yes' && <p>Thanks for your feedback! 🎉</p>}
      {state === 'no' && <p>Thanks — we'll try to improve this page.</p>}
      {state === 'error' && <p>Something went wrong. Please try again later.</p>}
    </div>
  );
}

Vue Component Example

<template>
  <div>
    <p>Was this page helpful?</p>
    <div v-if="state === 'idle'">
      <button @click="submitRating(true)">Yes</button>
      <button @click="submitRating(false)">No</button>
    </div>
    <p v-if="state === 'yes'">Thanks for your feedback! 🎉</p>
    <p v-if="state === 'no'">Thanks — we'll try to improve this page.</p>
    <p v-if="state === 'error'">Something went wrong. Please try again later.</p>
  </div>
</template>

<script>
export default {
  props: {
    projectKey: {
      type: String,
      required: true
    }
  },
  data() {
    return {
      state: 'idle'
    };
  },
  methods: {
    async submitRating(helpful) {
      this.state = 'loading';

      try {
        const response = await fetch('https://seggwat.com/api/v1/rating/submit', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            project_key: this.projectKey,
            value: helpful,
            path: window.location.pathname,
          }),
        });

        if (response.ok) {
          this.state = helpful ? 'yes' : 'no';
        } else {
          this.state = 'error';
        }
      } catch (error) {
        console.error('Error submitting rating:', error);
        this.state = 'error';
      }
    }
  }
};
</script>

Rate Limiting

The endpoint implements rate limiting to prevent abuse:

Client-side: The helpful widget enforces a 10-second cooldown between submissions
Server-side: Additional rate limiting may apply based on IP address or project

If you hit the rate limit, you’ll receive a 429 Too Many Requests response with a retry_after value in seconds.

Best Practices

Security

Never expose your project key in public repositories
Configure allowed origins in your project settings
Validate ratings on the server side (the API does this for you)
Don’t send PII in the submitted_by field

Performance

Implement client-side rate limiting (10s cooldown minimum)
Cache the user’s rating state in localStorage to prevent duplicate submissions
Use asynchronous requests (don’t block the UI)
Handle network errors gracefully

User Experience

Disable buttons after submission to prevent accidental double-clicks
Show clear feedback messages (success, error)
Consider allowing users to change their rating (with a reset mechanism)
Place rating widgets at the end of content, not the beginning

Analytics

Use version to correlate ratings with releases
Track path consistently (normalize trailing slashes)
Use submitted_by for authenticated users to track patterns
Monitor ratings over time to identify content quality trends

CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser requests. Ensure your domain is listed in the allowed origins for your project. Allowed methods: POST, OPTIONS Allowed headers: Content-Type

Webhooks

Currently, ratings do not trigger webhooks. This feature may be added in a future update. Instead of calling this API directly, consider using the pre-built helpful rating widget:

<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"></script>

The widget handles:

API calls and error handling
Rate limiting
User state management
Internationalization
Accessibility
Mobile responsiveness

Helpful Widget Documentation

Learn more about the pre-built helpful rating widget

Submit Feedback

Submit detailed text feedback with categories and metadata

List Feedback

Retrieve submitted feedback and ratings for your project

Using the API

Projects

Feedback

Ratings

Health

Overview

Authentication

Request

Response

Success Response

Error Responses

Examples

Basic Rating Submission

With Version Tracking

With User Tracking

React Component Example

Vue Component Example

Rate Limiting

Best Practices

CORS

Webhooks

Widget Integration

Helpful Widget Documentation

Submit Feedback

List Feedback

Using the API

Projects

Feedback

Ratings

Health

​Overview

​Authentication

​Request

​Response

​Success Response

​Error Responses

​Examples

​Basic Rating Submission

​With Version Tracking

​With User Tracking

​React Component Example

​Vue Component Example

​Rate Limiting

​Best Practices

​CORS

​Webhooks

​Widget Integration

Helpful Widget Documentation

​Related Endpoints

Submit Feedback

List Feedback

Overview

Authentication

Request

Response

Success Response

Error Responses

Examples

Basic Rating Submission

With Version Tracking

With User Tracking

React Component Example

Vue Component Example

Rate Limiting

Best Practices

CORS

Webhooks

Widget Integration

Related Endpoints