API Documentation

Introduction

Welcome to the VisiSocial API documentation. Our API allows you to programmatically access personality analysis, user insights, and data export features. All endpoints use REST principles and return JSON responses.

Quick Start

Authentication

All API requests require authentication using an access token. Include your token in the Authorization header of each request.

Getting Your API Token

You can generate an API token from your dashboard settings. Navigate to Settings → API → Generate New Token.

GET /api/profile HTTP/1.1
Host: api.visisocial.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Rate Limits

API requests are rate limited to ensure fair usage and system stability. Current rate limits:

Rate Limit Headers

Each response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1704067200

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

Error Response Format

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Authentication required",
  "details": {
    "timestamp": "2026-01-01T12:00:00Z",
    "path": "/api/profile"
  }
}

Common Error Codes

User Profile

Retrieve and update user profile information.

{
  "success": true,
  "user": {
    "id": "12345678",
    "name": "John Doe",
    "email": "john@example.com",
    "picture": "https://...",
    "gender": "male",
    "location": "San Francisco, CA",
    "createdAt": "2025-01-01T00:00:00Z",
    "lastUpdated": "2026-01-01T12:00:00Z"
  }
}

{
  "displayName": "John D.",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Personality Analysis

Access personality analysis results and trigger new analyses.

{
  "success": true,
  "personality": {
    "scores": {
      "openness": 75,
      "conscientiousness": 68,
      "extroversion": 82,
      "agreeableness": 71,
      "neuroticism": 45,
      "confidence": 87
    },
    "description": "You tend to be outgoing and social...",
    "lastUpdated": "2026-01-01T12:00:00Z"
  }
}

{
  "success": true,
  "taskId": "task_abc123",
  "message": "Analysis started"
}

Insights & Recommendations

Access AI-generated insights and personalized recommendations.

{
  "success": true,
  "insights": {
    "personality": [
      {
        "title": "Social Energy",
        "description": "You draw energy from social interactions..."
      }
    ],
    "recommendations": [
      {
        "title": "Explore Team Activities",
        "description": "Based on your extroversion score..."
      }
    ],
    "trends": []
  }
}

Data Export

Export user data in various formats.

SDKs & Libraries

Official SDKs and community libraries to simplify API integration.

Code Examples

JavaScript / Node.js

const axios = require('axios');

const API_TOKEN = 'your_api_token';
const BASE_URL = 'https://api.visisocial.com/v2';

async function getProfile() {
  try {
    const response = await axios.get(`${BASE_URL}/api/profile`, {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('User Profile:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getProfile();

Python

import requests

API_TOKEN = 'your_api_token'
BASE_URL = 'https://api.visisocial.com/v2'

def get_profile():
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(f'{BASE_URL}/api/profile', headers=headers)
    
    if response.status_code == 200:
        print('User Profile:', response.json())
        return response.json()
    else:
        print('Error:', response.json())
        return None

get_profile()

cURL

curl -X GET https://api.visisocial.com/v2/api/profile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Changelog

Version 2.0.0 (2026-01-01)

• Added: New insights endpoint with AI-generated recommendations
• Improved: Enhanced personality analysis accuracy
• Changed: Updated rate limits for analysis endpoints
• Deprecated: Legacy v1 endpoints (sunset date: 2026-06-01)