REST API v1.0.0

Authentication

All API requests require authentication via the X-API-Key header. You can find your project API key in the FeedbackKit dashboard under Project Settings.

X-API-Key: your-project-api-key
X-User-Id: optional-user-id    # For personalized has_voted state
Content-Type: application/json

Field naming

Response bodies are snake_case — every field below is spelled exactly as it arrives on the wire.

Request bodies accept either casing. Both {"userId": …} and {"user_id": …} decode to the same field, so the camelCase request examples below are correct and so is the snake_case every official SDK sends.

Query parameters are read verbatim — neither convention applies, so includeMerged is spelled exactly as documented.

Endpoints Overview

All endpoints are prefixed with /api/v1. The base URL for production is https://api.feedbackkit.app.

Feedback

curl -X GET "https://api.feedbackkit.app/api/v1/feedbacks?status=approved" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-Id: user_12345"

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add dark mode support",
    "description": "It would be great to have a dark mode option.",
    "status": "approved",
    "category": "feature_request",
    "user_id": "user_12345",
    "vote_count": 42,
    "has_voted": false,
    "comment_count": 5,
    "created_at": "2026-02-01T10:30:00Z",
    "updated_at": "2026-02-05T14:20:00Z"
  }
]

curl -X POST "https://api.feedbackkit.app/api/v1/feedbacks" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add dark mode support",
    "description": "It would be great to have a dark mode option.",
    "category": "feature_request",
    "userId": "user_12345",
    "userEmail": "user@example.com"
  }'

curl -X GET "https://api.feedbackkit.app/api/v1/feedbacks/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-Id: user_12345"

Votes

curl -X POST "https://api.feedbackkit.app/api/v1/feedbacks/550e8400-.../votes" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "email": "user@example.com",
    "notifyStatusChange": true
  }'

{
  "feedback_id": "550e8400-e29b-41d4-a716-446655440000",
  "vote_count": 43,
  "has_voted": true
}

curl -X DELETE "https://api.feedbackkit.app/api/v1/feedbacks/550e8400-.../votes" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_12345"}'

Comments

curl -X GET "https://api.feedbackkit.app/api/v1/feedbacks/550e8400-.../comments" \
  -H "X-API-Key: your-api-key"

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "content": "Thanks for the suggestion! We're looking into this.",
    "user_id": "admin_user",
    "is_admin": true,
    "created_at": "2026-02-02T09:15:00Z"
  }
]

curl -X POST "https://api.feedbackkit.app/api/v1/feedbacks/550e8400-.../comments" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This would be really helpful!",
    "userId": "user_67890",
    "isAdmin": false
  }'

Users

curl -X POST "https://api.feedbackkit.app/api/v1/users/register" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "mrr": 9.99
  }'

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "user_id": "user_12345",
  "mrr": 9.99,
  "first_seen_at": "2026-01-15T08:00:00Z",
  "last_seen_at": "2026-02-08T12:30:00Z"
}

Events

curl -X POST "https://api.feedbackkit.app/api/v1/events/track" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "feedback_list",
    "userId": "user_12345",
    "properties": {
      "filter": "feature_request",
      "sort": "votes"
    }
  }'

Metrics

Eight read-only operations return aggregated project metrics and the raw event feed. Four answer for the project behind an X-API-Key; four are nested under /projects/:id/metrics, take an admin bearer token, and additionally answer the SDK-user and revenue measures.

A narrowed answer is a 200, not an error

Two subscription axes can narrow a metrics answer, and neither makes the feature unavailable. Every metrics response echoes what the server actually ran, so a low figure always arrives with a machine-readable reason attached — read the value, never infer it from an absence.

FeedbackKit’s own three predefined events — feedback_list, feedback_detail and submit_feedback — are readable on every tier. Below Pro your own event names are still ingested and retained; they simply are not counted, and they become readable on upgrade with no re-tracking.

• event_scope — all, or predefined_only when custom event names were excluded. It narrows only the two event measures, event_count and unique_event_users; no other measure is ever affected by it.
• retention_clamped — true when your plan narrowed the window you asked for. The request still succeeds.
• retention_window_days — your plan’s allowance. Together with the applied date_from and date_to this makes “showing 30 of the 180 days you asked for” computable from the response alone.

The one 402

METRICS_CUSTOM_EVENTS_REQUIRE_PRO is this family’s only payment-required refusal. It is raised on exactly three requests, each of which is exclusively about custom event names and so has no narrower honest answer: a breakdown by event name, a filter naming an event outside the three predefined ones, and any request to the raw event feed. Everything else a plan affects comes back as a narrower 200.

Two different error bodies

The metrics family is not uniformly enveloped, and a client that assumes an error code is always present will fail on a 401. Failures raised by the metrics API itself — its 400s, the 402, and the API-key surface’s measure 403 — carry error as an object with a stable code. Failures raised by the shared authentication, authorization and rate-limiting layers — 401, the suspended-project and no-access 403s, 404, 429 and 500 — use the server-wide shape below, where error is a boolean and there is no code. Same property name, incompatible types; the OpenAPI document declares both for every status that can carry either.

Models

Error Handling

All errors follow a consistent format with an error boolean and a human-readable reason string.

{
  "error": true,
  "reason": "Invalid API key"
}

HTTP Status Codes

Subscription Tiers

Some API features are limited by subscription tier. Exceeding limits returns a 402 Payment Required response.