API Overview

Welcome to the Data Builder Public API. This API allows you to access and query your Perfex CRM data using RESTful endpoints. It's designed to be fast, secure, and developer-friendly.

Base URL https://databuilder.polyxgo.com/api/v1/

Demo note: API domains in examples alternate between your current host and a generic domain (https://your-api-site.com/api/v1) so users understand this is configurable.

Getting Started

To use this API, you need a valid Bearer Token. Integration samples are provided for several languages in the sidebar for each endpoint.

Sandbox — Safe & Private
• All response data (names, emails, phones, amounts, …) is randomized — no real system data is returned.
• Passwords, payment details, tokens, and secrets are masked or excluded entirely.
• All write operations (POST, PUT, DELETE) are simulated — nothing is persisted to the database.
• To enable sandbox requests, create a token at Admin → Data Builder → API Tokens and set it in Settings → Public Demo Token.

PUBLIC DEMO TOKEN

dba_51d5••••••••••••••••••••••••••••••••••••••••d186

Authentication

All API requests must include your API token in the `Authorization` HTTP header as a Bearer token.

HTTP Header

Authorization: Bearer YOUR_TOKEN_HERE

HMAC Verification

If your token has HMAC signing enabled, every request must include `X-Timestamp` and `X-Signature` headers to ensure data integrity.

PHP Node.js Python cURL

<?php
$method    = "POST";
$path      = "/api/v1/graphql"; // Always starts with /
$query     = ""; // Data after ? in URL
$body      = json_encode(["query" => "{ ... }"]);
$timestamp = time();
$secret    = "YOUR_HMAC_SECRET";

$bodyHash  = hash('sha256', $body);
$canonical = implode("\n", [$method, $path, $query, $bodyHash, $timestamp]);
$signature = hash_hmac('sha256', $canonical, $secret);

// Headers
$headers = [
    "Authorization: Bearer YOUR_TOKEN",
    "X-Timestamp: " . $timestamp,
    "X-Signature: " . $signature,
    "Content-Type: application/json"
];

const crypto = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const method    = "POST";
const path      = "/api/v1/graphql";
const query     = "";
const body      = JSON.stringify({ query: "{ ... }" });
const secret    = "YOUR_HMAC_SECRET";

const bodyHash  = crypto.createHash('sha256').update(body).digest('hex');
const canonical = [method, path, query, bodyHash, timestamp].join("\n");
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

const headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
};

import hmac, hashlib, time, json

timestamp = str(int(time.time()))
method    = "POST"
path      = "/api/v1/graphql"
query     = ""
body      = json.dumps({"query": "{ ... }"})
secret    = b"YOUR_HMAC_SECRET" # Must be bytes

body_hash = hashlib.sha256(body.encode()).hexdigest()
canonical = "\n".join([method, path, query, body_hash, timestamp])
signature = hmac.new(secret, canonical.encode(), hashlib.sha256).hexdigest()

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
}

# Example: Manual test with pre-calculated values
# Replace timestamps/signatures with values from your local calculator
curl -X POST 'https://your-domain.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Timestamp: 1711900000' \
  -H 'X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ ... }"}'

Canonical String Construction Guide

The signature is computed over a strictly ordered string to ensure both client and server validate the exact same data context:

{METHOD}\n{PATH}\n{QUERY}\n{SHA256_BODY}\n{TIMESTAMP}

\n: Represents a literal newline character (LF).
{PATH}: Must begin with a leading slash (e.g. /api/v1/graphql).
{SHA256_BODY}: A lowercase hex-encoded SHA256 hash of the raw request body.

Testing with Postman

Complete guide to export, import, and configure the API collection in Postman for testing all REST and GraphQL endpoints.

Step 1 — Create an API Token

Before you can make any API request, you need a valid API token.

Go to Admin → Data Builder → API Tokens
Click "Create Token"
Fill in the token name (e.g., Postman Testing)
Select Scopes: choose tables, views, and write as needed
Select Allowed Tables and Allowed Views the token can access
Click Save
Copy the token immediately — it is only shown once

Important — The token is stored as a SHA-256 hash. If you lose the plain text token, you must revoke and create a new one. Tokens follow the format dba_{48_hex_characters}.

Step 2 — Export the Postman Collection

Download the pre-built collection with all endpoints, headers, and query parameters.

Postman Collection v2.1

DataBuilder_API.postman_collection.json

Step 3 — Import into Postman

Import the downloaded JSON file into your Postman workspace.

Open Postman (desktop app or web)
Click Import (top-left, or Ctrl+O / ⌘+O)
Drag and drop the .json file or click "Upload Files"
Click "Import" to confirm
The collection "Data Builder API" appears in your sidebar with all folders: Resources, Reports, GraphQL

Step 4 — Configure Collection Variables

The exported collection uses two variables that you must set before testing.

Variable	Value	Description
`{{baseUrl}}`	`https://databuilder.polyxgo.com/api/v1`	API base URL — auto-filled from export, update if your domain changes
`{{api_token}}`	`dba_xxxxxxx...`	Paste the token you created in Step 1
`{{hmac_secret}}`	`Optional secret`	The HMAC Secret key (only if HMAC is enabled for the token)

How to set variables in Postman:

Click the collection name "Data Builder API" in the sidebar
Go to the "Variables" tab
baseUrl is pre-filled — update the CURRENT VALUE column if your server URL differs (e.g., https://yourdomain.com/api/v1)
Set api_token CURRENT VALUE to your token from Step 1
Click Save (Ctrl+S / ⌘+S)

Tip — The collection-level authentication is already configured to use Bearer {{api_token}}. All requests inherit this automatically — no need to set Authorization on each request individually.

Step 5 — Send Your First Request

You're all set! Try a quick test:

Expand Resources folder in the collection sidebar
Click any GET List request
The URL bar shows: {{baseUrl}}/resource_name
Click the Send button
View the JSON response in the Body tab below ✓

Step 6 — Production Security: HMAC Signatures

Security Policy Alert — For development and local testing, you can disable HMAC on your tokens for simplicity. However, for Production Environments, we strongly recommend enabling HMAC Signature Verification to prevent request tampering and replay attacks.

If your token has an HMAC Secret configured, Postman must generate a valid X-Signature for every request. You can automate this using a Pre-request Script:

Postman Pre-request Script:

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = pm.request.method.toUpperCase();
const secret = pm.environment.get("hmac_secret");

if (secret) {
    const url = pm.request.url;
    // Build path: ensure it starts with /
    const path = "/" + url.getPathWithQuery().split('?')[0]; 
    const query = url.getQueryString() || "";
    // Body digest (SHA256)
    const bodyRaw = pm.request.body.raw || "";
    const bodyHash = CryptoJS.SHA256(bodyRaw).toString();

    // Canonical string: METHOD\nPATH\nQUERY\nBODY_HASH\nTIMESTAMP
    const canonical = [method, path, query, bodyHash, timestamp].join("\n");
    const signature = CryptoJS.HmacSHA256(canonical, secret).toString();

    pm.request.headers.add({ key: 'X-Timestamp', value: timestamp });
    pm.request.headers.add({ key: 'X-Signature', value: signature });
}

Paste this script into the "Pre-request Script" tab of the collection (or a specific request) and ensure the {{hmac_secret}} variable is set.

Available Query Parameters

List endpoints include pre-configured query parameters (disabled by default). Enable them in the Params tab:

Param	Example	Description
`page`	`1`	Page number
`per_page`	`25`	Records per page (max 1000)
`sort`	`-id`	Sort field — prefix `-` for DESC
`fields`	`id,name,email`	Sparse fieldset — only return listed columns
`filter`	`status:1`	Filter results by field value

Testing with OpenAPI

Use the exported OpenAPI 3.0 specification to test your REST & GraphQL endpoints in Swagger UI, Insomnia, or integrate with AI platforms like ChatGPT (OpenAI Actions).

Step 1 — Download the OpenAPI Spec

Export the auto-generated OpenAPI 3.0.3 YAML file that includes all your REST and GraphQL endpoints.

All Tables — YAML

DataBuilder_API_OpenAPI3.yaml

Custom Export (OpenAI)

Select specific tables to export

Includes — All REST CRUD operations, Report endpoints, GraphQL mutation/query endpoint, Bearer authentication, and RFC 9457 error schemas.

Step 2 — Import into Your Favorite Tool

The OpenAPI spec can be used with many tools:

Swagger UI

Open editor.swagger.io
Go to File → Import File
Upload the .yaml file
Click Authorize and enter your token
Click Try it out on any endpoint

Insomnia

Open Insomnia and create a new project
Click Import → select the .yaml file
Set Bearer Token in environment
All endpoints appear with parameters pre-filled
Click Send to test

Step 3 — Integrate with ChatGPT (OpenAI Actions)

Use the OpenAPI spec to create a Custom GPT Action that allows ChatGPT to query your CRM data in real-time.

Go to ChatGPT GPT Editor → Create a GPT
In the Configure tab, scroll down to Actions → click "Create new action"
Click "Import from URL" or paste the raw YAML content into the schema editor
Set Authentication: select API Key, Auth Type: Bearer, paste your API token
Click "Save" — ChatGPT can now query your API endpoints

Tip — Your server must be publicly accessible for ChatGPT to reach it. For local development, use a tunnel like ngrok or Cloudflare Tunnel.

Real-World Use Cases

With the right API branches configured, your Custom GPT becomes a powerful AI-powered CRM analyst. Here are some practical scenarios:

Data Analysis — Ask ChatGPT to analyze customer data, identify trends, and surface insights from your CRM

Project Status — "Which projects are overdue?" or "Show project progress for client X"

Client Insights — "Which clients have the most projects?" or "Rank customers by total revenue"

Unpaid Invoices — "List all overdue invoices" or "Total outstanding amount this quarter"

Revenue Reports — "Monthly revenue breakdown by payment method" or "Compare Q1 vs Q2 sales"

AI Reports — Combine multiple API calls to generate comprehensive summaries and actionable recommendations

Try it now — Data Builder for Perfex

A ready-to-use Custom ChatGPT that connects directly to your CRM via the Data Builder API. Ask questions in natural language and get instant answers.

Open in ChatGPT

Step 4 — Testing GraphQL with the OpenAPI Spec

The OpenAPI export includes the POST /graphql endpoint schema. Here's how to use it:

Swagger UI cURL ChatGPT Prompt

# In Swagger UI's "Try it out" for POST /graphql:
# Set the request body to:
{
  "query": "{ staffs(limit: 5) { id email firstname lastname } }",
  "variables": {},
  "operationName": null
}

# For mutations:
{
  "query": "mutation { createProject(input: { name: \"New Project\", clientid: 1 }) { id name } }",
  "variables": {}
}

# List query
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ staffs(limit: 5) { id email firstname lastname } }"
  }'

# Introspection query (discover all types)
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ __schema { types { name kind } } }"
  }'

# Mutation example
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation { createProject(input: { name: \\"API Test\\", clientid: 1 }) { id name } }"
  }'

# Example prompts you can use with your Custom GPT:

"List all staff members with their email addresses"
→ GPT will call: POST /graphql with query { staffs { id firstname lastname email } }

"Show me the 5 latest projects"
→ GPT will call: GET /projects?sort=-id&per_page=5

"Create a new task for project ID 3 with name 'Review API docs'"
→ GPT will call: POST /tasks with body { rel_type: "project", rel_id: 3, name: "Review API docs" }

"Get the schema of the invoices table"
→ GPT will call: GET /invoices/schema

"Run a monthly revenue report grouped by status"
→ GPT will call: GET /reports/invoices/aggregate?dimension=status&measure=total&aggregation=sum&period=monthly

What's Included in the Spec

Feature	Details
REST CRUD	GET list, GET by ID, POST create, PUT update, DELETE, GET schema — for every allowed table
Reports	Query and Aggregate endpoints for every published View/Report
GraphQL	`POST /graphql` with query, variables, and operationName schema
Authentication	Bearer Token (BearerAuth) security scheme
Query Params	`page`, `per_page`, `sort`, `fields`, `filter` — described with types and defaults
Error Schema	RFC 9457 Problem Details schema for 401, 403, 429 responses

Tips

The spec is dynamically generated based on your current allowed tables and views — export again after changes.
For ChatGPT Actions, keep your token scopes minimal (read-only) for safety.
Use the Postman Collection for more detailed request body samples and pre-configured queries.
If HMAC is enabled on your token, see the Authentication section for signing details.

Webhooks & Events

Listen for real-time events in Perfex CRM to sync data with external systems, push notifications, or trigger custom workflows in third-party services like Zapier, Make.com, or AWS Lambda.

Ready-made integration templates for Zapier, Make, n8n, and Notion are included in this Webhooks section below.

How it Works

An event occurs in Perfex CRM (e.g., a new tblclients record is created).
The Data Builder Webhook Engine securely intercepts the trigger and strips out sensitive columns like passwords, salts, logic keys, etc.
Custom Field Mapping Rules (whitelist, blacklist, field renaming) configured in your subscription are applied to the payload.
An HTTP POST request is asynchronously dispatched to your receiving app over the cURL Channel with an optional HMAC Signature.

Supported Event Types

Webhooks can be narrowed down to specific tables or set to capture everything. The engine triggers on 3 core data lifecycle events:

Event Type	Trigger Condition
`table.create`	Fired immediately after an INSERT statement executes for an allowed table.
`table.update`	Fired immediately after an UPDATE statement executes. Note: only fields affected by the update query and the Primary Key are guaranteed to be present.
`table.delete`	Fired immediately after a DELETE statement. Payload consists of the primary key ID of the deleted resource.

Payload Structure

Example Output (JSON)

{
  "event": "table.create",
  "table": "tblclients",
  "record_id": "42",
  "timestamp": 1711900500,
  "data": {
    "userid": "42",
    "company": "PolyXGO Software",
    "vat": "123456789",
    "phonenumber": "0123456789",
    "country": "243",
    "city": "Hanoi"
  }
}

Data Restructuring — If you configured Field Renaming (e.g. mapping `company` to `business_name`), the `data` object will automatically reflect the mapped keys.

Security & Validation (HMAC)

If you generated an HMAC Secret for your Webhook, the server will attach an X-Signature-HMAC-SHA256 header to every POST request.
You should verify this signature in your receiving application to ensure the request genuinely came from Perfex CRM.

Node.js / Express PHP

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

const WEBHOOK_SECRET = 'your-generated-hmac-secret-here';

// Important: Parse raw body for accurate hashing
app.post('/api/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const signatureHeader = req.headers['x-signature-hmac-sha256'];
    const rawBody = req.body; // Buffer

    // Calculate expected signature
    const expectedSignature = crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(rawBody)
        .digest('hex');

    // Secure compare
    if (crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signatureHeader))) {
        // Validation Passed
        const payload = JSON.parse(rawBody.toString());
        console.log('Received event:', payload.event, payload.table);
        res.status(200).send('OK');
    } else {
        // Validation Failed
        res.status(401).send('Invalid signature');
    }
});

<?php
define('WEBHOOK_SECRET', 'your-generated-hmac-secret-here');

$signatureHeader = $_SERVER['HTTP_X_SIGNATURE_HMAC_SHA256'] ?? '';
$rawBody = file_get_contents('php://input');

$expectedSignature = hash_hmac('sha256', $rawBody, WEBHOOK_SECRET);

if (hash_equals($expectedSignature, $signatureHeader)) {
    // Validation Passed
    $payload = json_decode($rawBody, true);
    error_log("Received valid event: " . $payload['event'] . " for table " . $payload['table']);
    
    http_response_code(200);
    echo "OK";
} else {
    // Validation Failed
    http_response_code(401);
    die("Invalid webhook signature.");
}

Live Simulator (Sandbox)

Test webhook dispatches right from this page. We'll fire a dummy payload to a public mock receiver so you can observe the exact output format.

Target Table

Event Type

Test HMAC Secret (Optional)

Mock Receiver Output

Waiting for event...

Automation Use Cases (Zapier, Make, n8n, Notion)

Ready-to-apply integration playbooks for developers. Use these patterns to push Data Builder events into no-code/low-code tools and collaboration systems with minimal custom code.

Recommended pattern: Keep Data Builder webhook payload as your source event, then normalize once in Zapier/Make/n8n before routing to tools like Notion, Slack, Email, Sheets, or internal APIs.

Canonical Event Shape (Normalization Template)

Use this unified structure so every downstream step reads the same keys regardless of source table.

Normalized Event JSON

{
  "source": "perfex-data-builder",
  "event": "table.create",
  "table": "tbltasks",
  "record_id": "603",
  "occurred_at_unix": 1711900500,
  "idempotency_key": "tbltasks:603:table.create:1711900500",
  "data": {
    "id": 603,
    "name": "Review API docs",
    "rel_type": "project",
    "rel_id": 1775,
    "status": 1
  }
}

Field	Why It Matters
`event`, `table`, `record_id`	Base routing and dedup keys in any automation tool.
`idempotency_key`	Prevents duplicate processing on retries.
`data`	Business payload used for mapping to Notion/Zapier/Make/n8n actions.

Use Case 1: Zapier - New Task to Slack + Notion

Goal: whenever a new task is created in Perfex CRM, notify Slack and create a Notion item.

Create a Data Builder Webhook subscription for tbltasks + table.create.
Set receiver URL to your Zapier Catch Hook URL.
Add a Zapier Filter step: event == table.create and table == tbltasks.
Add Slack action (Send Channel Message).
Add Notion action (Create Database Item) and map required properties from data.*.

Zapier Formatter / Code Step (optional normalize)

const input = inputData.payload ? JSON.parse(inputData.payload) : inputData;

return {
  source: "perfex-data-builder",
  event: input.event,
  table: input.table,
  record_id: String(input.record_id || input.id || ""),
  idempotency_key: [input.table, input.record_id, input.event, input.timestamp].join(":"),
  task_name: input.data && input.data.name ? input.data.name : "Untitled task",
  project_id: input.data && input.data.rel_id ? String(input.data.rel_id) : ""
};

Use Case 2: Make - Invoice Event to Notion + Email

Goal: route invoice events by status, then create/update tracking rows in Notion and send notification emails.

Make Module	Config Hint
Webhooks → Custom webhook	Receive Data Builder payload.
Router + Filters	Branch by `event` / `table` / status value in `data`.
Notion → Create/Update DB Item	Use `record_id` as external reference key.
Gmail/SMTP → Send Email	Include invoice number, amount, and idempotency key.

Use Case 3: n8n - Validation + Transform + Notion Sync

Goal: implement stricter control (signature checks, custom logic, retries) before writing to Notion.

Webhook node receives Data Builder event.
IF node validates allowed combinations (e.g., table == tblprojects).
Code node builds canonical object and fallback defaults.
HTTP Request node calls Notion API (or any destination API).
Respond to Webhook node returns 200 quickly.

n8n Code Node (normalize + defaults)

const payload = $json;
const data = payload.data || {};

return [{
  source: "perfex-data-builder",
  event: payload.event || "unknown",
  table: payload.table || "unknown",
  record_id: String(payload.record_id || ""),
  idempotency_key: [payload.table, payload.record_id, payload.event, payload.timestamp].join(":"),
  title: data.name || data.subject || ("Record " + (payload.record_id || "")),
  occurred_at_unix: payload.timestamp || 0,
  raw: payload
}];

Use Case 4: Notion-First Status Board (Poll Mode)

If your environment cannot receive webhooks, use scheduled pulls from REST endpoints and upsert rows in Notion by external ID.

Polling Request Pattern

GET https://your-api-site.com/api/v1/tasks?per_page=20&sort=-id
Authorization: Bearer YOUR_TOKEN

# Store last synced ID or timestamp in your automation platform
# and only process newer records each run.

Implementation Checklist

Use Data Builder Field Mapping Rules to expose only fields your automation truly needs.
Add dedup control using idempotency_key (or table + record_id + event + timestamp).
Return fast 2xx responses from receivers, then do heavy processing asynchronously.
For Notion, keep a dedicated External ID property to support safe upsert behavior.
Keep platform secrets in Zapier/Make/n8n secure credential vaults (not hardcoded in workflow text).

API Samples Module

Free companion module that helps you understand and integrate with the REST API and GraphQL endpoints provided by Data Builder — Visual Reporting, REST API & GraphQL for Perfex CRM.

What is this?

The API Data Builder Sample is a free, open-source Perfex CRM module that provides interactive, working demos of every Data Builder API feature. Install it in your admin panel to explore REST CRUD operations, execute GraphQL queries, and test webhook integrations — all with live code examples you can copy into your own projects.

Included Demos

REST API

Full CRUD on Projects, Staff, Payments, Invoices, Tasks, Clients
Pagination, sorting, sparse fieldsets
Live response viewer with status codes & timing
Auto-generated PHP sample code

GraphQL Playground

Query editor with one-click templates
Mutation templates (Create, Update, Delete)
Variables support for parameterized queries
Structured result table + raw JSON viewer

Webhooks

Event listener for table.create / update / delete
Payload inspector & JSON viewer
Integration guide for third-party services

Security & Config

HMAC-SHA256 request signing
Connection test with one-click verification
Admin Session Bypass for dev environments
Robust non-JSON error handling

Download API Samples Module

Free & open-source. Install in your Perfex CRM modules/ folder. Includes REST demos, GraphQL playground, webhook listener, and full source code you can customize.

View on GitHub

Quick Installation

Download or clone from GitHub
Copy the api_data_builder_sample folder directly into your Perfex CRM modules/ directory, or compress it as a .zip file following Perfex CRM module packaging standards and use Admin → Setup → Modules → Browse to upload & install
Go to Admin → Setup → Modules, find "API Data Builder Sample" and click Activate
Navigate to API Samples → Settings to configure your API Base URL and Token
Click Test Connection to verify — you’re ready!

Note — This sample module connects to the REST API & GraphQL endpoints provided by Data Builder v2.0.0+. The two modules do not need to be installed on the same system — API Samples is a standalone reference client that can query any Perfex CRM site running Data Builder. Simply point it to the target site’s API URL and provide a valid API Token (created in Data Builder → API Tokens).

Deployment Guide

Server-level configuration for production deployments. Some security features require web server configuration — PHP cannot intercept slow HTTP attacks because they occur before PHP receives the request.

Slow HTTP Protection

Protects against Slowloris and similar slow-read/slow-header attacks.

Apache

Add to your VirtualHost or .htaccess. Requires mod_reqtimeout (enabled by default on most Apache installs).

Apache — httpd.conf or .htaccess

# Protects against slow-read and slow-header attacks (Slowloris, etc.)
RequestReadTimeout header=20-40,MinRate=500 body=30,MinRate=500

header=20-40,MinRate=500 — 20s to start headers, 40s max; min 500 B/s transfer rate
body=30,MinRate=500 — 30s total body read time; min 500 B/s

Nginx

Add to your server {} or location /api/ {} block.

Nginx — nginx.conf

# Slow HTTP protection
client_header_timeout  10s;
client_body_timeout    10s;
client_max_body_size   256k;    # Matches application DDoS shield body limit
keepalive_timeout      30s;
send_timeout           10s;

Body Size Limit Alignment

The application DDoS shield middleware enforces a configurable body size limit (default 256KB). Align your web server limit to match — if the web server limit is higher, it wastes resources receiving oversized payloads before the application check rejects them.

Server	Directive
Apache	`LimitRequestBody 262144`
Nginx	`client_max_body_size 256k`

MySQL Permissions

The tbldata_builder_api_rate table contains rate counters that must only be writable by the application DB user. Restricting access prevents unauthorized counter manipulation.

SQL — Restrict table access

-- Revoke from any monitoring/reporting users
REVOKE SELECT, INSERT, UPDATE, DELETE
  ON your_db.tbldata_builder_api_rate FROM 'readonly_user'@'%';

-- Grant only to the application user
GRANT SELECT, INSERT, UPDATE, DELETE
  ON your_db.tbldata_builder_api_rate TO 'app_user'@'localhost';

tbldata_builder_api_logs contains sensitive audit data — also restrict to app user and admin only.

Reverse Proxy / WAF

The application-level DDoS shield handles body size limits (413), IP-level fixed-window throttling, and malformed payload detection. For volumetric DDoS (layer 3/4) or large-scale layer 7 attacks, use external solutions:

Cloudflare

WAF + rate limiting + bot protection. Recommended for most setups.

AWS WAF + Shield

For AWS-hosted deployments with managed rules.

Nginx + fail2ban

Self-hosted: ban IPs exceeding rate limits.

HAProxy

Connection-level rate limiting before PHP.

Cloudflare Rate Limiting Rule (example)

Cloudflare — Rate Limiting

Match:    http.request.uri.path contains "/api/v1/"
Action:   Rate limiting — 500 requests per minute per IP
Response: 429 Too Many Requests

HTTPS Enforcement

All API tokens sent via Authorization: Bearer header must be transmitted over HTTPS only.

Apache

.htaccess

# Enforce HTTPS for API routes
RewriteCond %{HTTPS} off
RewriteCond %{REQUEST_URI} ^/api/v1/
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Nginx

nginx.conf — http block

if ($scheme != "https") {
    return 301 https://$host$request_uri;
}

Production Checklist

Ensure all items are configured before going live.

Web server slow HTTP protection configured (Apache / Nginx)

client_max_body_size matches application body limit (default 256KB)

MySQL grants on api_rate and api_logs tables restricted to app user

HTTPS enforced for /api/v1/ routes

WAF or reverse proxy in place for high-traffic deployments

api_allow_query_token left OFF (default) unless embed mode intentionally needed

Log retention cron job configured (default: purge logs older than 90 days)

Public Chart Reports

Public data views with embeddable chart reports. Click any report to open it in a new tab.

Activity Log

/embed/report/activity-log

Type URI	`https://databuilder.polyxgo.com/api_docs#error-query-string-too-long`
Description	The URL query string exceeds the maximum allowed length (default 4KB). This is a protection against query-based abuse.
Resolution	Reduce the number or length of query parameters. Use POST with a JSON body for complex queries.
Source	`DdosShieldMiddleware`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-invalid-parameter`
Description	One or more query parameters have invalid values. For aggregation endpoints, the `aggregation` parameter must be one of: sum, avg, count, min, max.
Resolution	Check the error detail for which parameter is invalid and what values are accepted.
Source	`Db_views`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-ip-not-allowed`
Description	The client IP address is not in the token's IP allowlist. IP filtering supports exact match and IPv4 CIDR notation (e.g., 192.168.1.0/24).
Resolution	Ensure your request originates from an IP address listed in the token's IP whitelist. Contact the API administrator to update the whitelist. Note: IPv6 addresses are not currently supported for CIDR matching.
Source	`ScopeVerifierMiddleware`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-scope-not-allowed`
Description	The token does not have the required scope for this operation. Scopes control which API features a token can access: `tables` (table endpoints), `views` (report endpoints), `graphql` (GraphQL endpoint), `write` (mutations/POST/PUT/DELETE).
Resolution	Update the token's scopes in the admin panel to include the required scope. Check which scope is needed from the error detail message.
Source	`ScopeVerifierMiddleware`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-not-found`
Description	The requested resource, record, table, or view was not found. This can mean the entity doesn't exist, is not published, or is not accessible with the current token permissions.
Resolution	Verify the resource name, record ID, or view slug is correct. Check that the resource is whitelisted and the view is published.
Source	`Db_resources / Db_tables / Db_views`

API Overview

Getting Started

Authentication

HMAC Verification

Testing with Postman

Step 1 — Create an API Token

Step 2 — Export the Postman Collection

Step 3 — Import into Postman

Step 4 — Configure Collection Variables

Step 5 — Send Your First Request

Step 6 — Production Security: HMAC Signatures

Available Query Parameters

Testing with OpenAPI

Step 1 — Download the OpenAPI Spec

Custom YAML Export

Step 2 — Import into Your Favorite Tool

Step 3 — Integrate with ChatGPT (OpenAI Actions)

Step 4 — Testing GraphQL with the OpenAPI Spec

What's Included in the Spec

Webhooks & Events

How it Works

Supported Event Types

Payload Structure

Security & Validation (HMAC)

Live Simulator (Sandbox)

Mock Receiver Output

Automation Use Cases (Zapier, Make, n8n, Notion)

Canonical Event Shape (Normalization Template)

Use Case 1: Zapier - New Task to Slack + Notion

Use Case 2: Make - Invoice Event to Notion + Email

Use Case 3: n8n - Validation + Transform + Notion Sync

Use Case 4: Notion-First Status Board (Poll Mode)

Implementation Checklist

API Samples Module

Included Demos

Quick Installation

Deployment Guide

Slow HTTP Protection

Apache

Nginx

Body Size Limit Alignment

MySQL Permissions

Reverse Proxy / WAF

Cloudflare Rate Limiting Rule (example)

HTTPS Enforcement

Apache

Nginx

Production Checklist

Public Chart Reports

Error Reference

Examples

Sandbox GET