> ## Documentation Index
>
> Fetch the complete documentation index at: https://testimonial.to/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# API - GET all testimonials

> List testimonials from a Space with GET /v1/testimonials. Authenticate with your Space API key and optionally filter by type, Wall of Love, highlight, tag, or limit.

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](https://testimonial.to/settings?tab=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

1.  Open the [dashboard](https://testimonial.to/dashboard).
    
2.  On the Space you want to use, click the **⋯** (options) button on the space card.
    
    ![Space card options menu](https://apuqtiwclzoqhluvxsdm.supabase.co/storage/v1/object/public/help-center/22/2280189cb617934353a436777a52b684.png)
    
3.  Choose **API Key**.
    
4.  In the **API Key** modal, click **Copy API Key**. Use that value as `API_KEY` in the examples below.
    
    ![Copy API Key modal](https://apuqtiwclzoqhluvxsdm.supabase.co/storage/v1/object/public/help-center/41/410ca822a9669dffebb0a73c9c0c5273.png)
    

See also [API - How to get your API KEY](https://help.testimonial.to/en/articles/6814418-api-how-to-get-your-api-key).

---

## 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": "customer@email.com",        "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": "customer@email.com",        "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

-   [API - How to get your API KEY](https://help.testimonial.to/en/articles/6814418-api-how-to-get-your-api-key)
    
-   [API - Send request](https://help.testimonial.to/en/articles/6223146-api-send-request)
    
-   [API - Submit a text testimonial](https://help.testimonial.to/en/articles/6451677-api-submit-a-text-testimonial)
    
-   [API - Submit a video testimonial](https://help.testimonial.to/en/articles/6236786-api-submit-a-video-testimonial)
    

Need help? Message us in the chat widget.