← Back to Docs

StackBloom API Documentation

REST API reference for integrating StackBloom apps into your own projects

Quick Links

AuthenticationRate LimitsForms APIPDF Suite APIURL Shortener APIMonitor APIWebhooksError Handling

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key: Generate API keys from your dashboard in each app's settings (Forms, URL Shortener, etc.)

Rate Limits

API requests are rate-limited to ensure service quality. Rate limit information is included in response headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per hour
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetTime when the rate limit resets

Default Limits

  • Starter: 100 requests/hour
  • Pro: 1,000 requests/hour
  • Business: 10,000 requests/hour
  • Enterprise: 100,000 requests/hour

Forms API

Create, manage, and submit forms programmatically.

POST/api/forms

Create a new form

Request Body:

{
  "name": "Contact Form",
  "description": "Main contact form for website",
  "template": "contact" // optional
}

Response (201):

{
  "id": "form_12345",
  "name": "Contact Form",
  "description": "Main contact form for website",
  "isPublished": false,
  "createdAt": "2026-02-18T10:30:00Z"
}
GET/api/forms

List all forms with filtering options

Query Parameters:

  • status - Filter by status (published, draft)
POST/api/forms/:id/submit

Submit a form (public endpoint)

Request Body:

{
  "data": {
    "field_id_1": "John Doe",
    "field_id_2": "john@example.com",
    "field_id_3": "Message content"
  }
}
GET/api/forms/:id/submissions

Retrieve form submissions with pagination

PDF Suite API

Convert, edit, and manipulate PDF documents programmatically.

POST/api/pdf-suite/convert

Convert PDF to various formats

Request Body:

{
  "fileUrl": "https://example.com/document.pdf",
  "targetFormat": "docx", // docx, xlsx, txt, jpg, png
  "options": {
    "dpi": 150 // for image conversions
  }
}

Response (200):

{
  "success": true,
  "url": "https://storage.example.com/converted.docx",
  "format": "docx",
  "size": 245678
}

Supported Conversions

From PDF:

  • PDF to Word (docx)
  • PDF to Excel (xlsx)
  • PDF to Text (txt)
  • PDF to Images (jpg, png)

To PDF:

  • Word to PDF
  • Excel to PDF
  • Images to PDF

URL Shortener API

Create, manage, and track shortened URLs with detailed analytics.

POST/api/v1/links

Create a new shortened link

Request Body:

{
  "destination": "https://example.com/very-long-url",
  "slug": "custom-slug", // optional
  "title": "My Link", // optional
  "tags": ["marketing"], // optional
  "password": "secret", // optional
  "expiresAt": "2026-12-31T23:59:59Z", // optional
  "maxClicks": 1000 // optional
}

Response (201):

{
  "success": true,
  "data": {
    "id": "clx1234567890",
    "slug": "custom-slug",
    "shortUrl": "https://stackbloom.io/r/custom-slug",
    "destination": "https://example.com/very-long-url",
    "title": "My Link",
    "tags": ["marketing"],
    "isActive": true,
    "currentClicks": 0,
    "maxClicks": 1000,
    "expiresAt": "2026-12-31T23:59:59Z",
    "createdAt": "2026-02-18T10:30:00Z"
  }
}
GET/api/v1/links

List all links with pagination

Query Parameters:

  • limit - Number of results (max 100, default 50)
  • offset - Pagination offset (default 0)
  • tag - Filter by tag
  • active - Filter by active status (true/false)

Response (200):

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
PATCH/api/v1/links/:id

Update an existing link

DELETE/api/v1/links/:id

Delete a link permanently

GET/api/v1/links/:id/analytics

Get detailed analytics for a link

Query Parameters:

  • period - Time period (24h, 7d, 30d, all)
  • granularity - Data granularity (hourly, daily)

Monitor API

Monitor websites, APIs, and servers with uptime checks and alerts.

POST/api/monitor/monitors

Create a new monitor

Request Body:

{
  "name": "Production API",
  "type": "HTTP", // HTTP, SSL, KEYWORD, API, PORT, PING, HEARTBEAT, DOMAIN, PAGE_SPEED
  "url": "https://api.example.com",
  "method": "GET",
  "checkInterval": 60, // seconds (10-3600)
  "timeout": 30, // seconds
  "expectedStatusCode": 200,
  "followRedirects": true,
  "locations": ["us-east"],
  "keyword": "success", // for KEYWORD type
  "keywordMode": "PRESENT" // PRESENT or ABSENT
}

Response (201):

{
  "id": "mon_12345",
  "name": "Production API",
  "type": "HTTP",
  "url": "https://api.example.com",
  "isActive": true,
  "isPaused": false,
  "createdAt": "2026-02-18T10:30:00Z"
}
GET/api/monitor/monitors

List all monitors with latest status

Monitor Types

Basic:

  • HTTP - Website monitoring
  • PING - Network connectivity
  • PORT - Port availability

Advanced:

  • SSL - Certificate monitoring
  • API - API endpoint checks
  • KEYWORD - Content monitoring

Special:

  • HEARTBEAT - Cron job monitoring
  • DOMAIN - Domain expiry
  • PAGE_SPEED - Performance

Webhooks

Receive real-time notifications about events in your StackBloom apps.

Available Events

Forms:

  • form.submitted - New form submission
  • form.published - Form published

Monitor:

  • monitor.down - Monitor went down
  • monitor.up - Monitor came back up
  • incident.created - New incident
  • incident.resolved - Incident resolved

URL Shortener:

  • link.clicked - Link was clicked
  • link.expired - Link expired

Webhook Payload Example

{
  "event": "form.submitted",
  "timestamp": "2026-02-18T10:30:00Z",
  "data": {
    "formId": "form_12345",
    "submissionId": "sub_67890",
    "fields": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Webhook Security

All webhooks include an X-StackBloom-Signature header with an HMAC-SHA256 signature. Verify this signature using your webhook secret to ensure the request is authentic.

Error Handling

All error responses follow a consistent format across the StackBloom API.

Error Response Format

{
  "error": "Error message description",
  "details": [...] // optional, for validation errors
}

HTTP Status Codes

200
OK - Request successful
201
Created - Resource created successfully
400
Bad Request - Invalid input or validation error
401
Unauthorized - Invalid or missing API key
403
Forbidden - Insufficient permissions or tier limit reached
404
Not Found - Resource doesn't exist
409
Conflict - Resource already exists (e.g., slug taken)
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error - Something went wrong on our end

Code Examples

JavaScript / Node.js

// Create a shortened URL
const response = await fetch('https://www.stackbloom.io/api/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    destination: 'https://example.com',
    slug: 'my-link',
    title: 'My Awesome Link'
  })
});

const data = await response.json();
console.log(data.data.shortUrl);

Python

import requests

# Create a form
response = requests.post(
    'https://www.stackbloom.io/api/forms',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Contact Form',
        'description': 'Main contact form',
    }
)

data = response.json()
print(f"Form created: {data['id']}")

cURL

# Create a monitor
curl -X POST https://www.stackbloom.io/api/monitor/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "HTTP",
    "url": "https://api.example.com",
    "checkInterval": 60
  }'

PHP

<?php
// Convert PDF to Word
$ch = curl_init('https://www.stackbloom.io/api/pdf-suite/convert');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'fileUrl' => 'https://example.com/document.pdf',
    'targetFormat' => 'docx',
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Converted file: " . $data['url'];
?>

API Versioning

The StackBloom API uses URL-based versioning for certain endpoints:

  • URL Shortener: /api/v1/links
  • Other apps: /api/[app-name]/... (no version prefix)

We maintain backwards compatibility and will announce any breaking changes at least 90 days in advance.

Support & Resources

Need Help?

Additional Resources