Back to home

API Documentation

Complete guide to integrating with StaticBox APIs. Build powerful forms, manage data storage, and create dynamic experiences for your static sites.

Getting StartedAuthenticationForms APIForm ManagementData Store APILocalization APIProject ManagementDomain SecurityExamplesRate Limits

Getting Started

StaticBox provides RESTful APIs to add dynamic functionality to your static websites. No backend required - just make HTTP requests to our endpoints.

Forms API

Collect form submissions, validate data, and manage contact forms without any server setup.

Data Store API

Store and retrieve JSON data with a simple REST API. Perfect for user-generated content.

Localization API

Manage multi-language content with translation management and export capabilities.

Base URL

https://staticbox.io/api

This is your current domain with the API path. All code examples below use your current domain automatically.

Authentication

StaticBox uses API keys for authentication. Include your API key in the request headers.

  1. Sign up for a StaticBox account
  2. Create a new project
  3. Navigate to your project settings
  4. Generate an API key in the "API Keys" section

Security Note

Keep your API keys secure. Never expose them in client-side code for production applications.

Forms API

Handle form submissions without any backend code. Perfect for contact forms, surveys, and user feedback.

🛡️ Built-in Protection

  • Spam Detection: AI-powered content analysis with honeypot protection
  • Rate Limiting: Automatic protection against form spam and abuse
  • Domain Restrictions: CORS protection when domains are configured
  • File Upload Security: Type and size validation for attachments
  • Form Status: Enable/disable forms without code changes
POSThttps://staticbox.io/api/forms/{projectId}/{formSlug}/submit

Request Body

Form Submission
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1-555-0123",
  "message": "Hello, I'm interested in your services!"
}

Response

Success Response (201)
{
  "success": true,
  "message": "Form submitted successfully",
  "id": "submission-uuid"
}

HTML Form Example

Contact Form
<form action="https://staticbox.io/api/forms/PROJECT_ID/contact/submit" method="POST">
  <input type="text" name="name" placeholder="Your Name" required>
  <input type="email" name="email" placeholder="Your Email" required>
  <textarea name="message" placeholder="Your Message" required></textarea>
  
  <!-- Honeypot field for spam protection -->
  <input type="text" name="_honeypot" style="display: none;" tabindex="-1">
  
  <button type="submit">Send Message</button>
</form>

Form Management API

Manage form submissions, configure webhooks, and analyze spam patterns with comprehensive APIs.

GEThttps://staticbox.io/api/projects/{projectId}/forms/{formId}/submissionsAuth Required

Query Parameters

  • limit - Number of submissions to return (default: 100, max: 100)
  • offset - Number of submissions to skip (pagination)
Get Form Submissions
const response = await fetch(
  'https://staticbox.io/api/projects/PROJECT_ID/forms/FORM_ID/submissions?limit=50',
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
);

const { submissions } = await response.json();
console.log('Submissions:', submissions);

Response Format

Submissions Response
{
  "submissions": [
    {
      "id": "submission-uuid",
      "formId": "form-uuid",
      "data": {
        "name": "John Doe",
        "email": "john@example.com",
        "message": "Hello!",
        "attachments": [
          {
            "originalName": "document.pdf",
            "url": "https://blob-url.vercel-storage.com/...",
            "size": 1024000,
            "type": "application/pdf"
          }
        ]
      },
      "metadata": {
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "spamScore": 0.1,
        "confidence": 95
      },
      "isSpam": false,
      "isRead": false,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

Data Store API

Store and retrieve JSON data with a simple REST API. Perfect for user-generated content, comments, reviews, and any structured data.

🔒 Security Features

  • Domain Protection: CORS validation when domain restrictions are enabled
  • Public/Private Entries: Control access at the entry level with isPublic flag
  • API Key Authentication: Required for creating, updating, and accessing private data
  • Collection Status: Active/inactive collections for access control
POSThttps://staticbox.io/api/projects/{projectId}/datastores/{collectionId}/data
Create Blog Post
{
  "key": "my-first-post",
  "data": {
    "title": "Getting Started with StaticBox",
    "content": "StaticBox makes it easy to add dynamic features...",
    "author": "John Doe",
    "publishedAt": "2024-01-15T10:00:00Z",
    "tags": ["tutorial", "getting-started"]
  },
  "metadata": {
    "tags": ["blog", "featured"],
    "author": "john@example.com"
  }
}

Localization API

Manage multi-language content with comprehensive translation management, export capabilities, and JavaScript SDK integration for dynamic language switching.

🌍 Access Control

  • Public Access Option: Enable public GET requests for translations
  • Domain Protection: Always enforced regardless of public access setting
  • API Key Required: For create, update, delete, and private access
  • Export Formats: JSON, CSV, and key-value formats supported
  • JavaScript SDK: Easy integration with React and vanilla JS
GEThttps://staticbox.io/api/projects/{projectId}/localization/{localizationProjectId}/entriesAuth Required

Query Parameters

  • limit - Number of entries to return (default: 100, max: 100)
  • offset - Number of entries to skip (pagination)
  • search - Search by translation key or content
  • language - Filter by specific language code
  • onlyIncomplete - Show only incomplete translations (true/false)
Get All Translation Entries
const response = await fetch(
  'https://staticbox.io/api/projects/PROJECT_ID/localization/LOCALIZATION_PROJECT_ID/entries',
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
);

const { entries } = await response.json();
console.log('Translation entries:', entries);

Response Format

Translation Entries Response
{
  "entries": [
    {
      "id": "entry-uuid",
      "key": "welcome.title",
      "description": "Main welcome message title",
      "translations": {
        "en": "Welcome to our website",
        "es": "Bienvenido a nuestro sitio web",
        "fr": "Bienvenue sur notre site web"
      },
      "completionPercentage": 100,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-16T10:00:00Z"
    },
    {
      "id": "entry-uuid-2",
      "key": "navigation.home",
      "description": "Home navigation link",
      "translations": {
        "en": "Home",
        "es": "Inicio",
        "fr": ""
      },
      "completionPercentage": 67,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 100,
    "offset": 0
  }
}

Project Management API

Manage projects, team members, and invitations programmatically for collaborative workflows.

GET /api/projects

List all projects for authenticated user

POST /api/projects

Create new project with settings

Create Project
{
  "name": "My New Project",
  "description": "A project for my portfolio site",
  "settings": {
    "allowedOrigins": ["https://mysite.com", "https://www.mysite.com"],
    "emailNotifications": true,
    "webhookUrl": "https://mysite.com/webhook",
    "webhookAuth": {
      "type": "bearer",
      "token": "webhook-secret-token"
    },
    "spamFilter": {
      "enabled": true,
      "strictMode": false,
      "threshold": 0.8
    }
  }
}

Project Response

Project Details
{
  "project": {
    "id": "project-uuid",
    "name": "My New Project",
    "description": "A project for my portfolio site",
    "settings": {
      "allowedOrigins": ["https://mysite.com"],
      "emailNotifications": true,
      "webhookUrl": "https://mysite.com/webhook",
      "spamFilter": {
        "enabled": true,
        "strictMode": false,
        "threshold": 0.8
      }
    },
    "role": "owner",
    "createdAt": "2024-01-15T10:00:00Z",
    "stats": {
      "totalSubmissions": 0,
      "totalForms": 0,
      "totalCollections": 0
    }
  }
}

Examples

Real-world examples of how to integrate StaticBox APIs into your applications.

Complete Contact Form
<!DOCTYPE html>
<html>
<head>
    <title>Contact Form</title>
    <style>
        .form-group { margin-bottom: 1rem; }
        .form-group label { display: block; margin-bottom: 0.5rem; }
        .form-group input, .form-group textarea { 
            width: 100%; padding: 0.5rem; border: 1px solid #ccc; 
        }
        .btn { background: #6366f1; color: white; padding: 0.75rem 1.5rem; border: none; }
        .message { padding: 1rem; margin: 1rem 0; border-radius: 4px; }
        .success { background: #d1fae5; color: #065f46; }
        .error { background: #fee2e2; color: #991b1b; }
    </style>
</head>
<body>
    <form id="contactForm">
        <div class="form-group">
            <label>Name *</label>
            <input type="text" name="name" required>
        </div>
        
        <div class="form-group">
            <label>Email *</label>
            <input type="email" name="email" required>
        </div>
        
        <div class="form-group">
            <label>Message *</label>
            <textarea name="message" rows="4" required></textarea>
        </div>
        
        <!-- Honeypot for spam protection -->
        <input type="text" name="_honeypot" style="display: none;" tabindex="-1">
        
        <button type="submit" class="btn">Send Message</button>
    </form>
    
    <div id="messageDiv"></div>

    <script>
        document.getElementById('contactForm').addEventListener('submit', async (e) => {
            e.preventDefault();
            
            const formData = new FormData(e.target);
            const data = Object.fromEntries(formData.entries());
            
            try {
                const response = await fetch('https://staticbox.io/api/forms/YOUR_PROJECT_ID/contact/submit', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'x-api-key': 'YOUR_API_KEY'
                    },
                    body: JSON.stringify(data)
                });
                
                const result = await response.json();
                const messageDiv = document.getElementById('messageDiv');
                
                if (response.ok) {
                    messageDiv.innerHTML = `<div class="message success">${result.message}</div>`;
                    e.target.reset();
                } else {
                    messageDiv.innerHTML = `<div class="message error">${result.error}</div>`;
                }
            } catch (error) {
                document.getElementById('messageDiv').innerHTML = 
                    '<div class="message error">Network error. Please try again.</div>';
            }
        });
    </script>
</body>
</html>

Domain Security

StaticBox provides comprehensive domain-based security controls to protect your APIs from unauthorized access and ensure requests only come from approved domains.

All form submissions and data store operations are protected by CORS (Cross-Origin Resource Sharing) validation when domain restrictions are configured.

⚠️ Important

When domain restrictions are enabled, API requests are blocked unless they originate from an approved domain. This applies to both forms and data stores.

Domain Configuration Options

Single Domain (Project Settings)
Basic Domain Protection
{
  "project": {
    "id": "project-123",
    "name": "My Website", 
    "domain": "mywebsite.com"   // Single domain validation
  }
}
Multiple Origins (Advanced)
Advanced Domain Protection
{
  "project": {
    "id": "project-123",
    "name": "My Website",
    "settings": {
      "allowedOrigins": [
        "https://mywebsite.com",
        "https://www.mywebsite.com", 
        "https://staging.mywebsite.com",
        "*.subdomain.com"  // Wildcard support
      ]
    }
  }
}

CORS Headers Response

CORS Headers
Access-Control-Allow-Origin: https://mywebsite.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, x-api-key
Access-Control-Allow-Credentials: false

Rate Limits

StaticBox implements rate limiting to ensure fair usage and prevent abuse.

Forms API

  • Rate Limit: 100 submissions per hour per IP
  • Burst Limit: 10 submissions per minute
  • Headers: X-RateLimit-* headers included

Data Store API

  • Rate Limit: 1000 requests per hour per API key
  • Burst Limit: 50 requests per minute
  • Headers: X-RateLimit-* headers included

Rate Limit Exceeded

When rate limits are exceeded, the API returns a 429 status code. Implement exponential backoff to handle these gracefully.

Need Help?

Check out our examples or contact support for assistance.

View Examples