Quickstart

Make your first API calls to Vivreal using plain HTTP requests — just cURL or your favorite HTTP client.

Prerequisites

• A Vivreal account with at least one group
• An API key (find it in the portal under Group Settings)
• At least one collection with published objects

Step 1: Fetch Your Site Data

Test that your API key works by fetching your site configuration:

curl "https://client.vivreal.io/tenant/siteDetails?siteId=YOUR_SITE_ID" \
  -H "Authorization: YOUR_API_KEY"

You should see your site's theme, logo, and business info in the response. If you get a 401, double-check your API key.

Step 2: Fetch Collection Objects

Now fetch the published objects from a collection:

curl "https://client.vivreal.io/tenant/collectionObjects?collectionId=YOUR_COLLECTION_ID&limit=5&sort=publishDate:desc" \
  -H "Authorization: YOUR_API_KEY"

Each object has an objectValue field containing the fields you defined in your collection schema.

Step 3: Display Images

Objects with images have a mediaFields map. The API resolves media to signed CDN URLs automatically:

// Get the signed image URL from a collection object
const imageUrl = item.objectValue.image?.currentFile?.source || "";

Error Handling

Always check the response status before parsing the body:

async function vivrealFetch(path) {
  const res = await fetch(`https://client.vivreal.io${path}`, {
    headers: { Authorization: API_KEY },
  });

  if (!res.ok) {
    const error = await res.json().catch(() => ({}));
    throw new Error(
      `Vivreal API error ${res.status}: ${error.error || res.statusText}`
    );
  }

  return res.json();
}

// Usage
try {
  const { data } = await vivrealFetch(
    `/tenant/collectionObjects?collectionId=${COLLECTION_ID}`
  );
  console.log(`Fetched ${data.totalCount} objects`);
} catch (err) {
  console.error(err.message);
}

Common errors you may encounter:

See the full error codes reference for details.

Next Steps

• Endpoints — Full reference for every endpoint
• Authentication — API key details and best practices