# API Guide

## Famewall API v1 — Quickstart (2 minutes)

Use the Famewall API to add and manage testimonials programmatically from your tools.

### 1) Get your API Key

1. Open the Famewall app
2. Go to **API** in the sidebar
3. Click **Generate API Key**
4. Copy the key (shown once)

Keep this key secret.

### 2) Base URL

Your API base URL:

```
https://api.famewall.io/v1
```

All requests require the header:

```
Authorization: Bearer <YOUR_API_KEY>
```

### 3) List your walls

**Request**

```
GET /walls
```

**Example (curl)**

```bash
curl -X GET "https://api.famewall.io/v1/walls" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

**Response**

```json
{
  "items": [
    {
      "wallId": "...",
      "wallUrl": "my-wall",
      "wallName": "Customer Love",
      "description": "...",
      "updatedOn": "2026-02-24T11:35:48.493Z"
    }
  ],
  "next_cursor": null
}
```

### 4) Fetch testimonials from a wall

**Request**

```
GET /walls/{wall_url}/testimonials
```

**Example (curl)**

```bash
curl -X GET "https://api.famewall.io/v1/walls/my-wall/testimonials" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

**Response (example)**

```json
{
  "items": [
    {
      "testimonialId": "...",
      "testimonialType": "TEXT",
      "authorName": "Jane Doe",
      "testimonialContent": "Great product!",
      "testimonialTime": "2026-02-24T11:35:43.320Z",
      "workTitle": "Founder",
      "createdAt": "2026-02-24T11:35:48.493Z",
      "videoPlaybackId": "...",
      "videoUrl": "https://stream.mux.com/<playback_id>/medium.mp4",
      "audioAssetKey": "...",
      "audioUrl": "https://..."
    }
  ],
  "next_cursor": null
}
```

### 5) Add a testimonial to a wall (text only)

**Request**

```
POST /walls/{wall_url}/testimonials
```

**Body**

```json
{
  "author_name": "Jane Doe",
  "message_content": "Loved the product!",
  "work_title": "Founder",
  "star_rating": 5,
  "author_image": "https://...",
  "author_link": "https://...",
  "author_username": "jane",
  "message_link": "https://...",
  "insert_position": "top"
}
```

**Example (curl)**

```bash
curl -X POST "https://api.famewall.io/v1/walls/my-wall/testimonials" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"author_name":"Jane Doe","message_content":"Loved the product!","insert_position":"top"}'
```

**Response**

```json
{
  "testimonialId": "...",
  "status": "added",
  "insertPosition": "top"
}
```

### 6) Get collected testimonials

**Request**

```
GET /walls/{wall_url}/collected-testimonials
```

**Example (curl)**

```bash
curl -X GET "https://api.famewall.io/v1/walls/my-wall/collected-testimonials" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

**Response (example)**

```json
{
  "items": [
    {
      "testimonialId": "...",
      "testimonialType": "TEXT",
      "authorName": "Jane Doe",
      "testimonialContent": "Great!",
      "email": "jane@example.com",
      "customFieldValues": {"company":"Acme"},
      "createdAt": "2026-02-24T11:35:48.493Z"
    }
  ],
  "next_cursor": null
}
```

### Pagination

All list endpoints support:

* `limit` (default `20`, max `50`)
* `cursor` (use `next_cursor` from the previous response)

**Example**

```
GET /walls?limit=20&cursor=abc123
```

### Troubleshooting

* **401 Unauthorized**: Invalid API key or not on Standard plan.
* **400 Invalid request**: Missing or invalid parameters.
* **429**: Rate limit exceeded (retry after a minute).

If you’re blocked, regenerate your API key in the Famewall app and try again.