API Documentation

1Introduction

The Secure Notes API allows you to programmatically create and manage encrypted, self-destructing notes. Our REST API is designed with security and simplicity in mind, following industry best practices.

Key Features

• Zero-Knowledge Architecture: API cannot read note contents
• End-to-End Encryption: Notes encrypted before reaching our servers
• RESTful Design: Predictable resource-oriented URLs
• JSON Format: All requests and responses use JSON
• Rate Limited: Built-in protection against abuse

API Base URL

2Authentication

Currently, the Secure Notes API uses CSRF token-based authentication for creating notes and IP-based rate limiting for security.

CSRF Protection

When creating notes through the web interface, a CSRF token is required:

{
  "csrf_token": "abc123def456...",
  "content": "Your encrypted content here"
}

3Rate Limits

To ensure fair usage and prevent abuse, we implement rate limiting based on IP address:

4API Endpoints

curl -X POST https://securenotes.net/api/create.php \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a secret message",
    "expiry_type": "both",
    "expiry_time": 24,
    "max_views": 1,
    "passcode": "secret123",
    "notification_email": "user@example.com",
    "csrf_token": "your-csrf-token"
  }'

{
  "success": true,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://securenotes.net/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2024-01-15 14:30:00",
  "max_views": 1,
  "has_passcode": true
}

curl -X GET https://securenotes.net/api/view/a1b2c3d4-e5f6-7890-abcd-ef1234567890.php

{
  "success": true,
  "note": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "has_passcode": true,
    "expiry_type": "both",
    "expires_at": "2024-01-15 14:30:00",
    "max_views": 1,
    "current_views": 0,
    "is_destroyed": false,
    "created_at": "2024-01-14 14:30:00"
  }
}

curl -X GET https://securenotes.net/api/stats.php

{
  "success": true,
  "stats": {
    "total_notes_created": 1542,
    "active_notes": 234,
    "destroyed_notes": 1308,
    "success_rate": 98.5,
    "notes_24h": 45,
    "notes_7d": 312,
    "notes_30d": 1205,
    "health_status": {
      "database": "healthy",
      "encryption": "available",
      "email": "configured"
    },
    "generated_at": "2024-01-14 14:30:00"
  }
}

5Error Handling

The API uses conventional HTTP response codes to indicate success or failure. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate client errors, and codes in the 5xx range indicate server errors.

HTTP Status Codes

Error Response Format

{
  "error": "Content is required",
  "code": "INVALID_CONTENT",
  "details": {
    "parameter": "content",
    "message": "Content cannot be empty"
  }
}

6Code Examples

JavaScript/Node.js

// Create a secure note
const createNote = async (content, options = {}) => {
  const response = await fetch('https://securenotes.net/api/create.php', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: content,
      expiry_type: options.expiryType || 'view',
      max_views: options.maxViews || 1,
      passcode: options.passcode,
      csrf_token: await getCSRFToken()
    })
  });
  
  return await response.json();
};

// Usage
const note = await createNote('My secret message', {
  expiryType: 'both',
  maxViews: 1,
  passcode: 'secret123'
});

console.log('Note URL:', note.url);

Python

import requests
import json

def create_secure_note(content, expiry_type='view', max_views=1, passcode=None):
    """Create a secure note using the SecureNotes API"""
    
    url = 'https://securenotes.net/api/create.php'
    
    payload = {
        'content': content,
        'expiry_type': expiry_type,
        'max_views': max_views,
        'csrf_token': get_csrf_token()  # You need to implement this
    }
    
    if passcode:
        payload['passcode'] = passcode
    
    response = requests.post(url, json=payload)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API Error: {response.status_code} - {response.text}")

# Usage
try:
    note = create_secure_note(
        content="My secret message",
        expiry_type="both",
        max_views=1,
        passcode="secret123"
    )
    print(f"Note URL: {note['url']}")
except Exception as e:
    print(f"Error: {e}")

PHP

Error: API Error: 0 - 

cURL

# Create a note
curl -X POST https://securenotes.net/api/create.php \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is my secret message",
    "expiry_type": "view",
    "max_views": 1,
    "csrf_token": "your-csrf-token-here"
  }'

# Get statistics
curl -X GET https://securenotes.net/api/stats.php

# Check note metadata
curl -X GET https://securenotes.net/api/view/your-note-uuid.php

7SDKs & Libraries

We're working on official SDKs for popular programming languages. Currently, you can use the HTTP API directly or create wrapper functions as shown in the examples above.

Community SDKs

8Webhooks

Webhooks allow your application to receive real-time notifications when certain events occur with your notes.

Planned Webhook Events

• note.accessed - When a note is successfully viewed
• note.failed_access - When someone tries to access a note with wrong passcode
• note.expired - When a note expires by time
• note.destroyed - When a note is destroyed after max views

Webhook Payload Example

{
  "event": "note.accessed",
  "timestamp": "2024-01-14T14:30:00Z",
  "data": {
    "note_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "access_details": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "access_time": "2024-01-14T14:30:00Z"
    }
  }
}

9Changelog

Version 1.0.0 - July 9, 2025

• Initial API release
• Note creation endpoint
• Note metadata retrieval
• Statistics endpoint
• Rate limiting implementation
• CSRF protection

10Support & Resources

Additional Resources

• Live API Statistics
• Privacy Policy
• Terms of Service
• Web Interface