API Integration

The MongoDash REST API enables programmatic access to your MongoDB data, query execution, dashboard management, and workspace administration.

Overview

Use the API to:

• Execute queries - Run MongoDB queries and aggregations programmatically
• Manage connections - Add, update, and remove database connections
• Automate dashboards - Create and update dashboards via code
• Export data - Programmatically export collections and query results
• Manage users - Automate user provisioning and role assignments
• Access audit logs - Retrieve activity logs for compliance and monitoring

Authentication

API Keys

Create API keys for secure authentication:

Authorization: Bearer your_api_key_here

Key Permissions

Control what each API key can access:

Key Rotation

Regularly rotate API keys for security:

# Rotate an API key
curl -X POST https://api.mongodash.com/v1/api-keys/key_abc123/rotate \
  -H "Authorization: Bearer CURRENT_API_KEY" \
  -H "Content-Type: application/json"

Returns a new key while invalidating the old one.

Base URL and Versioning

API Endpoint

All API requests use the base URL:

https://api.mongodash.com/v1

Versioning

The API is versioned via the URL path. Current version is v1.

Regional Endpoints

Use region-specific endpoints for lower latency:

• US East: https://us-east.api.mongodash.com/v1
• US West: https://us-west.api.mongodash.com/v1
• EU: https://eu.api.mongodash.com/v1
• Asia Pacific: https://ap.api.mongodash.com/v1

Core API Endpoints

Connections

List connections:

GET /v1/connections
 
curl -X GET https://api.mongodash.com/v1/connections \
  -H "Authorization: Bearer YOUR_API_KEY"

Create connection:

POST /v1/connections
 
curl -X POST https://api.mongodash.com/v1/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Database",
    "uri": "mongodb+srv://user:pass@cluster.mongodb.net",
    "environment": "production"
  }'

Test connection:

POST /v1/connections/{connection_id}/test
 
curl -X POST https://api.mongodash.com/v1/connections/conn_abc123/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Queries

Execute query:

POST /v1/queries/execute
 
curl -X POST https://api.mongodash.com/v1/queries/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": "conn_abc123",
    "database": "production_db",
    "collection": "users",
    "filter": {"status": "active"},
    "limit": 100
  }'

Execute aggregation:

POST /v1/queries/aggregate
 
curl -X POST https://api.mongodash.com/v1/queries/aggregate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": "conn_abc123",
    "database": "production_db",
    "collection": "orders",
    "pipeline": [
      {"$match": {"status": "completed"}},
      {"$group": {
        "_id": "$customerId",
        "totalSpent": {"$sum": "$amount"}
      }},
      {"$sort": {"totalSpent": -1}},
      {"$limit": 10}
    ]
  }'

List saved queries:

GET /v1/queries
 
curl -X GET https://api.mongodash.com/v1/queries \
  -H "Authorization: Bearer YOUR_API_KEY"

Data Export

Export collection:

POST /v1/export
 
curl -X POST https://api.mongodash.com/v1/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": "conn_abc123",
    "database": "production_db",
    "collection": "users",
    "format": "csv",
    "filter": {"createdAt": {"$gte": "2024-01-01"}},
    "fields": ["email", "name", "createdAt"]
  }'

Download export:

GET /v1/export/{export_id}/download
 
curl -X GET https://api.mongodash.com/v1/export/exp_xyz789/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output export.csv

Dashboards

List dashboards:

GET /v1/dashboards
 
curl -X GET https://api.mongodash.com/v1/dashboards \
  -H "Authorization: Bearer YOUR_API_KEY"

Create dashboard:

POST /v1/dashboards
 
curl -X POST https://api.mongodash.com/v1/dashboards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Dashboard",
    "layout": "grid",
    "widgets": [
      {
        "type": "metric",
        "title": "Total Revenue",
        "query": {
          "connection": "conn_abc123",
          "database": "production_db",
          "collection": "orders",
          "aggregation": [
            {"$match": {"status": "completed"}},
            {"$group": {"_id": null, "total": {"$sum": "$amount"}}}
          ]
        }
      }
    ]
  }'

Get dashboard data:

GET /v1/dashboards/{dashboard_id}/data
 
curl -X GET https://api.mongodash.com/v1/dashboards/dash_abc123/data \
  -H "Authorization: Bearer YOUR_API_KEY"

Users and Permissions Team

List workspace members:

GET /v1/workspace/members
 
curl -X GET https://api.mongodash.com/v1/workspace/members \
  -H "Authorization: Bearer YOUR_API_KEY"

Invite user:

POST /v1/workspace/invitations
 
curl -X POST https://api.mongodash.com/v1/workspace/invitations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "role": "editor",
    "message": "Welcome to our MongoDash workspace!"
  }'

Update user role:

PATCH /v1/workspace/members/{user_id}
 
curl -X PATCH https://api.mongodash.com/v1/workspace/members/usr_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Audit Logs Enterprise

Retrieve audit logs:

GET /v1/audit-logs
 
curl -X GET https://api.mongodash.com/v1/audit-logs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filter": {
      "timestamp": {"$gte": "2024-02-01T00:00:00Z"},
      "action": {"$regex": "^user\\."}
    },
    "limit": 100,
    "sort": {"timestamp": -1}
  }'

Request and Response Format

Request Format

All POST, PUT, and PATCH requests must include JSON payloads:

Content-Type: application/json

Response Format

All responses return JSON:

{
  "success": true,
  "data": {
    "id": "query_abc123",
    "results": [...],
    "count": 42
  },
  "meta": {
    "executionTime": "145ms",
    "timestamp": "2024-02-24T10:15:32Z"
  }
}

Error Responses

Errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query filter contains invalid operators",
    "details": {
      "field": "filter.$invalidOp",
      "reason": "Operator not supported"
    }
  },
  "requestId": "req_xyz789"
}

HTTP Status Codes

Rate Limits

Default Limits

Rate limits by plan:

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1708776000

Handling Rate Limits

When rate limited (429 response):

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retryAfter": 45
  }
}

Implement exponential backoff:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
 
    if (response.status !== 429) {
      return response;
    }
 
    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
 
  throw new Error('Max retries exceeded');
}

Pagination

Cursor-Based Pagination

For large result sets:

curl -X GET 'https://api.mongodash.com/v1/queries?limit=100&cursor=eyJ...' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes next cursor:

{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJsYXN0SWQiOiI2NWQ4...",
    "total": 5432
  }
}

Offset-Based Pagination

Alternative pagination method:

curl -X GET 'https://api.mongodash.com/v1/audit-logs?limit=50&offset=100' \
  -H "Authorization: Bearer YOUR_API_KEY"

SDKs and Libraries

Official SDKs

Node.js:

npm install @mongodash/sdk

const { MongoDash } = require('@mongodash/sdk');
 
const client = new MongoDash({
  apiKey: process.env.MONGODASH_API_KEY,
  region: 'us-east'
});
 
// Execute query
const results = await client.queries.execute({
  connection: 'conn_abc123',
  database: 'production_db',
  collection: 'users',
  filter: { status: 'active' },
  limit: 100
});
 
console.log(results.data);

Python:

pip install mongodash-sdk

from mongodash import MongoDash
 
client = MongoDash(api_key=os.environ['MONGODASH_API_KEY'])
 
# Execute aggregation
results = client.queries.aggregate(
    connection='conn_abc123',
    database='production_db',
    collection='orders',
    pipeline=[
        {'$match': {'status': 'completed'}},
        {'$group': {
            '_id': '$customerId',
            'totalSpent': {'$sum': '$amount'}
        }}
    ]
)
 
for doc in results['data']:
    print(doc)

Go:

go get github.com/mongodash/mongodash-go

package main
 
import (
    "context"
    "github.com/mongodash/mongodash-go"
)
 
func main() {
    client := mongodash.NewClient(mongodash.Config{
        APIKey: os.Getenv("MONGODASH_API_KEY"),
    })
 
    results, err := client.Queries.Execute(context.Background(), &mongodash.QueryRequest{
        Connection: "conn_abc123",
        Database:   "production_db",
        Collection: "users",
        Filter:     map[string]interface{}{"status": "active"},
        Limit:      100,
    })
 
    if err != nil {
        log.Fatal(err)
    }
 
    fmt.Println(results.Data)
}

Webhooks

Configure webhooks to receive events:

POST /v1/webhooks
 
curl -X POST https://api.mongodash.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhook",
    "events": ["query.completed", "export.finished"],
    "secret": "webhook_secret_key"
  }'

Verify webhook signatures:

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}
 
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-mongodash-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
 
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process webhook
  console.log('Received event:', req.body);
  res.status(200).send('OK');
});

Best Practices

Security

1. Rotate API keys - Regularly rotate keys, especially after employee changes
2. Use environment variables - Never hardcode API keys
3. Implement least privilege - Use read-only keys when write access isn't needed
4. Monitor API usage - Track API calls for unusual patterns
5. Use HTTPS - Always use secure connections

Performance

1. Implement caching - Cache responses when appropriate
2. Use pagination - Don't request all data at once
3. Batch requests - Combine multiple operations when possible
4. Handle rate limits - Implement exponential backoff
5. Use regional endpoints - Connect to nearest region for lower latency

Error Handling

1. Check status codes - Don't assume success
2. Log request IDs - Include in error reports for support
3. Implement retries - Handle transient failures
4. Validate responses - Check response structure before using data
5. Monitor errors - Track error rates and types

Example Use Cases

Automated Reporting

// Daily report generation
const cron = require('node-cron');
const { MongoDash } = require('@mongodash/sdk');
 
const client = new MongoDash({ apiKey: process.env.MONGODASH_API_KEY });
 
cron.schedule('0 8 * * *', async () => {
  const results = await client.queries.aggregate({
    connection: 'prod',
    database: 'analytics',
    collection: 'events',
    pipeline: [
      {
        $match: {
          timestamp: {
            $gte: new Date(Date.now() - 24 * 60 * 60 * 1000)
          }
        }
      },
      {
        $group: {
          _id: '$eventType',
          count: { $sum: 1 }
        }
      }
    ]
  });
 
  await sendEmailReport(results.data);
});

Data Synchronization

# Sync data to external warehouse
from mongodash import MongoDash
import psycopg2
 
client = MongoDash(api_key=os.environ['MONGODASH_API_KEY'])
 
# Export from MongoDB
export = client.export.create(
    connection='prod',
    database='app_db',
    collection='users',
    format='json'
)
 
# Wait for export
export_data = client.export.download(export['id'])
 
# Load to PostgreSQL
conn = psycopg2.connect(os.environ['POSTGRES_URL'])
cursor = conn.cursor()
 
for user in export_data:
    cursor.execute(
        "INSERT INTO users (id, email, name) VALUES (%s, %s, %s)",
        (user['_id'], user['email'], user['name'])
    )
 
conn.commit()

What's Next?

• Webhooks - Configure event-driven integrations
• Scheduled Queries - Automate recurring queries
• API Keys - Manage API authentication