API Reference

The Miniback API allows you to programmatically access and manage feedback and projects. The API provides comprehensive CRUD operations for both feedback and projects, with plan-based access control.

⚡ Quick Start

Get API key: Project Settings → API Access → Generate Key

Test endpoint: curl -H "x-api-key: YOUR_KEY" https://www.miniback.io/api/projects

See API Security Guide for best practices

Plans: Hobby (POST only) • Builder (full CRUD, 10k calls/mo) • Studio (unlimited)

Plan-Based Access

Plan	Access Level	Endpoints	Rate Limit
Hobby	Limited	POST feedback only	200 calls/month
Builder	Full	All CRUD operations	10,000 calls/month
Studio	Full	All CRUD operations	Unlimited

Plan identifiers: The dashboard shows plans as Hobby, Builder, and Studio, and error messages use those display names (e.g. “Upgrade to Builder or Studio”). The API’s internal plan identifiers — the plan value returned in responses — are FREE, STARTER, and PRO.

Authentication

Miniback has two credential types. Pick the one that matches the operation:

Credential	Prefix	Scope	Get it from
Account token	`mba_`	Full, account-wide. Required for account-level endpoints (list/create projects) & the MCP server.	Settings → API
Project key	`mbk_`	A single project only: submit/read/update/delete that project’s feedback and its own settings.	Project page → API Access

Scoping (breaking change): A project key can no longer list other projects, create projects, or touch another project’s data — those return 403/404. Use an account token for account-wide access.

Both authenticate the same way (header or query param). The examples below use a generic your_api_key_here; substitute the token type each endpoint requires (account-level endpoints are marked below).

Getting an Account API Token

Sign in to your Miniback dashboard
Go to Settings → API
Click Generate token and copy it (shown once, starts with mba_)

Getting a Project Key

Open a project page
Scroll to the API Access section
Click Generate API Key if you don’t have one
Copy your key (starts with mbk_)

Using Your API Key

Header Authentication (Recommended):


curl -H "x-api-key: your_api_key_here" \
  https://www.miniback.io/api/projects/PROJECT_ID/feedback

Query Parameter Authentication:


curl "https://www.miniback.io/api/projects/PROJECT_ID/feedback?api_key=your_api_key_here"

Endpoints

Projects

List All Projects

Get all projects for the authenticated account.


GET /api/projects

Authentication Required: Account token (mba_), Builder/Studio plans only. Project keys are rejected with 403.

Example Request:


curl -H "x-api-key: mbk_abc123..." \
  "https://www.miniback.io/api/projects"

Example Response:


{
  "data": [
    {
      "id": "proj_123",
      "name": "My Website",
      "slug": "my-website",
      "status": "ACTIVE",
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-01-01T12:00:00.000Z"
    }
  ]
}

Get Project by ID

Get a specific project by ID.


GET /api/projects/{projectId}

Authentication Required: API key (Builder/Studio plans only)

Create Project

Create a new project.


POST /api/projects

Authentication Required: Account token (mba_), Builder/Studio plans only. Project keys are rejected with 403.

Request Body:


{
  "name": "New Project",
  "slug": "new-project" // optional
}

Update Project

Update an existing project.


PUT /api/projects/{projectId}

Authentication Required: API key (Builder/Studio plans only)

Request Body:


{
  "name": "Updated Project Name",
  "slug": "updated-slug" // optional
}

Delete Project

Delete a project and all its feedback.


DELETE /api/projects/{projectId}

Authentication Required: API key (Builder/Studio plans only)

Note: This permanently deletes the project and all associated feedback.

Manage API Keys

Get or regenerate API key for a project.


GET /api/projects/{projectId}/api-key
POST /api/projects/{projectId}/api-key

Authentication Required: API key (Builder/Studio plans only)

Feedback

List All Feedback

Get all feedback across all projects for the authenticated user.


GET /api/feedback

Authentication Required: Session (web UI) or API key (Builder/Studio plans only)

Query Parameters:

project or projectSlug: Filter by specific project
status: Filter by status (NEW, REVIEWED, RESOLVED)
source: Filter by source (WIDGET, API)
search: Search in feedback messages
start, end: Date range filter (ISO format)
page: Page number (default: 1)
pageSize: Items per page (default: 10, max: 100)

Example Request:


curl -H "x-api-key: mbk_abc123..." \
  "https://www.miniback.io/api/feedback?status=NEW&pageSize=20"

Get Feedback by ID

Get a specific feedback item by ID.


GET /api/feedback/{id}

Authentication Required: API key (Builder/Studio plans only)

Example Response:


{
  "data": {
    "id": "feedback_456",
    "message": "Great product! Love the new features.",
    "context": {
      "url": "https://example.com/page",
      "userAgent": "Mozilla/5.0..."
    },
    "status": "NEW",
    "source": "WIDGET",
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-01-01T12:00:00.000Z",
    "project": {
      "id": "proj_123",
      "name": "My Website",
      "slug": "my-website"
    }
  }
}

Update Feedback Status

Update the status of a feedback item.


PUT /api/feedback/{id}

Authentication Required: API key (Builder/Studio plans only)

Request Body:


{
  "status": "RESOLVED"
}

Valid Status Values:

NEW
REVIEWED
RESOLVED

Delete Feedback

Delete a feedback item.


DELETE /api/feedback/{id}

Authentication Required: API key (Builder/Studio plans only)

Get Project Feedback

Retrieve feedback for a specific project.


GET /api/projects/{projectId}/feedback

Query Parameters:

status (optional): Filter by status (NEW, REVIEWED, RESOLVED)
limit (optional): Number of items to return (default: 50, max: 100)
offset (optional): Number of items to skip for pagination (default: 0)

Example Request:


curl -H "x-api-key: mbk_abc123..." \
  "https://www.miniback.io/api/projects/proj_123/feedback?status=NEW&limit=10"

Example Response:


{
  "data": [
    {
      "id": "feedback_456",
      "message": "Great product! Love the new features.",
      "context": {
        "url": "https://example.com/page",
        "userAgent": "Mozilla/5.0...",
        "timestamp": "2025-01-01T12:00:00.000Z"
      },
      "status": "NEW",
      "createdAt": "2025-01-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Create Feedback

Submit new feedback to a project programmatically.


POST /api/projects/{projectId}/feedback

Authentication Required: API key (all plans, including Hobby)

Request Body:


{
  "message": "This is feedback about your product",
  "context": {
    "url": "https://example.com/page",
    "userAgent": "Mozilla/5.0...",
    "custom_field": "any additional data"
  }
}

Required Fields:

message (string): The feedback message

Optional Fields:

context (object): Additional metadata about the feedback

Example Request:


curl -X POST \
  -H "x-api-key: mbk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Bug found on checkout page", "context": {"url": "https://example.com/checkout"}}' \
  https://www.miniback.io/api/projects/proj_123/feedback

Example Response:


{
  "data": {
    "id": "feedback_789",
    "message": "Bug found on checkout page",
    "context": {
      "url": "https://example.com/checkout"
    },
    "status": "NEW",
    "createdAt": "2025-01-01T12:00:00.000Z"
  }
}

Error Responses

401 Unauthorized


{
  "error": "API key is required. Provide it via 'x-api-key' header or 'api_key' query parameter."
}


{
  "error": "GET requests are available on paid plans only. FREE plan users can only POST feedback. Upgrade to Builder or Studio for full API access."
}

403 Forbidden


{
  "error": "Invalid API key or project not found"
}


{
  "error": "Project limit reached. Upgrade your plan to create more projects."
}

404 Not Found


{
  "error": "Project not found"
}


{
  "error": "Feedback not found"
}

400 Bad Request


{
  "error": "Message is required and must be a string"
}

500 Internal Server Error


{
  "error": "Internal server error"
}

Rate Limits

Plan-based API limits:

Hobby Plan: 200 API calls per month (POST feedback only)
Builder Plan: 10,000 API calls per month (all endpoints)
Studio Plan: Unlimited API calls (all endpoints)

Pagination

For endpoints that return multiple items, use the limit and offset parameters:

limit: Number of items per page (max: 100, default: 50)
offset: Number of items to skip
hasMore: Boolean indicating if there are more items

Example pagination:


# First page
GET /api/projects/proj_123/feedback?limit=25&offset=0
 
# Second page
GET /api/projects/proj_123/feedback?limit=25&offset=25
 
# Third page
GET /api/projects/proj_123/feedback?limit=25&offset=50

Use Cases

Custom Dashboard


// Fetch recent feedback for dashboard
async function getFeedback() {
  const response = await fetch("/api/projects/proj_123/feedback?limit=10", {
    headers: {
      "x-api-key": "mbk_your_key_here",
    },
  });
  const data = await response.json();
  return data.data;
}

Webhook Integration


// Submit feedback from your own form
async function submitFeedback(message, pageUrl) {
  const response = await fetch("/api/projects/proj_123/feedback", {
    method: "POST",
    headers: {
      "x-api-key": "mbk_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message,
      context: { url: pageUrl },
    }),
  });
  return response.json();
}

Analytics Integration


import requests
 
# Python example for analytics
def get_feedback_stats():
    headers = {'x-api-key': 'mbk_your_key_here'}
 
    # Get all feedback statuses
    statuses = ['NEW', 'REVIEWED', 'RESOLVED']
    stats = {}
 
    for status in statuses:
        response = requests.get(
            f'/api/projects/proj_123/feedback?status={status}&limit=1',
            headers=headers
        )
        data = response.json()
        stats[status] = data['pagination']['total']
 
    return stats

Security

Keep your API key secure: Never expose it in client-side code
Use HTTPS: Always use HTTPS in production
Rotate keys: Regenerate API keys periodically
Monitor usage: Check your API usage in the dashboard

See the API Security Guide for detailed best practices.

API Security Best Practices - Secure API usage
Security - Domain restrictions and security features
Troubleshooting - Common issues and solutions

Need help? Contact support through your Miniback dashboard.

API Reference

Plan-Based Access

Authentication

Getting an Account API Token

Getting a Project Key

Using Your API Key

Endpoints

Projects

List All Projects

Get Project by ID

Create Project

Update Project

Delete Project

Manage API Keys

Feedback

List All Feedback

Get Feedback by ID

Update Feedback Status

Delete Feedback

Get Project Feedback

Create Feedback

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

400 Bad Request

500 Internal Server Error

Rate Limits

Pagination

Use Cases

Custom Dashboard

Webhook Integration

Analytics Integration

Security

Related Documentation