Backend Docs

This guide will walk you through the process of configuring your backend to work seamlessly with your Limeblock widget. Proper backend integration enables your widget to access data, perform actions, and provide a more personalized experience to your users.

Backend URL Configuration

The first step in backend integration is to specify your API's base URL:

Navigate to the Backend tab in your Limeblock dashboard
Enter your API's base URL in the "Edit URL" section (e.g., https://api.yourapp.com)
Save the configuration

API Endpoint Configuration

Your Limeblock widget can interact with your backend through defined API endpoints. Follow these guidelines to configure them effectively:

Organize with Folders: Group related endpoints in logical folders (e.g., "User Management", "Content", "Transactions")
Define Clear Paths: Use RESTful paths that clearly indicate the endpoint's purpose
Provide Detailed Descriptions: Write comprehensive descriptions that help the AI understand when and how to use each endpoint

Example API Endpoint Structure

json

{
  "folders": [
    {
      "name": "User Management",
      "endpoints": [
        {
          "path": "/api/users/profile",
          "method": "GET",
          "description": "Retrieves the current user's profile information including name, email, preferences, and account status. Returns a 404 if the user is not found or a 401 if unauthorized.",
          "schema": {
            "user_id": "{user_id}"
          }
        },
        {
          "path": "/api/users/update",
          "method": "PUT",
          "description": "Updates the user's profile information. Can modify name, email, and preferences. Returns the updated user object or errors for invalid inputs.",
          "schema": {
            "user_id": "{user_id}",
            "name": "string",
            "email": "string",
            "preferences": {
              "notifications": "boolean",
              "theme": "string"
            }
          }
        }
      ]
    },
    {
      "name": "Products",
      "endpoints": [
        {
          "path": "/api/products/list",
          "method": "GET",
          "description": "Retrieves a paginated list of products with optional filtering by category, price range, and availability. Returns product information including ID, name, price, and description.",
          "schema": {
            "category": "string",
            "min_price": "number",
            "max_price": "number",
            "in_stock": "boolean",
            "page": "number",
            "limit": "number"
          }
        },
        {
          "path": "/api/products/{product_id}",
          "method": "GET",
          "description": "Retrieves detailed information about a specific product including features, specifications, pricing, and availability. Returns a 404 if the product is not found.",
          "schema": {
            "product_id": "{product_id}"
          }
        }
      ]
    }
  ]
}

Best Practices for Endpoint Descriptions

Write detailed descriptions that include:

What the endpoint does
What parameters it accepts
What response it returns
Potential error cases
Use cases for when this endpoint should be called

Example of a Good Description:

text

Creates a new order in the system with the provided items and shipping information. Validates inventory availability and calculates final price including taxes and shipping. Returns the created order ID and confirmation details, or specific error messages if validation fails (e.g., insufficient inventory, invalid shipping address).

Context Parameters

Context parameters allow your widget to dynamically pass information to API calls, making interactions more relevant and personalized.

How Context Parameters Work

Define parameters in your endpoint schemas using curly braces: {parameter_name}
When implementing the widget, pass these values dynamically
The AI will automatically substitute these placeholders with actual values during interactions

Common Context Parameters

Parameter	Description	Usage Example
`{user_id}`	Current authenticated user's ID	Personalizing responses, fetching user-specific data
`{session_id}`	Current session identifier	Tracking conversation context across interactions
`{product_id}`	Product being discussed	Fetching specific product details during a conversation
`{order_id}`	Order being discussed	Retrieving or updating order information

Example Schema with Context Parameters

json

{
  "path": "/api/dashboard/stats",
  "method": "GET",
  "description": "Retrieves personalized dashboard statistics for the specified user, including recent activity, pending tasks, and performance metrics for the given time period.",
  "schema": {
    "user_id": "{user_id}",
    "time_period": "string",
    "include_archived": "boolean"
  }
}

Consistent Naming Conventions

To avoid potential AI errors and ensure smooth operation, maintain consistent naming throughout your API configuration:

Use snake_case for all parameter names
Keep endpoint paths consistent (e.g., all plural nouns for collections)
Use the same parameter names across different endpoints when they represent the same data
Prefix IDs with their entity type (e.g., user_id, product_id)

Examples of Consistent Naming

✅ Good:

text

user_id, product_id, order_items, created_at

❌ Avoid Inconsistency:

text

userId, ProductId, orderItems, created-at

Configuring Backend Access

For your Limeblock widget to communicate with your backend, you need to set up proper access controls:

CORS Configuration

Configure your server to accept requests from Limeblock's domains by adding appropriate CORS (Cross-Origin Resource Sharing) headers.

Django Example

python

# settings.py

INSTALLED_APPS = [
    # ... other apps
    'corsheaders',
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    # ... other middleware
]

# Allow requests from Limeblock domains
CORS_ALLOWED_ORIGINS = [
    "https://limeblock.io",
    "https://limeblockbackend.onrender.com",
]

# If you need to allow credentials (cookies, authorization headers)
CORS_ALLOW_CREDENTIALS = True

# Optional: Specify which HTTP methods are allowed
CORS_ALLOW_METHODS = [
    "GET",
    "POST",
    "PUT",
    "PATCH",
    "DELETE",
    "OPTIONS"
]

Express.js Example

javascript

const express = require('express');
const cors = require('cors');
const app = express();

// Configure CORS
app.use(cors({
  origin: [
    "https://limeblock.io",
    "https://limeblockbackend.onrender.com",
  ],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

// Your routes and other middleware

Authentication

To secure your API endpoints, consider implementing one of these authentication methods:

API Key Authentication: Include your Limeblock API key in requests
OAuth 2.0: For more advanced security needs
JWT Tokens: For stateless authentication

Testing Your Backend Integration

Before deploying to production:

Use the "Test Endpoint" feature in the Limeblock dashboard to verify connectivity
Test with various inputs to ensure robust error handling
Verify context parameter substitution works correctly
Check that the AI can properly interpret the responses

Troubleshooting

Issue	Potential Solution
403 Forbidden errors	Check CORS configuration and authentication
Endpoint not being called	Verify URL path and description accuracy
Context parameters not being substituted	Ensure parameter names match in schema and implementation
AI misinterpreting responses	Improve endpoint descriptions and provide example responses

Getting Help

If you need assistance with your Limeblock implementation:

Contact our founder directly at byjuaditya@gmail.com for personalized support
Check our comprehensive documentation