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

{
  "id": "507f1f77bcf86cd799439013",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": true,
  "path": "/docs/getting-started",
  "version": "2.1.0",
  "submitted_by": "user-abc-123",
  "created_at": "2024-01-16T14:25:00Z",
  "archived": false
}

​
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

​
value
boolean
required
Rating value: true for helpful (thumbs up), false for not helpful (thumbs down).
​
path
string
Optional URL path where the rating relates to (e.g., /docs/getting-started). Useful for tracking helpfulness of specific pages or documentation sections.
​
version
string
Optional application or documentation version to track ratings against specific releases (e.g., 2.1.0).
​
submitted_by
string
Optional user identifier who submitted the rating. Useful for tracking ratings from specific users in your system.

​
Response

​
id
string
Unique identifier for the created rating.
​
project_id
string
The project this rating belongs to.
​
value
boolean
Rating value: true for helpful, false for not helpful.
​
path
string
The URL path specified in the request (if provided).
​
version
string
Application version specified in the request (if provided).
​
submitted_by
string
User identifier specified in the request (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

This endpoint is ideal for:
  • n8n workflows: Automatically create ratings from external sources (surveys, support tickets, analytics)
  • Documentation systems: Programmatically submit page helpfulness ratings from custom doc platforms
  • Integration platforms: Connect SeggWat with tools like Zapier, Make, or custom integrations
  • Analytics pipelines: Feed user satisfaction data from your analytics system into SeggWat
  • Import tools: Migrate existing rating/helpfulness data into SeggWat
Unlike the widget submit endpoint (/rating/submit), this endpoint:
  • Requires API key authentication
  • Provides full organization and project ownership verification
  • Returns the complete created rating object
  • Designed for server-to-server communication
curl -X POST "https://seggwat.com/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/ratings" \
  -H "X-API-Key: oat_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "value": true,
    "path": "/docs/getting-started",
    "version": "2.1.0",
    "submitted_by": "user-abc-123"
  }'

{
  "id": "507f1f77bcf86cd799439013",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": true,
  "path": "/docs/getting-started",
  "version": "2.1.0",
  "submitted_by": "user-abc-123",
  "created_at": "2024-01-16T14:25:00Z",
  "archived": false
}

​
Rating Statistics

After creating ratings, you can retrieve aggregated statistics using the Get Rating Stats endpoint to analyze overall helpfulness across your documentation or product.