Skip to main content
POST
/
projects
/
{project_id}
/
ratings
/
typed
curl -X POST "https://seggwat.com/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/ratings/typed" \
  -H "X-API-Key: oat_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": {
      "type": "helpful",
      "value": true
    },
    "context": {
      "path": "/docs/getting-started"
    }
  }'

{
  "id": "507f1f77bcf86cd799439013",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "rating_type": "helpful",
  "value": {
    "type": "helpful",
    "value": true
  },
  "path": "/docs/getting-started",
  "created_at": "2024-01-16T14:25:00Z",
  "archived": false
}

​
Overview

This endpoint supports creating ratings of multiple types:
  • Helpful - Binary thumbs up/down ratings
  • Star - 1-5 (or custom scale) star ratings
  • NPS - Net Promoter Score ratings (0-10)
For simple helpful ratings, you can also use the legacy endpoint.

​
Authentication

​
X-API-Key
string
required
Your Organization Access Token. See Authentication for details.

​
Path Parameters

​
project_id
string
required
The unique identifier of the project. You can find this in the dashboard under project settings.

​
Body Parameters

​
Rating Object (required)

The rating object contains the type and value. Structure varies by type: 
{
  "rating": {
    "type": "helpful",
    "value": true
  }
}
FieldTypeDescription
type"helpful"Rating type identifier
valuebooleantrue for helpful, false for not helpful

​
Context Object (optional)

​
context.path
string
URL path where the rating relates to (e.g., /docs/getting-started).
​
context.version
string
Application version to track ratings against specific releases (e.g., 2.1.0).
​
context.submitted_by
string
User identifier who submitted the rating.
​
context.metadata
object
Optional key-value pairs for custom data.

​
Response

​
id
string
Unique identifier for the created rating.
​
project_id
string
The project this rating belongs to.
​
rating_type
string
The type of rating: helpful, star, or nps.
​
value
object
The rating value object (structure varies by type).
​
path
string
The URL path specified in the context (if provided).
​
version
string
Application version specified in the context (if provided).
​
submitted_by
string
User identifier specified in the context (if provided).
​
metadata
object
Custom metadata specified in the context (if provided).
​
created_at
string
ISO 8601 timestamp when the rating was created.
​
archived
boolean
Whether the rating has been archived (always false for newly created ratings).

​
Use Cases

  • Product Reviews: Collect star ratings from customers
  • Customer Satisfaction: Track NPS scores over time
  • Documentation: Measure page helpfulness
  • Feature Feedback: Let users rate specific features
  • Survey Integration: Import ratings from external survey tools
curl -X POST "https://seggwat.com/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/ratings/typed" \
  -H "X-API-Key: oat_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": {
      "type": "helpful",
      "value": true
    },
    "context": {
      "path": "/docs/getting-started"
    }
  }'

{
  "id": "507f1f77bcf86cd799439013",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "rating_type": "helpful",
  "value": {
    "type": "helpful",
    "value": true
  },
  "path": "/docs/getting-started",
  "created_at": "2024-01-16T14:25:00Z",
  "archived": false
}

​
Validation Rules

TypeValue RangeNotes
Helpfultrue or falseBoolean only
Star1 to max_starsmax_stars defaults to 5, max is 10
NPS0 to 10Integer only