API Reference

Complete API documentation for SelfHostedDB

SelfHostedDB provides a RESTful API for programmatic access to your database. All endpoints require authentication (Basic Auth or API Keys).

Base URL

http://localhost:3001/api

For production deployments, replace localhost:3001 with your server address.

Authentication

SelfHostedDB supports two authentication methods:

HTTP Basic Authentication - Username and password
API Keys - Bearer token authentication

See Authentication Guide for detailed authentication information.

Quick Example:

# Basic Auth
curl -u admin:secret http://localhost:3001/api/health
 
# API Key
curl -H "Authorization: Bearer your-api-key-here" http://localhost:3001/api/health

Response Format

Success Response

All successful responses return JSON:

{
  "data": [...],
  "message": "Operation successful"
}

Error Response

Error responses follow this format:

{
  "error": "Error type",
  "message": "Detailed error message"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request (invalid parameters)
401	Unauthorized (authentication required)
404	Not Found
500	Internal Server Error

Rate Limiting

Currently, there are no rate limits on API requests. However, we recommend:

Implementing client-side rate limiting
Using connection pooling for database queries
Caching responses when appropriate

Versioning

The current API version is v1. All endpoints are under /api/ prefix.

Future versions will be available at /api/v2/, /api/v3/, etc.

Endpoints Overview

Health & System

GET /api/health - Health check (no auth required)

License & Trial

GET /api/license/status - Get current license status (no auth required)
POST /api/license/validate - Validate a license key (no auth required)
POST /api/license/activate - Activate a license key (no auth required)
POST /api/trial/start - Start a 14-day free trial (no auth required)
GET /api/trial/status - Get trial status (no auth required)

Schemas (Projects)

GET /api/schemas - List all schemas
POST /api/schema/create - Create new schema
DELETE /api/schema/:schemaName - Delete schema

API Keys

GET /api/project/:schema/keys - List API keys for schema
POST /api/project/:schema/keys - Create new API key
DELETE /api/project/:schema/keys/:keyId - Delete API key

Tables

GET /api/tables - List all tables
GET /api/table/:tableName - Get table data (paginated)
POST /api/table/create - Create new table
DELETE /api/table/:tableName - Delete table
POST /api/table/:tableName/clone - Clone table
GET /api/table/:tableName/export - Export table data

Table Columns

POST /api/table/:tableName/column - Add column to table

Table Rows

POST /api/table/:tableName/row - Insert new row
PATCH /api/table/:tableName/:rowId - Update row
DELETE /api/table/:tableName/row/:rowId - Delete row
POST /api/table/:tableName/rows/delete - Bulk delete rows

Queries

POST /api/query - Execute custom SQL query

Schema Information

GET /api/schema - Get schema information (tables, columns, foreign keys)

Complete Endpoint Reference

For detailed endpoint documentation with request/response examples, see All Endpoints.

Error Handling

Common Errors

401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

400 Bad Request:

{
  "error": "Invalid schema name",
  "message": "Schema name must start with a letter and contain only letters, numbers, and underscores"
}

404 Not Found:

{
  "error": "Table not found",
  "message": "Table 'users' does not exist"
}

500 Internal Server Error:

{
  "error": "Failed to fetch tables",
  "message": "Database connection error"
}

Best Practices

Always use HTTPS in production - Protect credentials and data in transit
Store API keys securely - Never commit API keys to version control
Handle errors gracefully - Check response status codes and error messages
Use pagination - For large datasets, use pagination parameters
Implement retry logic - Handle transient network errors
Cache responses - Cache static data to reduce API calls

SDKs and Libraries

Currently, SelfHostedDB provides a REST API. You can use any HTTP client library:

JavaScript/TypeScript: axios, fetch
Python: requests, httpx
Go: net/http
Ruby: httparty, faraday
PHP: guzzle, curl