Remote API Endpoints

This guide provides comprehensive documentation for BILDIT's Remote API endpoints. These endpoints serve various types of content and configuration data for scheduled content, components, and Visual Experience Engine functionality.

Overview

The Remote API provides several endpoints for retrieving content, configuration, and component data. Each endpoint serves a specific purpose in the BILDIT ecosystem and supports various query parameters for filtering and customization.

Base URLs

Every endpoint uses a Base URL that specifies the environment. Append the action name to the Base URL for each request. Use your own app key for the key parameter.

Environment	Base URL
Production	https://admin.bildit.co/
Stage	https://us-central1-compilepoc-2d379.cloudfunctions.net/
Local	http://localhost:5001/compilepoc-2d379/us-central1/

1. remote-webbanners_v1_1

Purpose: Serves scheduled content with filtering and scheduling capabilities.

Query Parameters

Parameter	Type	Description
key	string	API key associated with the instance of the app in the Visual Experience Engine
mode	string	Render mode: csr (client-side render) or ssr (server-side render). Code delivery (v1_1): compiled or transpiled — controls how banner code is returned. Use csr/ssr for where to render; use compiled/transpiled when requesting raw code format.
tomorrow	boolean	Include tomorrow's results for 12:00PM cutover
location	string	First URL where the content is deployed
category	string	Category where the content is deployed
customerGroup	string	Associated customer group to show content to
date	string	Date to get content for from schedules

Response Fields

• codelib: Transpiled base code wrapper for the entire scheduled content component
• lastUpdate: Latest create/update timestamp
• data: Array of scheduled content objects

Scheduled Content Object Structure

{
  "id": "string",
  "alternateText": "string",
  "bannerSortOrder": "array",
  "location": "string",
  "locations": "array",
  "schedules": "array",
  "screenTypes": "object",
  "variants": "array",
  "webSlots": "array",
  "url": "string"
}

Screen Types (Device Targeting)

{
  "desktop": true,
  "tablet": true,
  "phone": true
}

Note: Defaults to all true if not specified.

Banner Variant Object

Each variant can target different audiences, categories, or locations:

{
  "categories": ["array"],
  "customerGroups": ["array"],
  "locations": ["array"],
  "code": {
    "compiled": "string",
    "html": "string",
    "props": "object"
  },
  "codeType": "string",
  "image": "string",
  "url": "string",
  "adobeAnalytics": "string",
  "siteSpectVariationId": "string",
  "dynamicYieldVariationId": "string",
  "preview": {
    "h": "number",
    "w": "number",
    "uuid": "string"
  },
  "addBottomMargin": "boolean",
  "metadata": ["array"]
}

2. remote-content

Purpose: Serves HTML content without scheduling.

Query Parameters

Parameter	Type	Description
key	string	API key for authentication
cid	string	Random content ID for the database
slug	string	Path parameter to define content (usually location or description)
location	string	URL location where content will be displayed
category	string	Category where content will be displayed
device	string	Device types the content is made for

Response Fields

• id: Content identifier
• name: Content name
• slug: Content slug
• location: Display location
• category: Content category
• devices: Target devices
• status: Content status
• code: HTML content
• url: Content URL
• createdAt: Creation timestamp
• updatedAt: Last update timestamp

3. remote-config

Purpose: Serves app configuration data.

Query Parameters

Parameter	Type	Description
key	string	API key for authentication

Response

Returns an object with any properties (string, number, boolean, object, array).

4. remote-components

Purpose: Serves component code by path and version for static React components.

Query Parameters

Parameter	Type	Description
key	string	API key for authentication
path	string	Component path
version	string	Component version
platform	string	Target platform

Response Fields

• id: Component identifier
• path: Component path
• version: Component version
• code: Component code

5. remote-categories

Purpose: Serves categories from the Visual Experience Engine that have been overridden over platform categories.

Query Parameters

Parameter	Type	Description
key	string	API key for authentication

Response

Returns an object keyed by category ID with id and category properties.

6. remote-screens

Purpose: Serves screen configuration by name and version (JSON configuration for specific components or paths).

Query Parameters

Parameter	Type	Description
key	string	API key for authentication
name	string	Screen name
version	string	Screen version
platform	string	Target platform

Response Fields

• name: Screen name
• version: Screen version
• config: Screen configuration JSON

7. remote-codeLib (baseCodelib)

Purpose: Serves base code library template which wraps all scheduled content components.

Query Parameters

Parameter	Type	Description
key	string	API key for authentication

Response

Returns transpiled base code as a string to be rendered.

Detailed Field Explanations

Scheduled Content Object Fields

Core Scheduled Content Properties

• id (string): Unique scheduled content identifier for tracking, analytics, and management
• alternateText (string, optional): Alt text for accessibility and screen readers
• bannerSortOrder (array, optional): Array of objects with key and order properties for display order within web slots
• location (string): Primary URL pattern for scheduled content display
• locations (array): Array of URL patterns where the scheduled content can appear

Scheduling Properties

• schedules (array): Array of schedule objects with:
  • startDate (number): Unix timestamp when display begins
  • endDate (number): Unix timestamp when display ends
  • slot (number): Slot number for mobile apps (scheduled content display order)

Targeting Properties

• screenTypes (object, optional): Device targeting (desktop, tablet, phone)
• webSlots (array): Array of web slot identifiers for placement control
• url (string, optional): Click-through URL for image-only scheduled content

Scheduled Content Variant Object Fields

Targeting Properties

• categories (array): Category identifiers for targeting where a variant should appear
• customerGroups (array): Customer group identifiers for targeting specific customer types
• locations (array): URL patterns specific to this variant

Content Properties

• code (object): Scheduled content code with compiled, html, and props properties
• codeType (string): Type of code (jsx, html, javascript, etc.)
• image (string, optional): Image URL for the scheduled content
• url (string, optional): Click-through URL for this variant

Analytics & Tracking Properties

• adobeAnalytics (string, optional): Adobe Analytics tracking code
• siteSpectVariationId (string, optional): SiteSpect A/B testing variation identifier
• dynamicYieldVariationId (string, optional): Dynamic Yield personalization variation identifier

Display Properties

• preview (object, optional): Preview metadata (height, width, UUID)
• addBottomMargin (boolean, optional): Whether to add bottom margin to the scheduled content

Metadata Properties

• metadata (array, optional): Array of metadata objects for dynamic content with:
  • name (string): Metadata field name
  • type (string): Data type
  • value (string|number|boolean): Current value
  • defaultValue (string|number): Default value
  • dropdownOptions (array): Options for dropdown fields
  • bannerOptions (array): Options for banner-specific fields

Usage Examples

Basic Scheduled Content Request

// Request scheduled content for desktop with specific location
const response = await fetch('/api/remote-webbanners_v1_1?key=your-api-key&mode=csr&location=/homepage&screenTypes={"desktop":true}');
const data = await response.json();

Content Request

// Request specific content by slug
const response = await fetch('/api/remote-content?key=your-api-key&slug=hero-banner&location=/homepage');
const content = await response.json();

Component Request

// Request component code
const response = await fetch('/api/remote-components?key=your-api-key&path=/components/hero&version=1.0&platform=web');
const component = await response.json();

Best Practices

API Key Management

• Store API keys securely
• Use environment variables for different environments
• Rotate keys regularly for security

Error Handling

• Implement proper error handling for all API calls
• Check response status codes
• Handle network failures gracefully

Caching

• Implement appropriate caching strategies
• Use cache headers when available
• Consider content freshness requirements

Performance

• Use appropriate query parameters to limit data
• Implement pagination for large datasets
• Monitor API response times

Troubleshooting

Common Issues

1. Authentication Errors: Verify API key is correct and has proper permissions
2. Missing Content: Check query parameters and ensure content exists
3. Scheduling Issues: Verify date parameters and schedule configurations
4. Device Targeting: Ensure screenTypes parameters are properly formatted

Debug Tips

• Use browser developer tools to inspect API responses
• Check network tab for request/response details
• Verify query parameters are properly encoded
• Test with different mode parameters (csr/ssr for render; compiled/transpiled for code delivery)

Related Documentation

• Template Guide - Learn about creating templates
• Scheduled Content Management - Managing scheduled content in the Visual Experience Engine
• Configuration - Visual Experience Engine configuration settings

Getting Help

If you need assistance with the Remote API:

• Check the Troubleshooting Guide for common issues
• Verify your API key permissions
• Review query parameter documentation
• Test endpoints with different parameters

For additional support, refer to the Best Practices guide for optimization tips.