Skip to main content

API Overview

StagDB provides a comprehensive RESTful API for programmatic access to all functionality.

Base URL​

All API requests should be made to:

https://api.stagdb.com/v1

Authentication​

Currently, StagDB uses simple API key authentication:

curl -H "Authorization: Bearer your-api-key" \
  https://api.stagdb.com/v1/databases

Response Format​

All responses are JSON formatted:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully"
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid database type specified"
  }
}

Rate Limits​

  • General API: 1000 requests per hour
  • Database Operations: 100 operations per hour
  • Snapshot/Branch Operations: 50 operations per hour

Endpoints Overview​

Databases​

  • GET /databases - List all databases
  • POST /databases - Create new database
  • GET /databases/{id} - Get database details
  • PUT /databases/{id} - Update database
  • DELETE /databases/{id} - Delete database
  • POST /databases/{id}/start - Start database
  • POST /databases/{id}/stop - Stop database

Snapshots​

  • GET /databases/{id}/snapshots - List snapshots
  • POST /databases/{id}/snapshots - Create snapshot
  • GET /snapshots/{id} - Get snapshot details
  • DELETE /snapshots/{id} - Delete snapshot

Branches​

  • GET /databases/{id}/branches - List branches
  • POST /databases/{id}/branches - Create branch
  • POST /snapshots/{id}/branches - Create branch from snapshot
  • DELETE /databases/{branch-id} - Delete branch

Monitoring​

  • GET /databases/{id}/stats - Get database statistics
  • GET /databases/{id}/logs - Get database logs
  • GET /health - API health check

Example Workflows​

Create and Manage Database​

# Create database
curl -X POST https://api.stagdb.com/v1/databases \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-db",
    "type": "postgresql",
    "version": "15"
  }'

# Get database info
curl -H "Authorization: Bearer your-api-key" \
  https://api.stagdb.com/v1/databases/my-app-db

# Create snapshot
curl -X POST https://api.stagdb.com/v1/databases/my-app-db/snapshots \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "backup-snapshot"}'

SDKs and Libraries​

Official SDKs​

  • Python: pip install stagdb-python
  • JavaScript/Node.js: npm install stagdb-js
  • Go: go get github.com/stagdb/stagdb-go

Community SDKs​

  • Ruby: gem install stagdb-ruby
  • PHP: composer require stagdb/stagdb-php

Webhooks​

Subscribe to database events:

{
  "url": "https://your-app.com/webhooks/stagdb",
  "events": ["database.created", "database.deleted", "snapshot.created"],
  "secret": "webhook-secret"
}

Event payload:

{
  "event": "database.created",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "database_id": "db-12345",
    "name": "my-app-db",
    "type": "postgresql"
  }
}

OpenAPI Specification​

Full API documentation is available in OpenAPI format:

Error Codes​

Common error codes:

  • VALIDATION_ERROR - Invalid request parameters
  • NOT_FOUND - Resource not found
  • UNAUTHORIZED - Invalid or missing API key
  • RATE_LIMITED - Too many requests
  • SERVER_ERROR - Internal server error
  • RESOURCE_BUSY - Resource is being modified
  • INSUFFICIENT_RESOURCES - Not enough system resources

Pagination​

List endpoints support pagination:

curl "https://api.stagdb.com/v1/databases?page=1&limit=50" \
  -H "Authorization: Bearer your-api-key"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}