Professional API Documentation

1. Generate an API key in your Account Settings
2. Use your key in the Authorization header: Authorization: Bearer vd_live_YOUR_KEY
3. Make requests to track AI tool adoption data programmatically

Generate API Key

Endpoint:

POST /api/user/api-keys

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body:

{
  "name": "My API Key"
}

Response:

{
  "success": true,
  "apiKey": "vd_live_abc123def456...",
  "keyData": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My API Key",
    "keyPrefix": "vd_live_abc",
    "createdAt": "2025-11-18T12:00:00Z"
  }
}

List Your API Keys

Endpoint:

GET /api/user/api-keys

Headers:

Authorization: Bearer <your_jwt_token>

Response:

{
  "success": true,
  "apiKeys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My API Key",
      "keyPrefix": "vd_live_abc",
      "createdAt": "2025-11-18T12:00:00Z",
      "lastUsedAt": "2025-11-18T14:30:00Z",
      "totalRequests": 1523
    }
  ]
}

Revoke an API Key

Endpoint:

DELETE /api/user/api-keys/:keyId

Headers:

Authorization: Bearer <your_jwt_token>

Response:

{
  "success": true,
  "message": "API key revoked successfully"
}

Track your favorite AI development tools and get real-time metrics.

Get Your Watchlist

Endpoint:

GET /api/watchlist

Headers:

Authorization: Bearer vd_live_YOUR_KEY

Response:

{
  "success": true,
  "watchlist": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "toolName": "openai",
      "toolType": "npm",
      "addedAt": "2025-11-01T12:00:00Z",
      "lastViewedAt": "2025-11-18T14:30:00Z"
    }
  ],
  "count": 2,
  "limit": 25,
  "tier": "professional"
}

Tier Limits:

• Starter: 5 tools
• Professional: 25 tools
• Enterprise: Unlimited

Add Tool to Watchlist

Endpoint:

POST /api/watchlist

Headers:

Authorization: Bearer vd_live_YOUR_KEY
Content-Type: application/json

Request Body:

{
  "toolName": "langchain",
  "toolType": "npm"
}

Tool Types:

• npm - NPM packages
• pypi - Python packages
• docker - Docker images
• github - GitHub repositories

Response:

{
  "success": true,
  "tool": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "toolName": "langchain",
    "toolType": "npm",
    "addedAt": "2025-11-18T15:00:00Z"
  }
}

Remove Tool from Watchlist

Endpoint:

DELETE /api/watchlist/:toolId

Headers:

Authorization: Bearer vd_live_YOUR_KEY

Response:

{
  "success": true,
  "message": "Tool removed from watchlist"
}

Get real-time notifications when your tracked tools show significant changes.

Configure Webhook

Endpoint:

POST /api/analytics/alerts/settings

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body:

{
  "threshold": 10,
  "frequency": "hourly",
  "customWebhook": "https://your-app.com/webhook"
}

Parameters:

• threshold (number, 1-100): Percentage change to trigger alert
• frequency (string): "hourly", "daily", or "weekly"
• customWebhook (string): HTTPS URL to receive webhooks

Response:

{
  "success": true,
  "message": "Alert settings saved successfully"
}

Webhook Payload Format

When a tool in your watchlist changes by more than the threshold, we'll POST to your webhook URL:

Payload:

{
  "event": "watchlist.metric_change",
  "timestamp": "2025-11-18T15:30:00Z",
  "data": {
    "toolName": "openai",
    "toolType": "npm",
    "metric": "weekly_downloads",
    "previousValue": 7500000,
    "currentValue": 7600000,
    "changePercent": 1.33,
    "changeAbsolute": 100000
  }
}

Headers:

X-Webhook-Signature: sha256=abc123def456...
X-Webhook-Event: watchlist.metric_change
User-Agent: VibeData-Webhooks/1.0
Content-Type: application/json

Verify Webhook Signature

We sign all webhook payloads with HMAC-SHA256. Verify the signature to ensure the request came from Vibe Data:

Node.js Example:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, YOUR_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  console.log('Tool changed:', req.body.data);
  res.status(200).send('OK');
});

Get Webhook Delivery Log

Endpoint:

GET /api/analytics/alerts/webhook-deliveries

Headers:

Authorization: Bearer <your_jwt_token>

Response:

{
  "success": true,
  "deliveries": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "webhookUrl": "https://your-app.com/webhook",
      "status": "delivered",
      "responseStatus": 200,
      "attemptNumber": 1,
      "maxAttempts": 3,
      "scheduledAt": "2025-11-18T15:00:00Z",
      "attemptedAt": "2025-11-18T15:00:01Z",
      "deliveredAt": "2025-11-18T15:00:01Z",
      "responseTimeMs": 142
    }
  ],
  "total": 1
}

Delivery Status:

• pending - Scheduled but not yet sent
• delivered - Successfully delivered (200-299 response)
• failed - Failed after all retries
• retrying - Failed but will retry

Retry Logic:

• Max 3 attempts per delivery
• Exponential backoff: 1s, 2s, 4s
• Retries on 5xx errors only (not 4xx client errors)

Professional Tier:

• 100 requests/minute per API key
• 2,000 requests/day per API key

Enterprise Tier:

• 500 requests/minute per API key
• 10,000 requests/day per API key

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1700326800

Rate Limit Exceeded Response:

{
  "error": "Rate limit exceeded",
  "limit": 100,
  "retryAfter": 42
}

All error responses follow this format:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": {}
}

Common Error Codes:

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Insufficient tier or limit reached
404	NOT_FOUND	Resource not found
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Server error (contact support)

cURL

Get Watchlist:

curl https://vibe-data.com/api/watchlist \
  -H "Authorization: Bearer vd_live_YOUR_KEY"

Add Tool to Watchlist:

curl https://vibe-data.com/api/watchlist \
  -X POST \
  -H "Authorization: Bearer vd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toolName":"langchain","toolType":"npm"}'

JavaScript/Node.js

const VIBE_DATA_API_KEY = 'vd_live_YOUR_KEY';
const BASE_URL = 'https://vibe-data.com/api';

// Get watchlist
async function getWatchlist() {
  const response = await fetch(`${BASE_URL}/watchlist`, {
    headers: {
      'Authorization': `Bearer ${VIBE_DATA_API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Add tool to watchlist
async function addTool(toolName, toolType) {
  const response = await fetch(`${BASE_URL}/watchlist`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${VIBE_DATA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ toolName, toolType })
  });

  return response.json();
}

Python

import requests

VIBE_DATA_API_KEY = 'vd_live_YOUR_KEY'
BASE_URL = 'https://vibe-data.com/api'

# Get watchlist
def get_watchlist():
    response = requests.get(
        f'{BASE_URL}/watchlist',
        headers={'Authorization': f'Bearer {VIBE_DATA_API_KEY}'}
    )
    response.raise_for_status()
    return response.json()

# Add tool to watchlist
def add_tool(tool_name, tool_type):
    response = requests.post(
        f'{BASE_URL}/watchlist',
        headers={
            'Authorization': f'Bearer {VIBE_DATA_API_KEY}',
            'Content-Type': 'application/json'
        },
        json={'toolName': tool_name, 'toolType': tool_type}
    )
    response.raise_for_status()
    return response.json()

Questions? Contact us at intelligence@vibe-data.com

Found a bug? Report issues to the same email with:

• Your API key prefix (first 12 characters only)
• Request/response details
• Timestamp of the error

---

Last Updated: 2025-11-18

API Version: v1