API Reference

Base URL

All API requests should be made to:

https://api.tablrr.app/v1

Authentication

Most API endpoints require authentication using an API token. Include your token in the Authorization header:

http

Authorization: Bearer {your-token-here}

Getting an API Token

If you want to access the API directly from your own applications or scripts, you need to follow these steps:

Go to Settings > Sites & API Tokens in your tablrr account
Click "Add Site"
Enter you domain name
Verify your site and the token will be shown to you
Copy the token immediately - it won't be shown again

Requirements:

Growth plan or higher subscription

Premium Template Access

If your listing uses a premium template, you need:

Hobby plan or higher to use premium templates
Free plan users can only use free templates

If you try to access a premium template listing without the required plan, you'll receive a 403 Forbidden error.

Rate Limiting

To prevent abuse, API endpoints have rate limits:

Listing endpoints: 60 requests per minute
Site verification endpoint: 10 requests per minute

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait a minute before trying again.

Error Responses

All API errors follow a consistent format:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

Code	HTTP Status	Description
`RESOURCE_NOT_FOUND`	404	The requested listing or resource was not found
`VALIDATION_FAILED`	422	Request data is invalid or missing
`FORBIDDEN`	403	Access denied (plan restriction or unauthorized)
`INTERNAL_ERROR`	500	An internal server error occurred

Endpoints

Health Check

Check if the API is available and responding.

Endpoint: GET /api/v1/health

Authentication: Not required

Response:

json

{
  "status": "ok"
}

Example:

bash

curl https://api.tablrr.app/v1/health

Get Listing Embed Data

Get everything you need to embed a listing: HTML, CSS, JavaScript, and direct URLs to each asset.

Endpoint: GET /api/v1/listings/{publicId}/embed

Authentication: Required

Parameters:

publicId (path, required): The public ID of your listing (found in the listing URL or settings)

Response:

json

{
  "html": "<div>...</div>",
  "css": "/* CSS styles */",
  "js": "/* JavaScript code */",
  "structured_data": "/* JSON data */",
  "html_url": "https://api.tablrr.app/v1/listings/{publicId}/html",
  "css_url": "https://api.tablrr.app/v1/listings/{publicId}/css",
  "js_url": "https://api.tablrr.app/v1/listings/{publicId}/js",
  "structured_data_url": "https://api.tablrr.app/v1/listings/{publicId}/structured_data",
  "updated_at": "2025-01-10T10:00:00Z"
}

Caching:

Responses include cache headers to help reduce bandwidth:

Cache-Control: public, max-age=3600 (1 hour)
ETag header for conditional requests

Example:

bash

curl -H "Authorization: Bearer {token}" \
  https://api.tablrr.app/v1/listings/abc123/embed

Get Listing HTML

Get just the HTML content for a listing. Useful when you only need the markup.

Endpoint: GET /api/v1/listings/{publicId}/html

Authentication: Required

Parameters:

publicId (path, required): The public ID of your listing

Response:

Returns HTML content with Content-Type: text/html; charset=UTF-8

Caching:

Cache-Control: public, max-age=3600 (1 hour)
ETag header for conditional requests

Example:

bash

curl -H "Authorization: Bearer {token}" \
  https://api.tablrr.app/v1/listings/abc123/html

Get Listing CSS

Get just the CSS styles for a listing. Useful for loading styles separately or customizing them.

Endpoint: GET /api/v1/listings/{publicId}/css

Authentication: Required

Parameters:

publicId (path, required): The public ID of your listing

Response:

Returns CSS content with Content-Type: text/css; charset=UTF-8

Caching:

Cache-Control: public, max-age=3600 (1 hour)
ETag header for conditional requests

Example:

bash

curl -H "Authorization: Bearer {token}" \
  https://api.tablrr.app/v1/listings/abc123/css

Get Listing JavaScript

Get just the JavaScript code for a listing.

Endpoint: GET /api/v1/listings/{publicId}/js

Authentication: Required

Parameters:

publicId (path, required): The public ID of your listing

Response:

Returns JavaScript content with Content-Type: application/javascript; charset=UTF-8

Caching:

Cache-Control: public, max-age=3600 (1 hour)
ETag header for conditional requests

Example:

bash

curl -H "Authorization: Bearer {token}" \
  https://api.tablrr.app/v1/listings/abc123/js

Get Listing Structured Data

Get just the Schema.org ItemList JSON-LD structured data for a listing. Useful for injecting into the <head> section of your page for SEO.

Endpoint: GET /api/v1/listings/{publicId}/structured_data

Authentication: Required

Parameters:

publicId (path, required): The public ID of your listing

Response:

Returns JSON-LD structured data with Content-Type: application/json; charset=UTF-8

Caching:

Cache-Control: public, max-age=3600 (1 hour)
ETag header for conditional requests

Example:

bash

curl -H "Authorization: Bearer {token}" \
  https://api.tablrr.app/v1/listings/abc123/structured_data

Usage Examples

Embed a Listing in Your Website

Option 1: Load Everything at Once

javascript

const response = await fetch(
  "https://api.tablrr.app/v1/listings/abc123/embed",
  {
    headers: {
      Authorization: "Bearer your-token-here",
    },
  }
);

const data = await response.json();

// Inject HTML, CSS, and JS into your page
document.getElementById("listing-container").innerHTML = data.html;

const style = document.createElement("style");
style.textContent = data.css;
document.head.appendChild(style);

const script = document.createElement("script");
script.textContent = data.js;
document.body.appendChild(script);

// Inject structured data into <head> for SEO
const structuredDataScript = document.createElement("script");
structuredDataScript.type = "application/ld+json";
structuredDataScript.textContent = JSON.stringify(data.structured_data);
document.head.appendChild(structuredDataScript);

Option 2: Load Assets Separately

html

<!-- In your HTML -->
<div id="listing-container"></div>
<link rel="stylesheet" href="https://api.tablrr.app/v1/listings/abc123/css" />
<script src="https://api.tablrr.app/v1/listings/abc123/js"></script>

<script>
  fetch("https://api.tablrr.app/v1/listings/abc123/html", {
    headers: {
      Authorization: "Bearer your-token-here",
    },
  })
    .then((response) => response.text())
    .then((html) => {
      document.getElementById("listing-container").innerHTML = html;
    });
</script>

Handle Errors

javascript

try {
  const response = await fetch(
    "https://api.tablrr.app/v1/listings/abc123/embed",
    {
      headers: {
        Authorization: "Bearer your-token-here",
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();

    switch (error.error.code) {
      case "RESOURCE_NOT_FOUND":
        console.error("Listing not found. Check the public ID.");
        break;
      case "FORBIDDEN":
        if (error.error.message.includes("premium template")) {
          console.error(
            "This listing uses a premium template. Upgrade to Hobby plan or higher."
          );
        } else {
          console.error(
            "Access denied. Upgrade to Growth plan or higher for direct API access."
          );
        }
        break;
      case "VALIDATION_FAILED":
        console.error("Invalid request:", error.error.details);
        break;
      default:
        console.error("An error occurred:", error.error.message);
    }
    return;
  }

  const data = await response.json();
  // Use the listing data
} catch (error) {
  console.error("Network error:", error);
}

Best Practices

Store tokens securely: Never commit API tokens to version control or expose them in client-side code that's publicly accessible
Handle errors gracefully: Always check response status codes and provide helpful error messages to users
Respect rate limits: Implement retry logic with exponential backoff if you hit rate limits
Cache responses: Use the ETag header for conditional requests to reduce bandwidth and improve performance
Verify domains: Ensure your domain is verified in Settings > Sites before making browser-based requests
Check plan requirements: Make sure your account has the required plan before attempting to use premium features or direct API access

Support

For API support, please contact support@tablrr.app.

API Reference ​

Base URL ​

Authentication ​

Getting an API Token ​

Premium Template Access ​

Rate Limiting ​

Error Responses ​

Common Error Codes ​

Endpoints ​

Health Check ​

Get Listing Embed Data ​

Get Listing HTML ​

Get Listing CSS ​

Get Listing JavaScript ​

Get Listing Structured Data ​

Usage Examples ​

Embed a Listing in Your Website ​

Option 1: Load Everything at Once ​

Option 2: Load Assets Separately ​

Handle Errors ​

Best Practices ​

Support ​

API Reference

Base URL

Authentication

Getting an API Token

Premium Template Access

Rate Limiting

Error Responses

Common Error Codes

Endpoints

Health Check

Get Listing Embed Data

Get Listing HTML

Get Listing CSS

Get Listing JavaScript

Get Listing Structured Data

Usage Examples

Embed a Listing in Your Website

Option 1: Load Everything at Once

Option 2: Load Assets Separately

Handle Errors

Best Practices

Support