GET
/
api
/
v2
/
health
curl --request GET \
  --url https://api.buena.ai/api/v2/health \
  --header 'x-api-key: <api-key>'
{
  "version": "2.0",
  "status": "healthy",
  "authentication": "user",
  "user": {
    "id": "user_abc123",
    "email": "john@company.com",
    "role": "Premium"
  },
  "apiKey": {
    "name": "My Integration Key",
    "permissions": [
      "linkedin:schedule",
      "linkedin:upload",
      "leads:read",
      "leads:write"
    ],
    "usageCount": 150
  },
  "timestamp": "2024-01-20T15:30:00Z"
}

The health endpoint provides a quick way to verify that:

  • The API is operational
  • Your API key is valid
  • Your authentication is working properly

This is typically the first endpoint you should test when integrating with the Buena.ai API.

This endpoint does not require any specific permissions and does not count heavily against rate limits.

​
Request

​
x-api-key
string
required

Your API key for authentication

curl -X GET "https://api.buena.ai/api/v2/health" \
  -H "x-api-key: YOUR_API_KEY"

​
Response

​
version
string

Current API version (e.g., “2.0”)

​
status
string

API health status (“healthy” or “degraded”)

​
authentication
string

Authentication type (“user” for valid API key)

​
user
object

Information about the authenticated user

​
apiKey
object

Information about the API key used

​
timestamp
string

ISO 8601 timestamp of the response

{
  "version": "2.0",
  "status": "healthy",
  "authentication": "user",
  "user": {
    "id": "user_abc123",
    "email": "john@company.com",
    "role": "Premium"
  },
  "apiKey": {
    "name": "My Integration Key",
    "permissions": [
      "linkedin:schedule",
      "linkedin:upload",
      "leads:read",
      "leads:write"
    ],
    "usageCount": 150
  },
  "timestamp": "2024-01-20T15:30:00Z"
}

​
Use Cases

​
1. Integration Testing

Use the health endpoint to verify your integration setup:

async function verifySetup() {
  try {
    const response = await fetch("https://api.buena.ai/api/v2/health", {
      headers: { "x-api-key": process.env.BUENA_API_KEY },
    });

    if (response.ok) {
      const data = await response.json();
      console.log("✅ API integration working");
      console.log("📝 Permissions:", data.apiKey.permissions);
      return true;
    } else {
      console.error("❌ API integration failed");
      return false;
    }
  } catch (error) {
    console.error("❌ Connection failed:", error.message);
    return false;
  }
}

​
2. Permission Verification

Check if your API key has the required permissions:

def check_permissions(required_permissions):
    response = requests.get(
        'https://api.buena.ai/api/v2/health',
        headers={'x-api-key': os.getenv('BUENA_API_KEY')}
    )

    if response.status_code == 200:
        data = response.json()
        available = set(data['apiKey']['permissions'])
        required = set(required_permissions)

        if required.issubset(available):
            print("✅ All required permissions available")
            return True
        else:
            missing = required - available
            print(f"❌ Missing permissions: {missing}")
            return False
    else:
        print("❌ Health check failed")
        return False

# Example usage
check_permissions(['linkedin:schedule', 'leads:write'])

​
3. Monitoring and Alerting

Use for uptime monitoring and health checks:

#!/bin/bash
# health-check.sh - Simple monitoring script

RESPONSE=$(curl -s -w "%{http_code}" -H "x-api-key: $BUENA_API_KEY" \
  https://api.buena.ai/api/v2/health)

HTTP_CODE="${RESPONSE: -3}"
BODY="${RESPONSE%???}"

if [ "$HTTP_CODE" -eq 200 ]; then
  STATUS=$(echo "$BODY" | jq -r '.status')
  if [ "$STATUS" = "healthy" ]; then
    echo "✅ API is healthy"
    exit 0
  else
    echo "⚠️ API status: $STATUS"
    exit 1
  fi
else
  echo "❌ API health check failed: HTTP $HTTP_CODE"
  exit 2
fi

​
Error Responses

​
Invalid API Key (401)

{
  "error": true,
  "code": "UNAUTHORIZED",
  "message": "Invalid API key",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z"
}

​
Rate Limited (429)

{
  "error": true,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 30 seconds.",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z",
  "retryAfter": 30
}

​
Service Issues (5xx)

{
  "error": true,
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service temporarily unavailable",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z"
}

​
Status Indicators

The status field in the response can be:

StatusDescriptionAction
healthyAll systems operationalContinue normal operations
degradedPartial functionalityMonitor closely, some features may be slower
maintenanceScheduled maintenanceRetry after maintenance window

Pro Tip: Set up automated health checks in your monitoring system to detect API issues early. We recommend checking every 5-10 minutes for production applications.

​
Next Steps

Once your health check passes:

Create API Keys

Generate additional API keys for your team

Schedule LinkedIn Actions

Start automating LinkedIn outreach

Manage Leads

Work with your lead database

Check Rate Limits

Understand API usage limits