Auric API Documentation

Overview

The Auric API provides programmatic access to event tracking, contact management, and data retrieval for your applications.

API Types

• Public Endpoints: For client-side tracking (CORS-protected)
• API Key Endpoints: For server-to-server integration

Response Format

All responses are in JSON format. Successful responses include version information:

{
  "status": "ok",
  "version": "v3.0.0",
  "unified_naming": true
}

Authentication

API Keys

Generate API keys in your Auric Settings panel:

1. Go to Settings → API Keys
2. Enter a descriptive name
3. Click "Create API Key"
4. Copy the key immediately (shown only once)

Using API Keys

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

CORS Authentication

For public endpoints, requests are authenticated by:

• Origin Header: Must match allowed origins
• Referer Header: Fallback authentication method

Configure allowed origins in Settings → Ingest → Allowed Origins.

Public Endpoints

These endpoints are designed for client-side JavaScript and are protected by CORS/origin checking.

{
  "event_type": "form_submit",
  "occurred_at": "2025-01-01T12:00:00Z",
  "email": "user@example.com",
  "page_url": "https://example.com/signup",
  "referrer": "https://google.com",
  "session_id": "abc123",
  "querystring": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "lead_source": "Google Ads"
  },
  "custom": {
    "plan": "pro",
    "trial_days": 14
  }
}

{
  "status": "ok",
  "version": "v3.0.0"
}

API Key Endpoints

Server-to-server endpoints requiring Bearer token authentication.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "email": "user@example.com",
  "event_type": "purchase",
  "occurred_at": "2025-01-01T12:00:00Z",
  "custom": {
    "amount": 99.00,
    "plan": "premium"
  }
}

{
  "events": [
    {
      "email": "user1@example.com",
      "event_type": "signup",
      "occurred_at": "2025-01-01T12:00:00Z"
    },
    {
      "email": "user2@example.com", 
      "event_type": "purchase",
      "occurred_at": "2025-01-01T13:00:00Z",
      "custom": {
        "amount": 49.00
      }
    }
  ]
}

{
  "created": 2,
  "errors": [],
  "version": "v3.0.0"
}

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "John Doe",
  "lead_source": "Google Ads",
  "custom": {
    "company": "Acme Corp",
    "role": "CEO"
  }
}

{
  "contacts": [
    {
      "email": "user1@example.com",
      "name": "Jane Smith",
      "lead_source": "Referral"
    },
    {
      "email": "user2@example.com",
      "name": "Bob Johnson", 
      "lead_source": "Social Media"
    }
  ]
}

{
  "upserted": 2,
  "errors": [],
  "version": "v3.0.0"
}

Unified Naming Convention

Auric v3.0.0 uses a unified naming scheme across all endpoints while maintaining backward compatibility.

Field Name Mapping

Priority Order

When multiple field names are provided, the API uses this priority order:

1. New unified names (highest priority)
2. Common legacy names
3. Alternative legacy names
4. Default values (lowest priority)

Error Handling

The API uses standard HTTP status codes and provides detailed error information.

HTTP Status Codes

• 200 OK: Successful request
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing authentication
• 403 Forbidden: Origin not allowed or access denied
• 404 Not Found: Endpoint or resource not found
• 422 Unprocessable Entity: Valid format but business logic error
• 500 Internal Server Error: Server error

Error Response Format

{
  "error": "validation_failed",
  "detail": "Event type 'invalid_type' does not exist",
  "version": "v3.0.0"
}

Bulk Operation Errors

For endpoints that process multiple items, partial success is supported:

{
  "created": 2,
  "errors": [
    {
      "index": 1,
      "error": "Invalid email format"
    }
  ],
  "version": "v3.0.0"
}

Rate Limits

API endpoints have the following rate limits to ensure fair usage:

Rate Limit Headers

Response headers provide rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Code Examples

JavaScript (Client-side)

// Public endpoint - no API key needed
fetch('https://your-app-id.auriccloud.com/i', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type: 'form_submit',
    email: 'user@example.com',
    occurred_at: new Date().toISOString(),
    custom: {
      form_id: 'newsletter-signup',
      page: 'homepage'
    }
  })
})
.then(response => response.json())
.then(data => console.log('Event tracked:', data));

Node.js (Server-side)

const axios = require('axios');

async function createEvent(apiKey, eventData) {
  try {
    const response = await axios.post(
      'https://your-app-id.auriccloud.com/api/events',
      eventData,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
createEvent('your-api-key', {
  email: 'user@example.com',
  event_type: 'purchase',
  occurred_at: new Date().toISOString(),
  custom: {
    amount: 99.00,
    currency: 'USD'
  }
});

Python

import requests
import json
from datetime import datetime

def create_event(api_key, event_data):
    url = 'https://your-app-id.auriccloud.com/api/events'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, headers=headers, json=event_data)
    response.raise_for_status()
    return response.json()

# Usage
event_data = {
    'email': 'user@example.com',
    'event_type': 'signup',
    'occurred_at': datetime.utcnow().isoformat() + 'Z',
    'custom': {
        'plan': 'premium',
        'source': 'organic'
    }
}

result = create_event('your-api-key', event_data)
print(f"Event created: {result}")

PHP

 'user@example.com',
    'event_type' => 'download',
    'occurred_at' => date('c'),
    'custom' => [
        'file_type' => 'pdf',
        'file_name' => 'user-guide.pdf'
    ]
];

$result = createEvent('your-api-key', $eventData);
?>

cURL

# Public endpoint
curl -X POST "https://your-app-id.auriccloud.com/i" \
  -H "Content-Type: application/json" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "event_type": "form_submit",
    "email": "user@example.com",
    "occurred_at": "2025-01-01T12:00:00Z",
    "custom": {"form_id": "contact"}
  }'

# API endpoint
curl -X POST "https://your-app-id.auriccloud.com/api/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event_type": "purchase",
    "occurred_at": "2025-01-01T12:00:00Z",
    "custom": {"amount": 99.00}
  }'