SeggWat - Collect Feedback & Build Customer Loyalty

Overview

The Ideas API powers the SeggWat Ideas Portal, allowing your users to submit feature requests, vote on existing ideas, leave comments, and browse what your team is planning. All endpoints are public — no API key is required. Access is controlled via the project_key in the URL path and Origin header validation.

Authentication

No API key required. The project_key in the URL path identifies your project. Configure allowed origins in your project settings to restrict which domains can call these endpoints.

Warning

Configure allowed origins in your project settings before going to production. Without this, any domain can submit ideas and votes on behalf of your project.

End-User Identity

Most write endpoints (vote, suggest, comment) require identifying the end user. There are two approaches depending on your project configuration:

Without end-user auth (default) — Pass enduser_id (any stable string, e.g. a user ID from your system) on every write request. Optionally include enduser_email to notify the user when their idea is responded to.
With end-user auth enabled — Pass a signed token generated by your backend. When end-user authentication is configured on your project and a valid token is provided, the token's sub claim is used as the user identity and subscription_id enables reward discounts.

Info

When your project does not have end-user authentication configured, the token parameter is ignored and enduser_id must always be provided. See Portal Authentication to enable token-based auth.

The user_has_voted field in list responses is only populated when enduser_id or a valid token is provided.

Rate Limits

Endpoint type	Limit
Read endpoints (list, get, tags, stats, comments)	120 requests/min per IP
Vote / unvote	5 requests/min per IP
Suggest idea	5 requests/min per IP
Create comment	5 requests/min per IP

CORS

All endpoints support Cross-Origin Resource Sharing (CORS) for browser requests. Your domain must be listed in the project's allowed origins.

List Ideas

GET /api/v1/p/{project_key}/ideas

Returns a paginated list of ideas for the project, along with the portal configuration for rendering your branded Ideas Portal.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format)

Example: 550e8400-e29b-41d4-a716-446655440000

Query Parameters

offsetnumber

Pagination offset. Defaults to 0.

limitnumber

Items per page. Defaults to 20, maximum 100.

sort_by_votesboolean

Sort order. true returns most-voted ideas first. false returns newest first. Defaults to true.

enduser_idstring

End-user identifier for tracking which ideas the user has voted on. Required to populate user_has_voted in the response.

tokenstring

Signed auth token. When valid, overrides enduser_id for vote state tracking.

tagstring

Filter ideas by tag slug. Returns only ideas with the matching tag.

statusstring

Filter by status. One of: Open, Planned, Started, Completed, Declined, Duplicate.

searchstring

Full-text search across idea titles and descriptions.

Response

itemsarray

List of idea objects.

has_moreboolean

Whether additional pages of results exist.

totalnumber

Total number of ideas matching the current filters.

portal_configobject | null

Branding configuration for your Ideas Portal. Absent when no portal configuration has been saved for the project.

Examples

curl "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas?limit=20&sort_by_votes=true&enduser_id=user-123"

Get Single Idea

GET /api/v1/p/{project_key}/ideas/{idea_id}

Returns a single idea with its full details and portal configuration.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

idea_idstringrequired

The idea's unique identifier.

Query Parameters

enduser_idstring

End-user identifier for populating user_has_voted.

tokenstring

Signed auth token. Overrides enduser_id when valid.

Response

featureobject

The idea object. Same shape as items in the List Ideas response.

portal_configobject

Branding configuration. Same shape as in the List Ideas response.

Examples

curl "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/idea-abc123?enduser_id=user-123"

Vote for Idea

POST /api/v1/p/{project_key}/ideas/{idea_id}/vote

Casts a vote for an idea on behalf of an end user. If the user has already voted, returns already_voted without error.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

idea_idstringrequired

The idea to vote for.

Request Body

enduser_idstringrequired

Stable identifier for the end user. Always required when your project does not have end-user authentication configured. If end-user auth is enabled and a valid token is provided, the token's sub claim is used instead.

enduser_emailstring

End user's email address. Used to notify the user when your team responds to the idea.

tokenstring

Signed auth token. When valid, overrides enduser_id. Required if your project has end-user auth enabled.

Response

resultstring

"created" — Vote was recorded successfully.

"already_voted" — The user had already voted for this idea. No duplicate vote was created.

Examples

curl -X POST "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/idea-abc123/vote" \
  -H "Content-Type: application/json" \
  -d '{"enduser_id": "user-123", "enduser_email": "user@example.com"}'

Remove Vote

DELETE /api/v1/p/{project_key}/ideas/{idea_id}/vote

Removes a previously cast vote. If the user has not voted for this idea, returns not_voted without error.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

idea_idstringrequired

The idea to remove the vote from.

Query Parameters

enduser_idstringrequired

tokenstring

Signed auth token. Overrides enduser_id when valid. Required if your project has end-user auth enabled.

Response

resultstring

"removed" — Vote was removed successfully.

"not_voted" — The user had not voted for this idea. No action was taken.

Examples

curl -X DELETE "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/idea-abc123/vote?enduser_id=user-123"

Suggest Idea

POST /api/v1/p/{project_key}/ideas/suggest

Submits a new feature idea on behalf of an end user. The idea is added to the board and visible to other users immediately (subject to your project's moderation settings).

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

Request Body

titlestringrequired

Idea title. Short and descriptive.

Example: "Dark mode support"

descriptionstringrequired

Full description of the idea. Cannot be empty.

Example: "It would be great to have a dark mode option to reduce eye strain when using the app at night."

enduser_idstringrequired

Stable identifier for the end user. Required unless a valid token is provided.

enduser_emailstring

End user's email address. Used to notify the user when your team responds to their idea.

tokenstring

Signed auth token. When valid, overrides enduser_id. The subscription_id claim in the token enables reward discounts for idea submissions. Required if your project has end-user auth enabled.

Response

idea_idstring

The unique identifier of the newly created idea.

Examples

curl -X POST "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/suggest" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Dark mode support",
    "description": "Add a dark mode option to reduce eye strain at night.",
    "enduser_id": "user-123",
    "enduser_email": "user@example.com"
  }'

GET /api/v1/p/{project_key}/tags

Returns all tags configured for the project. Use tags to filter the ideas list or to display a tag browser in your portal.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

Response

tagsarray

List of tag objects.

Examples

curl "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/tags"

Idea Stats

GET /api/v1/p/{project_key}/ideas/stats

Returns idea counts grouped by status. Useful for rendering a status filter bar with counts in your portal.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

Response

countsarray

List of objects with status (string) and count (number) fields, one entry per status that has at least one idea.

totalnumber

Total number of ideas across all statuses.

Examples

curl "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/stats"

List Comments

GET /api/v1/p/{project_key}/ideas/{idea_id}/comments

Returns paginated top-level comments for an idea, each with their nested replies.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

idea_idstringrequired

The idea to fetch comments for.

Query Parameters

offsetnumber

Pagination offset. Defaults to 0.

limitnumber

Items per page. Defaults to 20, maximum 100.

Response

itemsarray

List of top-level comment thread objects.

has_moreboolean

Whether additional pages of top-level comments exist.

totalnumber

Total number of top-level comments for this idea.

Examples

curl "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/idea-abc123/comments"

Create Comment

POST /api/v1/p/{project_key}/ideas/{idea_id}/comments

Submits a comment or reply on an idea on behalf of an end user.

Path Parameters

project_keystringrequired

Your project's unique identifier (UUID format).

idea_idstringrequired

The idea to comment on.

Request Body

bodystringrequired

The comment text. Cannot be empty.

parent_idstring | null

ID of the comment to reply to. Omit or pass null to create a top-level comment.

enduser_idstringrequired

Stable identifier for the end user. Required unless a valid token is provided.

enduser_emailstring

End user's email address. Used to notify the user of replies to their comment.

tokenstring

Signed auth token. Overrides enduser_id when valid. Required if your project has end-user auth enabled.

Response

comment_idstring

The unique identifier of the newly created comment.

Examples

# Top-level comment
curl -X POST "https://seggwat.com/api/v1/p/550e8400-e29b-41d4-a716-446655440000/ideas/idea-abc123/comments" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "This would be incredibly useful for night-time use!",
    "parent_id": null,
    "enduser_id": "user-123",
    "enduser_email": "user@example.com"
  }'

Error Responses

{
  "error": "Title is required"
}

Status	Description
`400`	Invalid request — missing required fields or invalid values
`403`	Origin not in the project's allowed origins list
`404`	Project or idea not found
`429`	Rate limit exceeded — slow down requests
`500`	Internal server error

Overview

Authentication

End-User Identity

Rate Limits

CORS

List Ideas

Path Parameters

Query Parameters

Response

Examples

Get Single Idea

Path Parameters

Query Parameters

Response

Examples

Vote for Idea

Path Parameters

Request Body

Response

Examples

Remove Vote

Path Parameters

Query Parameters

Response

Examples

Suggest Idea

Path Parameters

Request Body

Response

Examples

List Tags

Path Parameters

Response

Examples

Idea Stats

Path Parameters

Response

Examples

List Comments

Path Parameters

Query Parameters

Response

Examples

Create Comment

Path Parameters

Request Body

Response

Examples

Error Responses