REST API

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.prod.getfeedbackkit.com.

Feedback

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

{
  "items": [
    {
      "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"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

curl -X POST "https://api.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/api/v1/feedbacks/550e8400-.../comments" \
  -H "X-API-Key: your-api-key"

{
  "items": [
    {
      "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"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

curl -X POST "https://api.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/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.prod.getfeedbackkit.com/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.

feedback_count, vote_count, and comment_count count the same rows a customer can list: not merged, and not hidden by the Free cap. Those rows stay stored. The response fields are unchanged, so an older client keeps decoding.

Authenticated project metrics reads allow 60 requests per minute per client IP and path. The IP is the connection peer, or X-Forwarded-For when that peer address is missing. A suspended project answers 403. POST /events/track is not on that budget, and older clients keep the same paths and bodies.

• 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. The field is additive: a client that has never seen it keeps decoding the rest of the overview, and a current client treats a missing event_scope as all because servers that omit it do not narrow. POST /events/track is unchanged, and the web Events page announces predefined_only without refusing the request or dropping stored rows.
• retention_clamped — true when your plan narrowed the window you asked for. The request still succeeds.
• retention_window_days — your plan’s allowance: 30 days on Free, 90 on Pro, 365 on Team. Together with the applied date_from and date_to this makes “showing 90 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.