Altus 4

Appearance

API Reference ​

Complete API Documentation for Altus 4

Altus 4 provides a RESTful API for managing database connections, executing searches, and accessing analytics. All endpoints follow REST conventions and return JSON responses.

Authentication ​

Altus 4 uses dual authentication depending on the endpoint type:

  • JWT Tokens: For user management, database connections, analytics dashboards, and API key management
  • API Keys: For search operations and service-to-service integrations

Authentication Flow ​

  1. Register a new user account
  2. Login to receive a JWT token
  3. Create your first API key using the JWT token via /api/v1/management/setup
  4. Use JWT tokens for user management, database connections, analytics, and API key management
  5. Use API keys for search operations and service integrations
bash
# Use JWT token for account management
Authorization: Bearer <jwt-token>

# Use API key for search operations
Authorization: Bearer <api-key>

API Key Format: altus4_sk_live_abc123def456... (live) or altus4_sk_test_xyz789abc123... (test)

Authentication Endpoints ​

MethodEndpointDescriptionAuth
POST/api/v1/auth/registerRegister new userNone
POST/api/v1/auth/loginUser loginNone
GET/api/v1/auth/profileGet user profileJWT
PUT/api/v1/auth/profileUpdate user profileJWT
POST/api/v1/auth/change-passwordChange user passwordJWT
POST/api/v1/auth/refreshRefresh JWT tokenJWT
POST/api/v1/auth/logoutLogout userJWT
DELETE/api/v1/auth/accountDeactivate accountJWT
POST/api/v1/management/setupCreate first API keyJWT
GET/api/v1/management/migration-statusCheck migration statusJWT
POST/api/v1/keysCreate new API keyJWT
GET/api/v1/keysList API keysJWT
PUT/api/v1/keys/:keyIdUpdate API keyJWT
DELETE/api/v1/keys/:keyIdRevoke API keyJWT
GET/api/v1/keys/:keyId/usageGet API key usage statsJWT
POST/api/v1/keys/:keyId/regenerateRegenerate API keyJWT

→ Complete API Key Authentication Guide

Database Management ​

Manage MySQL database connections for searching.

Database Endpoints ​

MethodEndpointDescriptionAuth
GET/api/v1/databasesList user databasesAPI Key (admin)
POST/api/v1/databasesAdd database connectionAPI Key (admin)
GET/api/v1/databases/:connectionIdGet database detailsAPI Key (admin)
PUT/api/v1/databases/:connectionIdUpdate database connectionAPI Key (admin)
DELETE/api/v1/databases/:connectionIdRemove database connectionAPI Key (admin)
POST/api/v1/databases/:connectionId/testTest database connectionAPI Key (admin)
GET/api/v1/databases/:connectionId/schemaGet database schemaAPI Key (admin)
GET/api/v1/databases/statusGet connection statusesAPI Key (admin)

Complete Database Documentation

Search Operations ​

Execute searches across connected databases with AI enhancements.

Search Endpoints ​

MethodEndpointDescriptionAuth
POST/api/v1/searchExecute searchAPI Key
GET/api/v1/search/suggestionsGet search suggestionsAPI Key
POST/api/v1/search/analyzeAnalyze query performanceAPI Key
GET/api/v1/search/historyGet search historyAPI Key
GET/api/v1/search/trendsGet user search trendsAPI Key

Note: API keys must include search permission for search and suggestions; analytics permission is required for analyze and trends.

Complete Search Documentation

Analytics & Insights ​

Access search analytics, performance metrics, and trend data.

Analytics Endpoints ​

MethodEndpointDescriptionAuth
GET/api/v1/analytics/dashboardGet dashboard dataAPI Key (analytics)
GET/api/v1/analytics/search-trendsGet search trendsAPI Key (analytics)
GET/api/v1/analytics/performanceGet performance metricsAPI Key (analytics)
GET/api/v1/analytics/popular-queriesGet popular queriesAPI Key (analytics)
GET/api/v1/analytics/search-historyGet search historyAPI Key (analytics)
GET/api/v1/analytics/insightsGet AI-generated insightsAPI Key (analytics)
GET/api/v1/analytics/admin/system-overviewGet system overview (admin)API Key (admin)
GET/api/v1/analytics/admin/user-activityGet user activity (admin)API Key (admin)
GET/api/v1/analytics/admin/performance-metricsGet system performance (admin)API Key (admin)

Complete Analytics Documentation

System Endpoints ​

Health checks and system information.

MethodEndpointDescriptionAuth
GET/healthSystem health checkNone
GET/api/v1/management/healthManagement healthNone

Request/Response Format ​

Standard Response Format ​

All API responses follow this structure:

typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta?: {
    timestamp: Date;
    requestId: string;
    version: string;
    executionTime?: number;
  };
}

Success Response Examples ​

User Registration Response ​

json
{
  "success": true,
  "data": {
    "user": {
      "id": "dc6e0cee-efe8-4134-be55-249d6a36ae19",
      "email": "user@example.com",
      "name": "Test User",
      "role": "user",
      "connectedDatabases": [],
      "createdAt": "2025-09-06T16:19:56.195Z",
      "lastActive": "2025-09-06T16:19:56.195Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "meta": {
    "timestamp": "2025-09-06T16:19:56.197Z",
    "requestId": "1b53d9d6-ca2e-4b99-959b-8459820475b4",
    "version": "0.3.0"
  }
}

API Key Creation Response ​

json
{
  "success": true,
  "data": {
    "apiKey": {
      "id": "9c81d4cf-fff8-48d0-994a-adc07e56bff3",
      "name": "Initial API Key",
      "keyPrefix": "altus4_sk_test_8wEp0HQVYpT6POU",
      "environment": "test",
      "permissions": ["search"],
      "rateLimitTier": "free",
      "createdAt": "2025-09-06T16:20:01.401Z"
    },
    "secretKey": "altus4_sk_test_8wEp0HQVYpT6POUumHNuFdvK9gMw3y2Wa9a_BjVoOJw",
    "warning": "This is the only time the full API key will be shown. Please store it securely."
  },
  "meta": {
    "timestamp": "2025-09-06T16:20:01.403Z",
    "requestId": "fb62455b-8ccd-4cbb-898a-606ba936e25c",
    "version": "0.3.0"
  }
}

Error Response Example ​

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "query",
      "reason": "Query cannot be empty"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "version": "0.3.0"
  }
}

Error Handling ​

HTTP Status Codes ​

StatusCodeDescriptionCommon Causes
200OKRequest successful-
201CreatedResource createdRegistration, database connection
400Bad RequestInvalid requestMissing/invalid parameters
401UnauthorizedAuthentication requiredMissing/invalid API key
403ForbiddenInsufficient permissionsAPI key lacks required permissions
404Not FoundResource not foundInvalid database/search ID
429Too Many RequestsRate limit exceededToo many API calls
500Internal Server ErrorServer errorDatabase/Redis connectivity issues

Error Codes ​

Error CodeHTTP StatusDescription
INVALID_API_KEY401Missing or invalid API key
INSUFFICIENT_PERMISSIONS403API key lacks required permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid request data
RATE_LIMIT_EXCEEDED429Too many requests (tiered by API key)
DATABASE_ERROR500Database connectivity/query error
CACHE_ERROR500Redis connectivity error
AI_SERVICE_ERROR500OpenAI API error
INTERNAL_ERROR500Unexpected server error

Complete Error Documentation

Rate Limiting ​

API requests are rate-limited based on your API key tier for fair usage and system stability.

Rate Limit Tiers ​

TierRequests/HourUse CaseBlock Duration
Free1,000Development, testing5 minutes
Pro10,000Small-medium prod5 minutes
Enterprise100,000Large scale prod1 minute

Rate Limiting for Authentication ​

  • Registration/Login: 10 requests per minute (IP-based)
  • API key management: Based on your API key tier

Rate Limit Headers ​

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2024-01-15T12:00:00Z
X-RateLimit-Tier: Free

Rate Limit Exceeded Response ​

json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "resetTime": "2024-01-15T10:31:00.000Z",
      "tier": "Free",
      "upgradeMessage": "Upgrade to Pro or Enterprise for higher rate limits"
    }
  }
}

Request Examples ​

cURL Examples ​

bash
# Register new user
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password",
    "name": "Test User"
  }'

# Login and get JWT token (for initial setup only)
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password"
  }'

# Create your first API key
curl -X POST http://localhost:3000/api/v1/management/setup \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Execute search with API key (use for all subsequent requests)
curl -X POST http://localhost:3000/api/v1/search \
  -H "Authorization: Bearer altus4_sk_test_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mysql performance optimization",
    "databases": ["db-uuid-1", "db-uuid-2"],
    "searchMode": "semantic",
    "limit": 20
  }'

JavaScript/Node.js Examples ​

javascript
// Using fetch API
const response = await fetch('http://localhost:3000/api/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`, // altus4_sk_live_abc123...
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'database optimization',
    databases: ['db-uuid-1'],
    searchMode: 'natural',
    limit: 10,
  }),
});

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

Python Examples ​

python
import requests

# Search request
response = requests.post(
    'http://localhost:3000/api/v1/search',
    headers={
        'Authorization': f'Bearer {api_key}',  # altus4_sk_live_abc123...
        'Content-Type': 'application/json'
    },
    json={
        'query': 'performance tuning',
        'databases': ['db-uuid-1'],
        'searchMode': 'boolean',
        'limit': 15
    }
)

data = response.json()
print(data['data']['results'])

Need Help? ​

Check out: