API Reference

The Feedbackfirst API allows you to programmatically access your products, feedback, and surveys.

Authentication

All API requests require an API key. Include it in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://feedbackfirst.dev/api/v1/products

Getting Your API Key

Go to your Feedbackfirst workspace
Click Settings → API Keys
Click "Generate New Key"
Copy the key and store it securely

Base URL

https://feedbackfirst.dev/api/v1

Products

List Products

GET /products

Response:

{
  "data": [
    {
      "id": "prod-123",
      "name": "Feedbackfirst",
      "description": "Collect and manage product feedback",
      "url": "https://feedbackfirst.dev",
      "category": "SaaS",
      "status": "MVP",
      "created_at": "2024-04-01T10:00:00Z",
      "feedback_count": 5,
      "update_count": 2
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Get Product

GET /products/{product_id}

Response:

{
  "id": "prod-123",
  "name": "Feedbackfirst",
  "description": "Collect and manage product feedback",
  "url": "https://feedbackfirst.dev",
  "category": "SaaS",
  "status": "MVP",
  "created_at": "2024-04-01T10:00:00Z",
  "feedback_count": 5,
  "update_count": 2
}

Create Product

POST /products

Request:

{
  "name": "Feedbackfirst",
  "description": "Collect and manage product feedback",
  "url": "https://feedbackfirst.dev",
  "category": "SaaS",
  "status": "MVP"
}

Response:

{
  "id": "prod-123",
  "name": "Feedbackfirst",
  "description": "Collect and manage product feedback",
  "url": "https://feedbackfirst.dev",
  "category": "SaaS",
  "status": "MVP",
  "created_at": "2024-04-01T10:00:00Z"
}

Update Product

PUT /products/{product_id}

Request:

{
  "name": "Feedbackfirst",
  "status": "Active"
}

Response:

{
  "id": "prod-123",
  "name": "Feedbackfirst",
  "status": "Active",
  "updated_at": "2024-04-08T10:00:00Z"
}

Feedback

List Feedback

GET /products/{product_id}/feedback

Query Parameters:

status (optional): submitted, validated, dismissed
type (optional): structured, quick
page (optional): Page number (default: 1)
per_page (optional): Items per page (default: 20)

Response:

{
  "data": [
    {
      "id": "fb-123",
      "product_id": "prod-456",
      "reviewer_id": "user-789",
      "reviewer_name": "John Doe",
      "type": "structured",
      "status": "submitted",
      "content": {
        "clear": "The onboarding is intuitive.",
        "confusing": "The pricing page is unclear.",
        "works": "The dashboard is fast.",
        "improve": "Add keyboard shortcuts."
      },
      "created_at": "2024-04-08T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

Get Feedback

GET /feedback/{feedback_id}

Response:

{
  "id": "fb-123",
  "product_id": "prod-456",
  "reviewer_id": "user-789",
  "reviewer_name": "John Doe",
  "type": "structured",
  "status": "submitted",
  "content": {
    "clear": "The onboarding is intuitive.",
    "confusing": "The pricing page is unclear.",
    "works": "The dashboard is fast.",
    "improve": "Add keyboard shortcuts."
  },
  "created_at": "2024-04-08T10:00:00Z"
}

Validate Feedback

POST /feedback/{feedback_id}/validate

Response:

{
  "id": "fb-123",
  "status": "validated",
  "credits_earned": 5,
  "updated_at": "2024-04-08T10:05:00Z"
}

Dismiss Feedback

POST /feedback/{feedback_id}/dismiss

Response:

{
  "id": "fb-123",
  "status": "dismissed",
  "updated_at": "2024-04-08T10:05:00Z"
}

Surveys

List Surveys

GET /products/{product_id}/surveys

Response:

{
  "data": [
    {
      "id": "survey-123",
      "product_id": "prod-456",
      "title": "Product Feedback",
      "questions": [
        {
          "id": "q1",
          "text": "How satisfied are you?",
          "type": "rating"
        }
      ],
      "credit_reward": 5,
      "response_count": 10,
      "created_at": "2024-04-01T10:00:00Z"
    }
  ]
}

Create Survey

POST /products/{product_id}/surveys

Request:

{
  "title": "Product Feedback",
  "questions": [
    {
      "text": "How satisfied are you?",
      "type": "rating"
    },
    {
      "text": "What could we improve?",
      "type": "text"
    }
  ],
  "credit_reward": 5
}

Response:

{
  "id": "survey-123",
  "product_id": "prod-456",
  "title": "Product Feedback",
  "questions": [...],
  "credit_reward": 5,
  "created_at": "2024-04-08T10:00:00Z"
}

List Survey Responses

GET /surveys/{survey_id}/responses

Response:

{
  "data": [
    {
      "id": "resp-123",
      "survey_id": "survey-456",
      "respondent_id": "user-789",
      "respondent_name": "Jane Doe",
      "responses": {
        "q1": "5",
        "q2": "The UI could be simpler"
      },
      "status": "submitted",
      "created_at": "2024-04-08T10:00:00Z"
    }
  ]
}

Updates

List Updates

GET /products/{product_id}/updates

Response:

{
  "data": [
    {
      "id": "update-123",
      "product_id": "prod-456",
      "title": "New Features Released",
      "description": "We've added keyboard shortcuts and improved performance.",
      "created_at": "2024-04-08T10:00:00Z"
    }
  ]
}

Create Update

POST /products/{product_id}/updates

Request:

{
  "title": "New Features Released",
  "description": "We've added keyboard shortcuts and improved performance."
}

Response:

{
  "id": "update-123",
  "product_id": "prod-456",
  "title": "New Features Released",
  "description": "We've added keyboard shortcuts and improved performance.",
  "created_at": "2024-04-08T10:00:00Z"
}

Error Handling

Errors are returned with appropriate HTTP status codes:

{
  "error": "Not found",
  "message": "Product not found",
  "code": "PRODUCT_NOT_FOUND"
}

Status Codes

200 — Success
400 — Bad request
401 — Unauthorized
404 — Not found
429 — Rate limited
500 — Server error

Rate Limiting

API requests are rate limited to 100 requests per minute per API key.

Check the X-RateLimit-* headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1712577600

Examples

Get all feedback for a product

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://feedbackfirst.dev/api/v1/products/prod-123/feedback

Validate feedback

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://feedbackfirst.dev/api/v1/feedback/fb-123/validate

Create a survey

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Feedback",
    "questions": [{"text": "How satisfied are you?", "type": "rating"}],
    "credit_reward": 5
  }' \
  https://feedbackfirst.dev/api/v1/products/prod-123/surveys