SignalLayer — API Docs

Quickstart

Three steps to your first query.

1. Get an API Key

No credit card needed. Free tier includes 500 queries/day.

Create Free API Key

sl_live_...

Save this key — it won't be shown again. Use it in the playground →

Or use curl:

bash

curl -X POST https://signallayer-2.polsia.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My App"}'

2. Generate a Query

Replace YOUR_KEY with the key from step 1.

bash

curl -X POST https://signallayer-2.polsia.app/api/v1/query/generate \
  -H "Authorization: Bearer sl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me all users who signed up this week",
    "schema": {
      "tables": [{
        "name": "users",
        "columns": [
          {"name": "id", "data_type": "serial", "is_primary_key": true},
          {"name": "email", "data_type": "varchar(255)"},
          {"name": "name", "data_type": "varchar(255)"},
          {"name": "created_at", "data_type": "timestamptz"}
        ]
      }]
    }
  }'

3. Use the Result

json — response

{
  "success": true,
  "data": {
    "sql": "SELECT id, email, name, created_at FROM users WHERE created_at >= NOW() - INTERVAL '7 days' ORDER BY created_at DESC LIMIT 100",
    "params": [],
    "explanation": "Retrieves all users who registered within the last 7 days, ordered by most recent first",
    "is_read_only": true,
    "estimated_complexity": "simple"
  }
}

Authentication

All API endpoints (except key creation and docs) require an API key. Pass it via:

Authorization header (recommended)

Authorization: Bearer sl_live_abc123...

x-api-key header (alternative)

x-api-key: sl_live_abc123...

API keys start with sl_live_. Free tier: 500 queries/day, 30/minute. The raw key is only shown once at creation — save it securely.

Try It Live

Try one of these examples:

Interactive Playground

Enter your API key and a natural language question. The generated SQL is ready to execute against your database.

API Key No key yet? Get one free →

Natural Language Query Schema (JSON, optional — include for best results)

Result

Generate Query

POST /api/v1/query/generate

Convert a natural language question into a safe, parameterized PostgreSQL query.

Request Body

Parameter	Type	Description
query	string required	Natural language question (max 2000 chars)
schema	object optional	Database schema context (tables, columns, relationships)
allow_write	boolean optional	Allow INSERT/UPDATE/DELETE (default: false, Pro only)
max_rows	integer optional	Max rows in LIMIT clause (default: 100)
target_tables	string[] optional	Focus generation on specific tables

Example Request

json — request body

{
  "query": "Top 5 customers by total order value",
  "schema": {
    "tables": [
      {
        "name": "customers",
        "columns": [
          { "name": "id", "data_type": "serial", "is_primary_key": true },
          { "name": "name", "data_type": "varchar(255)" },
          { "name": "email", "data_type": "varchar(255)" }
        ]
      },
      {
        "name": "orders",
        "columns": [
          { "name": "id", "data_type": "serial", "is_primary_key": true },
          { "name": "customer_id", "data_type": "integer" },
          { "name": "amount", "data_type": "decimal(10,2)" },
          { "name": "created_at", "data_type": "timestamptz" }
        ]
      }
    ]
  }
}

Response

Field	Type	Description
data.sql	string	Generated PostgreSQL query
data.params	array	Parameterized values ($1, $2, ...)
data.explanation	string	Plain English explanation
data.is_read_only	boolean	Whether query is read-only
data.tables_referenced	string[]	Tables used in the query
data.safety_flags	string[]	Safety check results
usage	object	Token usage and timing

Common Errors

Code	Status	Cause & Fix
INVALID_INPUT	400	`query` field missing or empty. Send: `{"query": "your question", ...}`
INVALID_SCHEMA	400	Schema malformed. Check: `{"tables": [{"name": "...", "columns": [...]}]}`
QUERY_TOO_LONG	400	Query exceeds 2000 chars. Trim your natural language input.
WRITE_REQUIRES_PRO	403	`allow_write: true` requires Pro tier. Upgrade →
UNAUTHORIZED	401	Missing or invalid API key. Check `Authorization: Bearer sl_live_...` header.

Validate Query

POST /api/v1/query/validate

Check if a SQL query is safe to execute. Detects injection patterns, dangerous statements, and missing safety guards.

Parameter	Type	Description
sql	string required	SQL query to validate
allow_write	boolean optional	Allow write operations (default: false)

json — request body

{
  "sql": "SELECT id, email FROM users WHERE created_at > NOW() - INTERVAL '7 days'"
}

Explain Query

POST /api/v1/query/explain

Get a plain English explanation of what a SQL query does.

Parameter	Type	Description
sql	string required	SQL query to explain
schema	object optional	Database schema for better context

Introspect Schema

POST /api/v1/schema/introspect

Connect to a PostgreSQL database and discover its schema — tables, columns, indexes, and foreign key relationships.

Parameter	Type	Description
connection_string	string required	PostgreSQL connection string (postgres://...)
schema_name	string optional	Schema to introspect (default: "public")

Connection strings are used transiently and never stored. We recommend using read-only database credentials.

Usage Stats

GET /api/v1/usage?period=30d

Get usage statistics for your API key. Available periods: 24h, 7d, 30d.

MCP Protocol

SignalLayer exposes a Model Context Protocol (MCP) endpoint for direct agent integration. Any MCP-compatible agent can connect and use our tools natively.

Claude Desktop / Cursor / Windsurf config

{
  "mcpServers": {
    "signallayer-db": {
      "url": "https://signallayer-2.polsia.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sl_live_YOUR_KEY"
      }
    }
  }
}

Example MCP Call

JSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "generate_query",
    "arguments": {
      "query": "Find the top 10 customers by revenue",
      "schema": { "tables": [...] }
    }
  },
  "id": 1
}

MCP Tools

Four tools are available via the MCP endpoint:

generate_query

Convert natural language to safe PostgreSQL. Accepts schema context for accurate results.

introspect_schema

Connect to a database and discover tables, columns, indexes, and relationships.

validate_query

Check SQL safety — detects injection, dangerous statements, missing limits.

explain_query

Get plain English explanation of any SQL query.

Install from GitHub

npm publish is currently pending review. In the meantime, install the MCP server directly from our GitHub repo — works identically.

Option 1 — Clone & run locally

Requires Node.js 18+. Runs the stdio MCP server as a local process.

bash

git clone https://github.com/Polsia-Inc/signallayer-2
cd signallayer-2/packages/mcp-server
npm install

bash — start the server

SIGNALLAYER_API_KEY=sl_live_YOUR_KEY node index.js

Option 2 — Run directly with npx from GitHub

bash

SIGNALLAYER_API_KEY=sl_live_YOUR_KEY npx github:Polsia-Inc/signallayer-2/packages/mcp-server

Claude Desktop config (after cloning)

Add to your claude_desktop_config.json. Replace the path with your actual clone location.

claude_desktop_config.json

{
  "mcpServers": {
    "signallayer": {
      "command": "node",
      "args": ["/path/to/signallayer-2/packages/mcp-server/index.js"],
      "env": {
        "SIGNALLAYER_API_KEY": "sl_live_YOUR_KEY"
      }
    }
  }
}

Cursor / Windsurf config

Same shape — add to your IDE's MCP server config file.

.cursor/mcp.json or .windsurf/mcp.json

{
  "mcpServers": {
    "signallayer": {
      "command": "node",
      "args": ["/path/to/signallayer-2/packages/mcp-server/index.js"],
      "env": {
        "SIGNALLAYER_API_KEY": "sl_live_YOUR_KEY"
      }
    }
  }
}

Coming soon: npm package @signallayer/mcp-server is pending review. Once published, installation will be simply npx @signallayer/mcp-server with no cloning required.

Safety & Validation

Every generated query passes through multiple safety checks:

Check	Description
Read-only enforcement	SELECT only by default. Write ops require explicit `allow_write: true`
Dangerous statement blocking	DROP, TRUNCATE, ALTER, CREATE, GRANT always blocked
Injection detection	Detects common SQL injection patterns (UNION injection, command execution)
Multi-statement prevention	Only single SQL statements allowed (no semicolon stacking)
Parameterization	User values use $1, $2 params — never interpolated into SQL
Row limiting	Automatic LIMIT clause when not specified (default: 100)
System table flagging	Access to pg_catalog/information_schema is flagged

Pricing

Free Tier

$0/mo

500 queries/day · 30/min · 3 API keys · Read-only

Pro

$49/mo

10,000 queries/day · 120/min · Unlimited keys · Write ops · Priority support

Database Query API Docs

First time here? You're 60 seconds from your first query.

Quickstart

1. Get an API Key

2. Generate a Query

3. Use the Result

Authentication

Try It Live

Interactive Playground

Generate Query

Request Body

Example Request

Response

Common Errors

Validate Query

Explain Query

Introspect Schema

Usage Stats

MCP Protocol

Example MCP Call

MCP Tools

Install from GitHub

Option 1 — Clone & run locally

Option 2 — Run directly with npx from GitHub

Claude Desktop config (after cloning)

Cursor / Windsurf config

Safety & Validation

Pricing

Free Tier

Pro