Complete API Documentation and Integration Guide

The Selgora API opens up endless possibilities for automation, integration, and custom development. Whether you're connecting external tools, building custom apps, or automating workflows, this guide provides everything you need.

API Fundamentals

Base URL and Versioning

Production: https://api.selgora.com/v1
Staging: https://staging-api.selgora.com/v1

Current Version: v1 Version Header: Accept: application/vnd.selgora.v1+json

Authentication

Selgora uses API key authentication with Bearer tokens:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.selgora.com/v1/courses

Getting Your API Key

1. Navigate to Settings → API
2. Click Generate New Key
3. Name your key (e.g., "Production App")
4. Set permissions
5. Copy immediately (shown only once)

API Key Security

DO:

• Store in environment variables
• Use different keys for different environments
• Rotate keys regularly
• Restrict permissions minimally

DON'T:

• Commit keys to version control
• Share keys across projects
• Use production keys in development
• Expose keys in client-side code

Rate Limiting

Protect system stability with rate limits:

Default Limits:

• 1000 requests per hour
• 100 requests per minute
• 10 concurrent requests

Headers Returned:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Rate Limit Response:

{
  "error": "Rate limit exceeded",
  "retry_after": 3600
}

Core Resources

Courses

List Courses

GET /v1/courses

Response:

{
  "data": [
    {
      "id": "course_abc123",
      "title": "Digital Marketing Mastery",
      "slug": "digital-marketing-mastery",
      "price": 497,
      "currency": "USD",
      "enrolled_count": 1250,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 45
  }
}

Get Single Course

GET /v1/courses/{id}

Create Course

POST /v1/courses
Content-Type: application/json

{
  "title": "New Course Title",
  "description": "Course description",
  "price": 297,
  "currency": "USD"
}

Update Course

PATCH /v1/courses/{id}

Delete Course

DELETE /v1/courses/{id}

Students/Enrollments

List Enrollments

GET /v1/enrollments?course_id=course_abc123

Enroll Student

POST /v1/enrollments

{
  "course_id": "course_abc123",
  "user_email": "student@example.com",
  "notify": true
}

Get Progress

GET /v1/enrollments/{id}/progress

Response:

{
  "enrollment_id": "enr_xyz789",
  "progress_percentage": 67,
  "lessons_completed": 12,
  "total_lessons": 18,
  "last_activity": "2024-03-21T09:15:00Z",
  "completion_estimated": "2024-04-15T00:00:00Z"
}

Contacts

List Contacts

GET /v1/contacts?tag=premium&limit=50

Create/Update Contact

POST /v1/contacts

{
  "email": "contact@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "tags": ["premium", "webinar-attended"],
  "custom_fields": {
    "company": "Acme Corp",
    "role": "CEO"
  }
}

Add Tags

POST /v1/contacts/{id}/tags

{
  "tags": ["new-tag-1", "new-tag-2"]
}

Events

List Events

GET /v1/events?status=upcoming

Create Event

POST /v1/events

{
  "title": "Weekly Office Hours",
  "start_time": "2024-03-25T14:00:00Z",
  "duration_minutes": 60,
  "recurring": {
    "frequency": "weekly",
    "count": 12
  }
}

Register Attendee

POST /v1/events/{id}/registrations

{
  "email": "attendee@example.com",
  "name": "Jane Smith"
}

Webhooks

Setting Up Webhooks

Configure webhooks in dashboard or via API:

POST /v1/webhooks

{
  "url": "https://your-app.com/webhooks/selgora",
  "events": [
    "enrollment.created",
    "payment.completed",
    "course.completed"
  ],
  "secret": "your_webhook_secret"
}

Webhook Events

Available events to subscribe to:

Course Events:

• course.created
• course.updated
• course.deleted
• course.published

Enrollment Events:

• enrollment.created
• enrollment.completed
• enrollment.cancelled

Payment Events:

• payment.completed
• payment.failed
• payment.refunded

Contact Events:

• contact.created
• contact.updated
• contact.unsubscribed

Webhook Payload

Example webhook payload:

{
  "id": "evt_abc123",
  "type": "enrollment.created",
  "created_at": "2024-03-21T10:30:00Z",
  "data": {
    "enrollment": {
      "id": "enr_xyz789",
      "course_id": "course_abc123",
      "user_email": "student@example.com",
      "created_at": "2024-03-21T10:29:55Z"
    }
  }
}

Webhook Security

Verify webhook signatures:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# In your webhook handler
signature = request.headers.get('X-Selgora-Signature')
if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
    return 401  # Unauthorized

Advanced Integration Patterns

Pagination

Handle large datasets efficiently:

def get_all_courses():
    courses = []
    page = 1

    while True:
        response = requests.get(
            f"{BASE_URL}/courses?page={page}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )

        data = response.json()
        courses.extend(data['data'])

        if page >= data['meta']['total_pages']:
            break

        page += 1

    return courses

Batch Operations

Process multiple items efficiently:

def batch_enroll(course_id, emails):
    batch_size = 50

    for i in range(0, len(emails), batch_size):
        batch = emails[i:i+batch_size]

        response = requests.post(
            f"{BASE_URL}/enrollments/batch",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={
                "course_id": course_id,
                "emails": batch
            }
        )

        if response.status_code != 200:
            handle_error(response)

Error Handling

Implement robust error handling:

class SelgoraAPI {
  async request(endpoint, options = {}) {
    const maxRetries = 3;
    let lastError;

    for (let i = 0; i < maxRetries; i++) {
      try {
        const response = await fetch(`${BASE_URL}${endpoint}`, {
          ...options,
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json',
            ...options.headers
          }
        });

        if (response.status === 429) {
          // Rate limited - wait and retry
          const retryAfter = response.headers.get('Retry-After') || 60;
          await new Promise(r => setTimeout(r, retryAfter * 1000));
          continue;
        }

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

        return await response.json();

      } catch (error) {
        lastError = error;

        if (i < maxRetries - 1) {
          // Exponential backoff
          await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
        }
      }
    }

    throw lastError;
  }
}

SDK Examples

JavaScript/Node.js

// Install: npm install @selgora/sdk

const Selgora = require('@selgora/sdk');

const client = new Selgora({
  apiKey: process.env.SELGORA_API_KEY
});

// List courses
const courses = await client.courses.list();

// Create enrollment
const enrollment = await client.enrollments.create({
  courseId: 'course_abc123',
  email: 'student@example.com'
});

// Handle webhooks
client.webhooks.on('enrollment.created', (data) => {
  console.log('New enrollment:', data);
});

Python

# Install: pip install selgora

from selgora import Client

client = Client(api_key=os.environ['SELGORA_API_KEY'])

# List courses
courses = client.courses.list()

# Create enrollment
enrollment = client.enrollments.create(
    course_id='course_abc123',
    email='student@example.com'
)

# Webhook handler
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = client.webhooks.verify(
        request.data,
        request.headers.get('X-Selgora-Signature')
    )

    if event.type == 'enrollment.created':
        process_new_enrollment(event.data)

    return '', 200

PHP

// Install: composer require selgora/selgora-php

use Selgora\Client;

$client = new Client($_ENV['SELGORA_API_KEY']);

// List courses
$courses = $client->courses->all();

// Create enrollment
$enrollment = $client->enrollments->create([
    'course_id' => 'course_abc123',
    'email' => 'student@example.com'
]);

// Webhook handler
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SELGORA_SIGNATURE'];

if ($client->webhooks->verify($payload, $signature)) {
    $event = json_decode($payload);

    switch($event->type) {
        case 'enrollment.created':
            processNewEnrollment($event->data);
            break;
    }
}

Common Integration Scenarios

Zapier Integration

Connect Selgora to 5000+ apps:

1. Trigger: New enrollment in Selgora
2. Action: Add row to Google Sheets
3. Action: Send Slack notification
4. Action: Create task in Asana

CRM Sync

Keep your CRM updated:

def sync_to_crm(contact):
    # Map Selgora fields to CRM fields
    crm_contact = {
        'email': contact['email'],
        'firstName': contact['first_name'],
        'lastName': contact['last_name'],
        'customFields': {
            'selgora_id': contact['id'],
            'total_purchases': contact['lifetime_value'],
            'last_activity': contact['last_activity']
        }
    }

    # Update or create in CRM
    crm_api.upsert(crm_contact)

Analytics Pipeline

Stream data to your warehouse:

// Stream events to analytics
client.on('event', async (event) => {
  await analytics.track({
    userId: event.user_id,
    event: event.type,
    properties: event.data,
    timestamp: event.created_at
  });
});

Testing

Sandbox Environment

Test without affecting production:

Sandbox URL: https://sandbox-api.selgora.com/v1
Test API Key: test_key_...

Test Data

Sandbox includes test data:

• 100 sample courses
• 1000 test contacts
• Various enrollment states
• Sample webhook events

Integration Testing

import pytest
from selgora import Client

@pytest.fixture
def client():
    return Client(api_key='test_key_123')

def test_create_enrollment(client):
    enrollment = client.enrollments.create(
        course_id='test_course_123',
        email='test@example.com'
    )

    assert enrollment.id is not None
    assert enrollment.status == 'active'

Performance Optimization

Caching Strategies

from functools import lru_cache
from datetime import datetime, timedelta

@lru_cache(maxsize=100)
def get_course(course_id):
    return client.courses.get(course_id)

# Clear cache periodically
def clear_old_cache():
    get_course.cache_clear()

Connection Pooling

import requests
from requests.adapters import HTTPAdapter

session = requests.Session()
adapter = HTTPAdapter(
    pool_connections=10,
    pool_maxsize=10,
    max_retries=3
)
session.mount('https://', adapter)

Troubleshooting

Common Issues

401 Unauthorized

• Check API key validity
• Verify key permissions
• Ensure correct environment

429 Too Many Requests

• Implement rate limiting
• Use exponential backoff
• Consider batch operations

500 Internal Server Error

• Retry with backoff
• Check status page
• Contact support if persistent

Debug Mode

Enable detailed logging:

client = Client(
    api_key=API_KEY,
    debug=True,
    log_level='DEBUG'
)

Remember This

The API is a powerful tool, but with great power comes great responsibility. Always handle user data securely, respect rate limits, and build resilient integrations.

Start simple. Get one integration working end-to-end before building complex workflows.

Test thoroughly. Your integration is only as reliable as its weakest link.

The API documentation is living - check for updates regularly and subscribe to changelog notifications.

Your integration can transform how creators use Selgora. Build something amazing!