How does Lustre work?

Lustre works in three simple steps: Collect testimonials via shareable links, curate and organize them in your dashboard, then embed beautiful widgets on your website with one line of code.

Is there a free plan?

Yes! Lustre offers a generous free plan with 5 testimonials, 1 widget, and basic styles. No credit card required.

Do the widgets slow down my website?

No. Lustre widgets load asynchronously and are under 15KB. They have zero impact on your Core Web Vitals scores.

Can I customize the widget design?

Absolutely. Customize colors, fonts, layout, border radius, and switch between light and dark mode. White-label branding is available on paid plans so the widget looks native to your site.

Can I collect video testimonials?

Yes. Lustre supports both text and video testimonials. Customers can record directly from the collection page—no app install required. Videos are hosted and optimized automatically.

Does Lustre offer an API?

Yes. Lustre provides a full REST API for managing testimonials, widgets, and analytics programmatically. API access is available on Starter plans and above.

API Documentation

Everything you need to integrate Lustre into your workflow.

Introduction

The Lustre API gives you programmatic access to your testimonials, widgets, and projects. Use it to integrate Lustre with your existing tools, automate workflows, or build custom integrations.

Scale Plan Required— The REST API is available exclusively on the Scale plan. Upgrade from your dashboard to get started.

Base URL

text

https://uselustre.com/api/v1

Response Format

All responses are returned as JSON. Successful responses include the requested data. Error responses include an error field with a human-readable message.

Authentication

Authenticate your API requests by including your API key in the Authorization header.

Getting Your API Key

Navigate to your Dashboard → Settings → API Keys
Click Generate API Key
Give your key a descriptive name
Copy and store the key securely — it will only be shown once

Using Your API Key

Include the key as a Bearer token in every request:

bash

curl -H "Authorization: Bearer tj_live_your_api_key_here" \
  https://uselustre.com/api/v1/testimonials?projectId=YOUR_PROJECT_ID

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. If compromised, delete the key immediately and generate a new one.

Testimonials

GET/api/v1/testimonials

Retrieve a list of testimonials for a project.

Query Parameters

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to the project associated with your API key.
status	string	No	Filter by status: "pending", "approved", "featured", or "archived".
limit	number	No	Max results to return (1-100). Default: 50.
offset	number	No	Number of results to skip. Default: 0.

Response

json

{
  "testimonials": [
    {
      "id": "abc123",
      "projectId": "proj_456",
      "authorName": "Alex Thompson",
      "authorEmail": "alex@example.com",
      "authorTitle": "Head of Marketing",
      "authorCompany": "Vercel",
      "authorAvatar": null,
      "text": "Lustre made it incredibly easy...",
      "rating": 5,
      "status": "approved",
      "source": "collection_page",
      "createdAt": "2026-03-18T10:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Examples

bash

# cURL
curl -H "Authorization: Bearer tj_live_YOUR_KEY" \
  "https://uselustre.com/api/v1/testimonials?status=approved&limit=10"

javascript

// JavaScript (fetch)
const response = await fetch(
  "https://uselustre.com/api/v1/testimonials?status=approved&limit=10",
  {
    headers: {
      Authorization: "Bearer tj_live_YOUR_KEY",
    },
  }
);
const data = await response.json();
console.log(data.testimonials);

POST/api/v1/testimonials

Create a new testimonial programmatically. The testimonial will be created with status: "pending" and source: "api".

Request Body

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.
authorName	string	Yes	Name of the testimonial author.
authorEmail	string	No	Author's email address.
authorTitle	string	No	Author's title (e.g. "CEO").
authorCompany	string	No	Author's company name.
text	string	Yes	The testimonial text.
rating	number	Yes	Rating from 1 to 5.

Response (201 Created)

json

{
  "id": "new_testimonial_id",
  "projectId": "proj_456",
  "authorName": "Jane Doe",
  "authorEmail": "jane@example.com",
  "authorTitle": "CTO",
  "authorCompany": "Acme",
  "text": "Amazing product!",
  "rating": 5,
  "status": "pending",
  "source": "api",
  "createdAt": "2026-03-20T12:00:00.000Z"
}

Examples

bash

# cURL
curl -X POST "https://uselustre.com/api/v1/testimonials" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorName": "Jane Doe",
    "authorCompany": "Acme",
    "text": "Amazing product!",
    "rating": 5
  }'

javascript

// JavaScript (fetch)
const response = await fetch("https://uselustre.com/api/v1/testimonials", {
  method: "POST",
  headers: {
    Authorization: "Bearer tj_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    authorName: "Jane Doe",
    authorCompany: "Acme",
    text: "Amazing product!",
    rating: 5,
  }),
});
const data = await response.json();

PATCH/api/v1/testimonials

Update the status of a testimonial (approve, feature, archive, etc.).

Request Body

Parameter	Type	Required	Description
testimonialId	string	Yes	The ID of the testimonial to update.
status	string	Yes	"pending", "approved", "featured", or "archived".

Response

json

{
  "id": "testimonial_id",
  "status": "approved",
  "updatedAt": "2026-03-20T12:05:00.000Z"
}

Examples

bash

# cURL
curl -X PATCH "https://uselustre.com/api/v1/testimonials" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testimonialId": "abc123",
    "status": "approved"
  }'

Widgets

GET/api/v1/widgets

List all widgets for a project.

Query Parameters

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.

Response

json

{
  "widgets": [
    {
      "id": "widget_123",
      "projectId": "proj_456",
      "name": "Homepage Wall",
      "type": "wall",
      "config": {
        "theme": "light",
        "primaryColor": "#2563EB",
        "showRating": true,
        "showAvatar": true,
        "showCompany": true,
        "maxTestimonials": 10,
        "layout": "grid"
      },
      "isActive": true,
      "createdAt": "2026-03-15T10:00:00.000Z"
    }
  ],
  "total": 3
}

Examples

bash

# cURL
curl -H "Authorization: Bearer tj_live_YOUR_KEY" \
  "https://uselustre.com/api/v1/widgets"

javascript

// JavaScript (fetch)
const response = await fetch("https://uselustre.com/api/v1/widgets", {
  headers: {
    Authorization: "Bearer tj_live_YOUR_KEY",
  },
});
const data = await response.json();
console.log(data.widgets);

POST/api/v1/widgets

Create a new widget with default configuration.

Request Body

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.
name	string	Yes	Name for the widget (e.g. "Homepage Wall").
type	string	Yes	"wall", "carousel", "minimal", "badge", or "popup".

Response (201 Created)

json

{
  "id": "new_widget_id",
  "projectId": "proj_456",
  "name": "Homepage Wall",
  "type": "wall",
  "createdAt": "2026-03-20T12:00:00.000Z"
}

Examples

bash

# cURL
curl -X POST "https://uselustre.com/api/v1/widgets" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage Wall",
    "type": "wall"
  }'

Rate Limits

The API is rate-limited to ensure fair usage. Current limits are:

Endpoint	Limit	Window
GET requests	1,000 requests	Per hour
POST / PATCH requests	200 requests	Per hour

Rate limit information is included in every response via headers:

text

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

If you exceed the limit, the API will respond with a 429 Too Many Requests status code. Wait for the rate limit window to reset before retrying.

Errors

The API uses conventional HTTP status codes. All error responses include a JSON body with an error field.

Status Code	Meaning
200	Success
201	Created — resource was successfully created
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — missing or invalid API key
403	Forbidden — your plan does not have API access
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on our end

Error Response Format

json

{
  "error": "Missing or invalid Authorization header. Use: Bearer <api_key>"
}

API Documentation

Everything you need to integrate Lustre into your workflow.

Introduction

The Lustre API gives you programmatic access to your testimonials, widgets, and projects. Use it to integrate Lustre with your existing tools, automate workflows, or build custom integrations.

Scale Plan Required— The REST API is available exclusively on the Scale plan. Upgrade from your dashboard to get started.

Base URL

text

https://uselustre.com/api/v1

Response Format

All responses are returned as JSON. Successful responses include the requested data. Error responses include an error field with a human-readable message.

Authentication

Authenticate your API requests by including your API key in the Authorization header.

Getting Your API Key

Navigate to your Dashboard → Settings → API Keys
Click Generate API Key
Give your key a descriptive name
Copy and store the key securely — it will only be shown once

Using Your API Key

Include the key as a Bearer token in every request:

bash

curl -H "Authorization: Bearer tj_live_your_api_key_here" \
  https://uselustre.com/api/v1/testimonials?projectId=YOUR_PROJECT_ID

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. If compromised, delete the key immediately and generate a new one.

Testimonials

GET/api/v1/testimonials

Retrieve a list of testimonials for a project.

Query Parameters

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to the project associated with your API key.
status	string	No	Filter by status: "pending", "approved", "featured", or "archived".
limit	number	No	Max results to return (1-100). Default: 50.
offset	number	No	Number of results to skip. Default: 0.

Response

json

{
  "testimonials": [
    {
      "id": "abc123",
      "projectId": "proj_456",
      "authorName": "Alex Thompson",
      "authorEmail": "alex@example.com",
      "authorTitle": "Head of Marketing",
      "authorCompany": "Vercel",
      "authorAvatar": null,
      "text": "Lustre made it incredibly easy...",
      "rating": 5,
      "status": "approved",
      "source": "collection_page",
      "createdAt": "2026-03-18T10:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Examples

bash

# cURL
curl -H "Authorization: Bearer tj_live_YOUR_KEY" \
  "https://uselustre.com/api/v1/testimonials?status=approved&limit=10"

javascript

// JavaScript (fetch)
const response = await fetch(
  "https://uselustre.com/api/v1/testimonials?status=approved&limit=10",
  {
    headers: {
      Authorization: "Bearer tj_live_YOUR_KEY",
    },
  }
);
const data = await response.json();
console.log(data.testimonials);

POST/api/v1/testimonials

Create a new testimonial programmatically. The testimonial will be created with status: "pending" and source: "api".

Request Body

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.
authorName	string	Yes	Name of the testimonial author.
authorEmail	string	No	Author's email address.
authorTitle	string	No	Author's title (e.g. "CEO").
authorCompany	string	No	Author's company name.
text	string	Yes	The testimonial text.
rating	number	Yes	Rating from 1 to 5.

Response (201 Created)

json

{
  "id": "new_testimonial_id",
  "projectId": "proj_456",
  "authorName": "Jane Doe",
  "authorEmail": "jane@example.com",
  "authorTitle": "CTO",
  "authorCompany": "Acme",
  "text": "Amazing product!",
  "rating": 5,
  "status": "pending",
  "source": "api",
  "createdAt": "2026-03-20T12:00:00.000Z"
}

Examples

bash

# cURL
curl -X POST "https://uselustre.com/api/v1/testimonials" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorName": "Jane Doe",
    "authorCompany": "Acme",
    "text": "Amazing product!",
    "rating": 5
  }'

javascript

// JavaScript (fetch)
const response = await fetch("https://uselustre.com/api/v1/testimonials", {
  method: "POST",
  headers: {
    Authorization: "Bearer tj_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    authorName: "Jane Doe",
    authorCompany: "Acme",
    text: "Amazing product!",
    rating: 5,
  }),
});
const data = await response.json();

PATCH/api/v1/testimonials

Update the status of a testimonial (approve, feature, archive, etc.).

Request Body

Parameter	Type	Required	Description
testimonialId	string	Yes	The ID of the testimonial to update.
status	string	Yes	"pending", "approved", "featured", or "archived".

Response

json

{
  "id": "testimonial_id",
  "status": "approved",
  "updatedAt": "2026-03-20T12:05:00.000Z"
}

Examples

bash

# cURL
curl -X PATCH "https://uselustre.com/api/v1/testimonials" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testimonialId": "abc123",
    "status": "approved"
  }'

Widgets

GET/api/v1/widgets

List all widgets for a project.

Query Parameters

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.

Response

json

{
  "widgets": [
    {
      "id": "widget_123",
      "projectId": "proj_456",
      "name": "Homepage Wall",
      "type": "wall",
      "config": {
        "theme": "light",
        "primaryColor": "#2563EB",
        "showRating": true,
        "showAvatar": true,
        "showCompany": true,
        "maxTestimonials": 10,
        "layout": "grid"
      },
      "isActive": true,
      "createdAt": "2026-03-15T10:00:00.000Z"
    }
  ],
  "total": 3
}

Examples

bash

# cURL
curl -H "Authorization: Bearer tj_live_YOUR_KEY" \
  "https://uselustre.com/api/v1/widgets"

javascript

// JavaScript (fetch)
const response = await fetch("https://uselustre.com/api/v1/widgets", {
  headers: {
    Authorization: "Bearer tj_live_YOUR_KEY",
  },
});
const data = await response.json();
console.log(data.widgets);

POST/api/v1/widgets

Create a new widget with default configuration.

Request Body

Parameter	Type	Required	Description
projectId	string	No	Project ID. Defaults to key's project.
name	string	Yes	Name for the widget (e.g. "Homepage Wall").
type	string	Yes	"wall", "carousel", "minimal", "badge", or "popup".

Response (201 Created)

json

{
  "id": "new_widget_id",
  "projectId": "proj_456",
  "name": "Homepage Wall",
  "type": "wall",
  "createdAt": "2026-03-20T12:00:00.000Z"
}

Examples

bash

# cURL
curl -X POST "https://uselustre.com/api/v1/widgets" \
  -H "Authorization: Bearer tj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage Wall",
    "type": "wall"
  }'

Rate Limits

The API is rate-limited to ensure fair usage. Current limits are:

Endpoint	Limit	Window
GET requests	1,000 requests	Per hour
POST / PATCH requests	200 requests	Per hour

Rate limit information is included in every response via headers:

text

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

If you exceed the limit, the API will respond with a 429 Too Many Requests status code. Wait for the rate limit window to reset before retrying.

Errors

The API uses conventional HTTP status codes. All error responses include a JSON body with an error field.

Status Code	Meaning
200	Success
201	Created — resource was successfully created
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — missing or invalid API key
403	Forbidden — your plan does not have API access
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on our end

Error Response Format

json

{
  "error": "Missing or invalid Authorization header. Use: Bearer <api_key>"
}