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 Your API key for authentication
curl -X GET "https://api.buena.ai/api/v2/health" \ -H "x-api-key: YOUR_API_KEY"
Response Current API version (e.g., “2.0”)
API health status (“healthy” or “degraded”)
Authentication type (“user” for valid API key)
Information about the authenticated user User’s subscription role (e.g., “Premium”, “Basic”)
Information about the API key used Human-readable name of the API key
List of permissions granted to this API key
Total number of requests made with this key
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:
Status Description Action healthyAll systems operational Continue normal operations degradedPartial functionality Monitor closely, some features may be slower maintenanceScheduled maintenance Retry 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:
