Overview

Every endpoint is relative to this base URL. Requests and responses are JSON.

https://app.videotestimonials.video/api/v1

The same reference is available as an OpenAPI 3.1 document, as markdown, and through the API catalog (RFC 9727). Call it from a server: a key can read and change your account's data.

Authentication

Create a key in the dashboard under Settings → API Keys. The full key is shown once, when you create it; we store only a hash. Send it as a bearer token on every request:

Authorization: Bearer sk_live_…

A key acts for the account that created it and sees every space and testimonial that account owns. Each key has one or more scopes, and each endpoint needs one of them:

read — every GET
write — creating and updating, including batch status updates
delete — deleting, including batch deletes

A key can be switched off or given an expiry date in the dashboard; requests with it then fail with 403.

Rate limits

Each account can make 1,000 requests per hour, shared by all of its keys. The hour starts with the first request and resets an hour later. Successful responses carry:

X-RateLimit-Limit
Requests allowed per hour for this account.
X-RateLimit-Remaining
Requests left in the current window.
X-RateLimit-Reset
When the current window ends, as a Unix timestamp in milliseconds.

Past the limit, requests return 429 with RATE_LIMIT_EXCEEDED and the reset time in error.details.reset. The count is kept per server instance, so treat the limit as a ceiling to stay under rather than an exact budget.

Errors

Every error has the same shape:

{
  "error": {
    "code": "TESTIMONIAL_NOT_FOUND",
    "message": "Testimonial not found or you do not have access to it"
  }
}

UNAUTHORIZED
No Authorization header was sent (401).
INVALID_API_KEY
The key is not sk_live_…/sk_test_… shaped, or no key with that value exists (401).
API_KEY_DISABLED
The key was switched off in the dashboard (403).
API_KEY_EXPIRED
The key is past its expiry date (403).
INSUFFICIENT_SCOPE
The key lacks the scope this operation needs: read, write or delete (403).
RATE_LIMIT_EXCEEDED
More than 1,000 requests in the current hour (429).
VALIDATION_ERROR
A query parameter or body field failed validation (400).
TESTIMONIAL_NOT_FOUND
No testimonial with that id belongs to this account (404).
SPACE_NOT_FOUND
No space with that id belongs to this account (404).
INVALID_ENDPOINT
The batch operation is neither update nor delete (404).
INTERNAL_ERROR
Anything else, including a request body that is not valid JSON (500).

VALIDATION_ERROR does not say which field failed; check the field rules under each endpoint below.

Pagination

List endpoints take limit (1–100, default 50) and offset (default 0), and return a pagination object next to data:

{
  "data": [
    "…"
  ],
  "pagination": {
    "total": 120,
    "limit": 50,
    "offset": 50,
    "has_more": true
  }
}

Browser access (CORS)

/testimonials, /testimonials/{id} and /spaces answer browser preflight requests and send Access-Control-Allow-Origin: *. /spaces/{id} and the batch endpoints do not, so call those from a server. Either way, never put a key in front-end code — anyone who can load the page can read it. To show testimonials on a website, use the embed widget instead.

Webhooks

Writes through the API fire the same webhooks as the dashboard: testimonial.created on create, testimonial.approved and testimonial.rejected when a status changes to one of those, and testimonial.deleted on delete. Set up endpoints in the dashboard — see Webhooks & automations.

Testimonials

Read, create, moderate and delete testimonials.

List testimonials

GET/testimonialsscope: read

Testimonials across every space the account owns, newest first unless sort_by/sort_order say otherwise.

Query parameters

space_idstring (uuid)
Only testimonials in this space.
statusstring
Only testimonials with this moderation status.
One of: pending, approved, rejected
typestring
Only text or only video testimonials.
One of: text, video
ratinginteger
Only testimonials with exactly this star rating.
1–5
searchstring
Case-insensitive substring match on text_content.
date_fromstring (date-time)
Only testimonials created at or after this time. ISO 8601 in UTC with a Z suffix, e.g. 2026-01-01T00:00:00Z.
date_tostring (date-time)
Only testimonials created at or before this time. ISO 8601 in UTC with a Z suffix.
limitinteger
Number of items to return.
1–100 · Default 50
offsetinteger
Number of items to skip, for paging.
Min 0 · Default 0
sort_bystring
Column to sort by. Defaults to created_at.
One of: created_at, updated_at, rating, shares
sort_orderstring
Sort direction.
One of: asc, desc · Default desc

Responses

200A page of testimonials.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl "https://app.videotestimonials.video/api/v1/testimonials?status=approved&limit=10" \
  -H "Authorization: Bearer $VT_API_KEY"

Example response

{
  "data": [
    {
      "id": "c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
      "space_id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
      "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "type": "text",
      "status": "approved",
      "submitter_name": "Jane Doe",
      "submitter_email": "jane@example.com",
      "submitter_company": "Example Co",
      "submitter_role": "Head of Marketing",
      "submitter_avatar_url": null,
      "text_content": "We collected twelve video testimonials in our first week.",
      "video_url": null,
      "video_thumbnail_url": null,
      "rating": 5,
      "created_at": "2026-10-01T09:30:00.123456+00:00"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create a testimonial

POST/testimonialsscope: write

Adds a testimonial to one of the account's spaces and fires the testimonial.created webhook. For a video testimonial with a video_url, the request also transcribes the video before it responds; on success the transcript is saved to ai_transcript and text_content. The response is the row as inserted, before transcription.

Request body (JSON)

space_idstring (uuid)required
Space to add the testimonial to. Must belong to the account that owns the API key.
typestringrequired
text or video.
One of: text, video
submitter_namestringrequired
Name of the person giving the testimonial.
1–100 characters
submitter_emailstring (email)required
Email of the person giving the testimonial.
submitter_companystring
Their company.
Max 100 characters
submitter_rolestring
Their job title or role.
Max 100 characters
submitter_avatar_urlstring (uri)
URL of their photo.
text_contentstring
The testimonial text. For a video testimonial this is replaced by the transcript once transcription succeeds.
video_urlstring (uri)
Publicly reachable URL of the video file. When type is video, the API downloads it and transcribes it before responding.
video_thumbnail_urlstring (uri)
URL of a thumbnail image for the video.
ratinginteger
Star rating.
1–5
statusstring
Moderation status. Embed widgets only show approved testimonials.
One of: pending, approved, rejected · Default pending

Responses

201The created testimonial.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404space_id is not a space this account owns. Codes: SPACE_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X POST "https://app.videotestimonials.video/api/v1/testimonials" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"space_id":"8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b","type":"text","submitter_name":"Jane Doe","submitter_email":"jane@example.com","submitter_company":"Example Co","text_content":"We collected twelve video testimonials in our first week.","rating":5,"status":"approved"}'

Example response

{
  "data": {
    "id": "c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    "space_id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "type": "text",
    "status": "approved",
    "submitter_name": "Jane Doe",
    "submitter_email": "jane@example.com",
    "submitter_company": "Example Co",
    "submitter_role": "Head of Marketing",
    "submitter_avatar_url": null,
    "text_content": "We collected twelve video testimonials in our first week.",
    "video_url": null,
    "video_thumbnail_url": null,
    "rating": 5,
    "created_at": "2026-10-01T09:30:00.123456+00:00"
  }
}

Get a testimonial

GET/testimonials/{id}scope: read

Path parameters

idstring (uuid)required
Resource id (UUID).

Responses

200The testimonial.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404No testimonial with that id belongs to this account. Codes: TESTIMONIAL_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl "https://app.videotestimonials.video/api/v1/testimonials/c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer $VT_API_KEY"

Example response

{
  "data": {
    "id": "c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    "space_id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "type": "text",
    "status": "approved",
    "submitter_name": "Jane Doe",
    "submitter_email": "jane@example.com",
    "submitter_company": "Example Co",
    "submitter_role": "Head of Marketing",
    "submitter_avatar_url": null,
    "text_content": "We collected twelve video testimonials in our first week.",
    "video_url": null,
    "video_thumbnail_url": null,
    "rating": 5,
    "created_at": "2026-10-01T09:30:00.123456+00:00"
  }
}

Update a testimonial

PATCH/testimonials/{id}scope: write

Changes status, text, rating, company or role. A status change to approved or rejected fires testimonial.approved or testimonial.rejected.

Path parameters

idstring (uuid)required
Resource id (UUID).

Request body (JSON)

statusstring
New moderation status. Changing it to approved or rejected fires the matching webhook.
One of: pending, approved, rejected
text_contentstring
Replacement testimonial text.
ratinginteger
Star rating.
1–5
submitter_companystring
Their company.
Max 100 characters
submitter_rolestring
Their job title or role.
Max 100 characters

Send at least one of these fields. Fields not listed are ignored.

Responses

200The updated testimonial.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404No testimonial with that id belongs to this account. Codes: TESTIMONIAL_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X PATCH "https://app.videotestimonials.video/api/v1/testimonials/c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"approved"}'

Example response

{
  "data": {
    "id": "c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    "space_id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "type": "text",
    "status": "approved",
    "submitter_name": "Jane Doe",
    "submitter_email": "jane@example.com",
    "submitter_company": "Example Co",
    "submitter_role": "Head of Marketing",
    "submitter_avatar_url": null,
    "text_content": "We collected twelve video testimonials in our first week.",
    "video_url": null,
    "video_thumbnail_url": null,
    "rating": 5,
    "created_at": "2026-10-01T09:30:00.123456+00:00"
  }
}

Delete a testimonial

DELETE/testimonials/{id}scope: delete

Deletes the testimonial, fires testimonial.deleted, and removes its uploaded avatar, video and thumbnail files from storage.

Path parameters

idstring (uuid)required
Resource id (UUID).

Responses

204Deleted. No body.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404No testimonial with that id belongs to this account. Codes: TESTIMONIAL_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X DELETE "https://app.videotestimonials.video/api/v1/testimonials/c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer $VT_API_KEY"

Batch

Moderate or delete up to 100 testimonials in one request.

Set the status of up to 100 testimonials

POST/testimonials/batch/updatescope: write

Sets one status on every listed testimonial the account owns. Setting approved or rejected fires the matching webhook once per testimonial.

Request body (JSON)

testimonial_idsstring (uuid)[]required
Testimonials to update. Ids that do not exist or belong to another account are skipped.
1–100 items
statusstringrequired
Status to set on every listed testimonial.
One of: pending, approved, rejected

Responses

200The updated testimonials and how many changed.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X POST "https://app.videotestimonials.video/api/v1/testimonials/batch/update" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testimonial_ids":["c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d","d2e3f4a5-6b7c-4d8e-8f9a-0b1c2d3e4f5a"],"status":"approved"}'

Example response

{
  "data": [
    {
      "id": "c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
      "space_id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
      "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "type": "text",
      "status": "approved",
      "submitter_name": "Jane Doe",
      "submitter_email": "jane@example.com",
      "submitter_company": "Example Co",
      "submitter_role": "Head of Marketing",
      "submitter_avatar_url": null,
      "text_content": "We collected twelve video testimonials in our first week.",
      "video_url": null,
      "video_thumbnail_url": null,
      "rating": 5,
      "created_at": "2026-10-01T09:30:00.123456+00:00"
    }
  ],
  "updated": 1
}

Delete up to 100 testimonials

POST/testimonials/batch/deletescope: delete

Deletes every listed testimonial the account owns and fires testimonial.deleted once per testimonial. Unlike the single delete, uploaded files are not removed from storage.

Request body (JSON)

testimonial_idsstring (uuid)[]required
Testimonials to delete. Ids that do not exist or belong to another account are skipped.
1–100 items

Responses

200How many testimonials were deleted.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X POST "https://app.videotestimonials.video/api/v1/testimonials/batch/delete" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testimonial_ids":["c7d1a2b3-5e6f-4a8b-9c0d-1e2f3a4b5c6d","d2e3f4a5-6b7c-4d8e-8f9a-0b1c2d3e4f5a"]}'

Example response

{
  "deleted": 2
}

Spaces

A space groups one brand's collection forms, testimonials and Wall of Love.

List spaces

GET/spacesscope: read

Spaces the account owns, newest first unless sort_by/sort_order say otherwise.

Query parameters

limitinteger
Number of items to return.
1–100 · Default 50
offsetinteger
Number of items to skip, for paging.
Min 0 · Default 0
sort_bystring
Column to sort by. Defaults to created_at.
One of: created_at, updated_at, rating, shares
sort_orderstring
Sort direction.
One of: asc, desc · Default desc

Responses

200A page of spaces.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl "https://app.videotestimonials.video/api/v1/spaces" \
  -H "Authorization: Bearer $VT_API_KEY"

Example response

{
  "data": [
    {
      "id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
      "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "name": "Example Co",
      "slug": "example-co",
      "description": "Tell us how Example Co helped you.",
      "logo_url": null,
      "primary_color": "#7C3AED",
      "custom_questions": [
        "What problem did we solve for you?",
        "What result did you get?"
      ],
      "created_at": "2026-09-15T12:00:00.000000+00:00"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create a space

POST/spacesscope: write

Request body (JSON)

namestringrequired
Space name, shown on its collection page.
1–100 characters
descriptionstring
Short description of the space.
Max 500 characters
logo_urlstring (uri)
URL of the space logo.
primary_colorstring
Brand colour as a 6-digit hex value, e.g. #7C3AED.
Pattern ^#[0-9A-Fa-f]{6}$
custom_questionsstring[]
Question strings stored on the space. Collection forms take their questions from the form builder, not from this field.

Responses

201The created space.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X POST "https://app.videotestimonials.video/api/v1/spaces" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Co","primary_color":"#7C3AED"}'

Example response

{
  "data": {
    "id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "name": "Example Co",
    "slug": "example-co",
    "description": "Tell us how Example Co helped you.",
    "logo_url": null,
    "primary_color": "#7C3AED",
    "custom_questions": [
      "What problem did we solve for you?",
      "What result did you get?"
    ],
    "created_at": "2026-09-15T12:00:00.000000+00:00"
  }
}

Get a space

GET/spaces/{id}scope: read

Path parameters

idstring (uuid)required
Resource id (UUID).

Responses

200The space.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404No space with that id belongs to this account. Codes: SPACE_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl "https://app.videotestimonials.video/api/v1/spaces/8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $VT_API_KEY"

Example response

{
  "data": {
    "id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "name": "Example Co",
    "slug": "example-co",
    "description": "Tell us how Example Co helped you.",
    "logo_url": null,
    "primary_color": "#7C3AED",
    "custom_questions": [
      "What problem did we solve for you?",
      "What result did you get?"
    ],
    "created_at": "2026-09-15T12:00:00.000000+00:00"
  }
}

Update a space

PATCH/spaces/{id}scope: write

Path parameters

idstring (uuid)required
Resource id (UUID).

Request body (JSON)

namestring
Space name, shown on its collection page.
1–100 characters
descriptionstring
Short description of the space.
Max 500 characters
logo_urlstring (uri)
URL of the space logo.
primary_colorstring
Brand colour as a 6-digit hex value, e.g. #7C3AED.
Pattern ^#[0-9A-Fa-f]{6}$
custom_questionsstring[]
Question strings stored on the space. Collection forms take their questions from the form builder, not from this field.

Send at least one of these fields. Fields not listed are ignored.

Responses

200The updated space.
400A query parameter or body field failed validation. Codes: VALIDATION_ERROR.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
404No space with that id belongs to this account. Codes: SPACE_NOT_FOUND.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X PATCH "https://app.videotestimonials.video/api/v1/spaces/8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Co — Customers"}'

Example response

{
  "data": {
    "id": "8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b",
    "user_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "name": "Example Co",
    "slug": "example-co",
    "description": "Tell us how Example Co helped you.",
    "logo_url": null,
    "primary_color": "#7C3AED",
    "custom_questions": [
      "What problem did we solve for you?",
      "What result did you get?"
    ],
    "created_at": "2026-09-15T12:00:00.000000+00:00"
  }
}

Delete a space

DELETE/spaces/{id}scope: delete

Deletes the space if the account owns it. An id that matches no space of this account also returns 204.

Path parameters

idstring (uuid)required
Resource id (UUID).

Responses

204Deleted, or nothing matched. No body.
401Missing, malformed or unknown API key. Codes: UNAUTHORIZED, INVALID_API_KEY.
403The key is disabled, expired, or lacks the scope this operation needs. Codes: INSUFFICIENT_SCOPE, API_KEY_DISABLED, API_KEY_EXPIRED.
429More than 1,000 requests in the current hour. Codes: RATE_LIMIT_EXCEEDED.
500Unexpected failure, or a request body that is not valid JSON. Codes: INTERNAL_ERROR.

Request

curl -X DELETE "https://app.videotestimonials.video/api/v1/spaces/8b3e2f9a-4c1d-4e5f-9a7b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $VT_API_KEY"

Objects

Testimonial

A testimonial as stored. Responses return the whole row, so fields beyond those listed here (for example AI analysis fields) can appear; treat unknown fields as optional.

Fields (required = always present)

idstring (uuid)required
space_idstring (uuid)required
user_idstring (uuid)
Account that owns the testimonial.
typestringrequired
One of: text, video
statusstringrequired
Moderation status. The API filters and writes pending, approved and rejected.
submitter_namestringrequired
submitter_emailstring
submitter_companystring
submitter_rolestring
submitter_avatar_urlstring
text_contentstring
video_urlstring
video_thumbnail_urlstring
ratinginteger
1–5
ai_transcriptstring
Transcript of a video testimonial, once transcribed.
created_atstring (date-time)required

Space

A space groups one brand's collection forms, testimonials and Wall of Love. Responses return the whole row, so fields beyond those listed here (branding, domain and wall settings) can appear.

Fields (required = always present)

idstring (uuid)required
user_idstring (uuid)
Account that owns the space.
namestringrequired
slugstring
Used in the public collection and wall URLs.
descriptionstring
logo_urlstring
primary_colorstring
custom_questionsarray
created_atstring (date-time)required

Pagination

Fields (required = always present)

totalintegerrequired
Items matching the filters, across all pages.
limitintegerrequired
offsetintegerrequired
has_morebooleanrequired
True when offset + limit < total.

Questions about the API, or need an endpoint that is not here? support@videotestimonials.video