Events API

Complete reference for the Deepns Events API.

Overview

The Events API allows you to send custom events from your server or application to Deepns.

Base URL: https://api.deepns.com

Endpoints

Create Event

Send a new event to Deepns.

Endpoint: POST /events

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body:

{
  "event": "purchase",
  "visitor_id": "visitor_abc123",
  "properties": {
    "amount": 99.99,
    "currency": "USD",
    "product": "Premium Plan"
  },
  "timestamp": "2026-03-20T10:30:00Z"
}

Parameters:

Parameter Type Required Description
event string Yes Event name (alphanumeric, underscores)
visitor_id string No Unique visitor identifier
properties object No Custom event properties
timestamp string No ISO 8601 timestamp (defaults to now)

Response (201 Created):

{
  "id": "evt_123456",
  "event": "purchase",
  "status": "accepted",
  "timestamp": "2026-03-20T10:30:00Z"
}

Batch Events

Send multiple events in a single request.

Endpoint: POST /events/batch

Request Body:

{
  "events": [
    {
      "event": "page_view",
      "visitor_id": "visitor_abc123",
      "properties": {
        "page": "/pricing"
      }
    },
    {
      "event": "button_click",
      "visitor_id": "visitor_abc123",
      "properties": {
        "button": "signup"
      }
    }
  ]
}

Response (201 Created):

{
  "accepted": 2,
  "rejected": 0,
  "results": [
    {
      "id": "evt_123456",
      "status": "accepted"
    },
    {
      "id": "evt_123457",
      "status": "accepted"
    }
  ]
}

Get Event

Retrieve details about a specific event.

Endpoint: GET /events/:id

Response (200 OK):

{
  "id": "evt_123456",
  "event": "purchase",
  "visitor_id": "visitor_abc123",
  "properties": {
    "amount": 99.99,
    "currency": "USD",
    "product": "Premium Plan"
  },
  "timestamp": "2026-03-20T10:30:00Z",
  "created_at": "2026-03-20T10:30:01Z"
}

List Events

Retrieve a list of events.

Endpoint: GET /events

Query Parameters:

Parameter Type Description
limit integer Number of results (1-100, default: 20)
offset integer Pagination offset (default: 0)
event string Filter by event name
visitor_id string Filter by visitor ID
from string Start date (ISO 8601)
to string End date (ISO 8601)

Example Request:

curl "https://api.deepns.com/events?event=purchase&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK):

{
  "data": [
    {
      "id": "evt_123456",
      "event": "purchase",
      "visitor_id": "visitor_abc123",
      "timestamp": "2026-03-20T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const trackEvent = async () => {
  try {
    const response = await axios.post(
      'https://api.deepns.com/events',
      {
        event: 'signup',
        visitor_id: 'user_123',
        properties: {
          plan: 'premium',
          source: 'homepage'
        }
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.DEEPNS_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Event tracked:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

Python

import requests
import os

api_key = os.getenv('DEEPNS_API_KEY')

response = requests.post(
    'https://api.deepns.com/events',
    json={
        'event': 'signup',
        'visitor_id': 'user_123',
        'properties': {
            'plan': 'premium',
            'source': 'homepage'
        }
    },
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Ruby

require 'httparty'

response = HTTParty.post(
  'https://api.deepns.com/events',
  body: {
    event: 'signup',
    visitor_id: 'user_123',
    properties: {
      plan: 'premium',
      source: 'homepage'
    }
  }.to_json,
  headers: {
    'Authorization' => "Bearer #{ENV['DEEPNS_API_KEY']}",
    'Content-Type' => 'application/json'
  }
)

puts response.body

PHP

<?php
$api_key = getenv('DEEPNS_API_KEY');

$data = [
    'event' => 'signup',
    'visitor_id' => 'user_123',
    'properties' => [
        'plan' => 'premium',
        'source' => 'homepage'
    ]
];

$ch = curl_init('https://api.deepns.com/events');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Error Responses

400 Bad Request

Invalid request data:

{
  "error": "bad_request",
  "message": "Invalid event name",
  "details": {
    "event": "Event name must be alphanumeric with underscores only"
  }
}

401 Unauthorized

Missing or invalid authentication:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

404 Not Found

Resource not found:

{
  "error": "not_found",
  "message": "Event not found"
}

422 Unprocessable Entity

Validation errors:

{
  "error": "validation_error",
  "message": "Validation failed",
  "details": {
    "properties.amount": "Must be a positive number"
  }
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

Best Practices

  1. Use batch endpoints for multiple events
  2. Include timestamps for accurate historical tracking
  3. Handle errors gracefully with retry logic
  4. Cache visitor IDs for consistent tracking
  5. Validate data before sending to API

Next Steps

Documentation