REST API Reference

curl -H "Authorization: Bearer sk_live_your_key_here" \
  https://saywall.io/api/v1/testimonials

curl -H "Authorization: Bearer sk_live_..." \
  "https://saywall.io/api/v1/testimonials?tag=saas,b2b&sort=rating&limit=10"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "SayWall made it incredibly easy to collect and display our customer testimonials.",
      "author": {
        "name": "Jane Smith",
        "role": "Head of Marketing",
        "handle": null,
        "avatar_url": "https://example.com/avatar.jpg"
      },
      "rating": 5,
      "source": "manual",
      "source_url": null,
      "media_type": "text",
      "media_url": null,
      "tags": ["saas", "b2b"],
      "posted_at": "2026-03-15T10:30:00Z",
      "created_at": "2026-03-15T10:30:00Z",
      "video": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

curl -H "Authorization: Bearer sk_live_..." \
  https://saywall.io/api/v1/testimonials/550e8400-e29b-41d4-a716-446655440000

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "SayWall made it incredibly easy to collect and display our customer testimonials.",
    "author": {
      "name": "Jane Smith",
      "role": "Head of Marketing",
      "handle": null,
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "rating": 5,
    "source": "manual",
    "source_url": null,
    "media_type": "text",
    "media_url": null,
    "tags": ["saas", "b2b"],
    "posted_at": "2026-03-15T10:30:00Z",
    "created_at": "2026-03-15T10:30:00Z",
    "video": null
  }
}

# Testimonials with exactly 5 stars
?rating=5
 
# Testimonials with 4 or 5 stars
?rating_min=4
 
# Testimonials with 1-3 stars
?rating_max=3

# Has any of these tags
?tag=saas,enterprise
 
# Has ALL of these tags
?tag=saas,enterprise&tag_mode=all
 
# Exclude testimonials with these tags
?tag=internal&tag_mode=exclude

# Only Google and Trustpilot reviews
?source=google,trustpilot
 
# Only manually added testimonials
?source=manual

# Only video testimonials
?media_type=video
 
# Text and image testimonials
?media_type=text,image

# Search testimonial content
?search=amazing product

# 5-star Google reviews tagged "enterprise", newest first
?rating=5&source=google&tag=enterprise&sort=newest&limit=5

{
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 85,
    "total_pages": 5,
    "has_next": true,
    "has_prev": true
  }
}

let page = 1;
let hasNext = true;
 
while (hasNext) {
  const res = await fetch(
    `https://saywall.io/api/v1/testimonials?page=${page}&limit=100`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const { data, pagination } = await res.json();
 
  // Process data...
 
  hasNext = pagination.has_next;
  page++;
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

# List all testimonials
curl -H "Authorization: Bearer $SAYWALL_API_KEY" \
  https://saywall.io/api/v1/testimonials
 
# Get 5-star testimonials tagged "featured"
curl -H "Authorization: Bearer $SAYWALL_API_KEY" \
  "https://saywall.io/api/v1/testimonials?rating=5&tag=featured&limit=5"

const API_KEY = process.env.SAYWALL_API_KEY;
 
async function getTestimonials(params?: Record<string, string>) {
  const url = new URL("https://saywall.io/api/v1/testimonials");
  if (params) {
    Object.entries(params).forEach(([key, value]) =>
      url.searchParams.set(key, value)
    );
  }
 
  const res = await fetch(url.toString(), {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
 
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error.message);
  }
 
  return res.json();
}
 
// Usage
const { data, pagination } = await getTestimonials({
  tag: "featured",
  sort: "rating",
  limit: "10",
});

import requests
import os
 
API_KEY = os.environ["SAYWALL_API_KEY"]
BASE_URL = "https://saywall.io/api/v1"
 
def get_testimonials(**params):
    response = requests.get(
        f"{BASE_URL}/testimonials",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()
 
# Usage
result = get_testimonials(tag="featured", sort="rating", limit=10)
for testimonial in result["data"]:
    print(f"{testimonial['author']['name']}: {testimonial['content'][:100]}")

// app/testimonials/page.tsx
async function getTestimonials() {
  const res = await fetch(
    "https://saywall.io/api/v1/testimonials?tag=featured&sort=newest",
    {
      headers: {
        Authorization: `Bearer ${process.env.SAYWALL_API_KEY}`,
      },
      next: { revalidate: 3600 }, // Cache for 1 hour
    }
  );
  return res.json();
}
 
export default async function TestimonialsPage() {
  const { data: testimonials } = await getTestimonials();
 
  return (
    <section>
      <h2>What our customers say</h2>
      <div className="grid grid-cols-3 gap-4">
        {testimonials.map((t) => (
          <div key={t.id} className="p-4 border rounded-lg">
            <p>{t.content}</p>
            <footer>
              — {t.author.name}
              {t.author.role && `, ${t.author.role}`}
            </footer>
          </div>
        ))}
      </div>
    </section>
  );
}

{
  "media_type": "video",
  "media_url": "https://...",
  "video": {
    "playback_id": "abc123",
    "thumbnail_url": "https://image.mux.com/abc123/thumbnail.jpg",
    "duration": 45.2,
    "width": 1920,
    "height": 1080
  }
}