You can list every testimonial in a Space with a GET request to https://api.testimonial.to/v1/testimonials. Send your Space API key in the Authorization: Bearer API_KEY header. The response is a JSON array of video and text testimonials (newest first).

REST API access is on Ultimate and Ultimate+ (per Space). Open Settings → Plan to upgrade. Each API key belongs to one Space and only returns testimonials from that Space.

Before you start

Plan: The REST API is on Ultimate and Ultimate+. On Free or Starter, API Key is disabled until you upgrade.
Scope: One API key per Space. Results are only from the Space where you copied the key.
Authentication: Every request needs Authorization: Bearer API_KEY. Missing or invalid keys return 401.
Video readiness: Video testimonials are included only when processing is complete (video.asset.ready or video.asset.static_renditions.ready).

Note: Keep your Space API key secret. Anyone with the key can read that Space’s testimonials.

Get your Space API key

Open the dashboard.
On the Space you want to use, click the ⋯ (options) button on the space card.
Choose API Key.
In the API Key modal, click Copy API Key. Use that value as API_KEY in the examples below.

Query parameters

All parameters are optional. Omit them to return every ready testimonial in the Space.

type — video or text. Omit to return both.
liked=true — Return testimonials on your Wall of Love (liked), not every testimonial in the Space.
highlighted=true — Return only highlighted testimonials (isHighlighted).
tag — Filter by tag display name. Repeat the parameter for more than one tag. A testimonial matches if it has any of the listed tags. Use the labels from Manage tags in the Space.
limit — Maximum number of testimonials to return (integer).

Note: This endpoint does not use page, offset, or cursor pagination. It returns one JSON array. Use limit to cap the size. You can combine parameters, for example type=video&liked=true&limit=20.

Make a request

Replace API_KEY with your Space API key. URL-encode tag names and other special characters.

curl "https://api.testimonial.to/v1/testimonials" \
  -H "Authorization: Bearer API_KEY"

curl "https://api.testimonial.to/v1/testimonials?type=video" \
  -H "Authorization: Bearer API_KEY"

curl "https://api.testimonial.to/v1/testimonials?type=text" \
  -H "Authorization: Bearer API_KEY"

Wall of Love (liked)

curl "https://api.testimonial.to/v1/testimonials?liked=true" \
  -H "Authorization: Bearer API_KEY"

curl "https://api.testimonial.to/v1/testimonials?type=video&liked=true" \
  -H "Authorization: Bearer API_KEY"

Highlighted

curl "https://api.testimonial.to/v1/testimonials?highlighted=true" \
  -H "Authorization: Bearer API_KEY"

Tags (OR match on display names)

curl "https://api.testimonial.to/v1/testimonials?tag=My%20tag&tag=My%20tag%202" \
  -H "Authorization: Bearer API_KEY"

Limit

curl "https://api.testimonial.to/v1/testimonials?limit=50" \
  -H "Authorization: Bearer API_KEY"

Response

A successful request returns HTTP 200 and a JSON array. Each item includes id, type (video or text), createdAt, spaceId (the Space alias when one is set), tags (when present), and a nested testimonial object.

Video objects include video_url, img_thumbnail, gif_thumbnail, excerpt, rating, and sent_by. Text objects include text (HTML stripped), rating, and sent_by.

Example response:

[
  {
    "createdAt": 1612582855000,
    "type": "video",
    "testimonial": {
      "rating": 5,
      "video_url": "https://stream.mux.com/my1pgRrHGSx1zILB9i7KVeWk39wUGtv9Y.m3u8",
      "img_thumbnail": "https://image.mux.com/my1pgRrHGSx1zILB9i7KVeWk39wUGtv9Y/thumbnail.png",
      "gif_thumbnail": "https://image.mux.com/my1pgRrHGSx1zILB9i7KVeWk39wUGtv9Y/animated.gif",
      "sent_by": {
        "email": "[email protected]",
        "name": "Maya Chen",
        "socialLink": "www.linkedin.com/in/example/",
        "title": "Head of Marketing at Northwind Labs"
      }
    }
  },
  {
    "createdAt": 1611465973552,
    "type": "text",
    "testimonial": {
      "rating": 5,
      "text": "Testimonial has been a big part of my conversions. I've had more inbound from people who found us through the Wall of Love.",
      "sent_by": {
        "email": "[email protected]",
        "name": "Jordan Hale",
        "socialLink": "https://twitter.com/example",
        "title": "Founder of Brightline",
        "avatar": "https://firebasestorage.googleapis.com/v0/b/testimonialto.appspot.com/o/avatars%2Fexample.png?alt=media"
      }
    }
  }
]

Common error responses:

401 — Missing or invalid Authorization header.
400 with Space does not exist — The Space linked to the API key was not found.
404 — Space not found or unavailable.

Check that a key works

You can confirm a Space API key with GET /v1/verify and the same Authorization: Bearer API_KEY header. A valid key returns HTTP 200 with the Space id and the account email. An invalid or missing key returns 401.

curl "https://api.testimonial.to/v1/verify" \
  -H "Authorization: Bearer API_KEY"

Related API guides

Need help? Message us in the chat widget.

API - GET all testimonials