API Documentation

Integrate secure note sharing into your applications

Last Updated: June 7, 2026 API Version 1.2

Quick Start

Base URL: https://securenotes.net/api/

Format: JSON requests and responses

Security: HTTPS required, rate limiting enabled

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

https://securenotes.net/api/

2Authentication

The Secure Notes API requires no authentication. All requests are open and protected by IP-based rate limiting.

No API Keys Required

POST your request directly - no tokens, no setup. Rate limiting keeps things fair.

3Rate Limits

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

Action	Limit	Window	Status Code
Create Notes	10 requests	1 hour	429
View Notes	50 requests	1 hour	429
Statistics	20 requests	1 hour	429

Rate Limit Headers

When you hit a rate limit, you'll receive a 429 Too Many Requests response. Wait for the time window to reset before making additional requests.

4API Endpoints

Create Note

POST /api/create.php

Creates a new encrypted note with specified expiration and security settings.

Request Parameters

Parameter	Type	Required	Description
`content`	string	Required	The note content to encrypt (max 10,000 characters)
`expiry_type`	string	Optional	Expiry type: `view`, `time`, or `both` (default: `view`)
`expiry_time`	integer	Optional	Hours until expiry (1-8760, default: 24)
`max_views`	integer	Optional	Maximum view count (1-100, default: 1)
`passcode`	string	Optional	Optional passcode for additional security
`notification_email`	string	Optional	Email address to notify when the note is read
`send_link_email`	string	Optional	Email address to send the note link to immediately after creation

Example Request

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": "notify@example.com",
    "send_link_email": "recipient@example.com"
  }'

Success Response

{
  "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
}

View Note

GET /api/view/{uuid}.php

Retrieves metadata about a note without decrypting it. Actual note viewing happens through the web interface for security.

URL Parameters

Parameter	Type	Required	Description
`uuid`	string	Required	The unique identifier of the note

Example Request

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

Success Response

{
  "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"
  }
}

Statistics

GET /api/stats.php

Retrieves anonymized usage statistics and system health information.

Example Request

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

Success Response

{
  "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

Status Code	Meaning	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request parameters
`404`	Not Found	Note not found or destroyed
`405`	Method Not Allowed	HTTP method not supported
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

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
    })
  });

  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
    }

    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

<?php
function createNote($content, $options = [])
{
    $data = [
        'content'     => $content,
        'expiry_type' => $options['expiryType'] ?? 'view',
        'max_views'   => $options['maxViews'] ?? 1,
        'passcode'    => $options['passcode'] ?? null,
    ];
    $ch = curl_init('https://securenotes.net/api/create.php');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        throw new Exception('cURL Error: ' . curl_error($ch));
    }
    curl_close($ch);
    return json_decode($response, true);
}

// Usage
try {
    $note = createNote('My secret message', [
        'expiryType' => 'both',
        'maxViews'   => 1,
        'passcode'   => 'secret123'
    ]);
    echo 'Note URL: ' . $note['url'];
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
?>

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
  }'

# 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

7Changelog

Version 1.2.0 - June 7, 2026

Added send_link_email parameter — email the note link immediately after creation

Version 1.1.0 - May 29, 2026

Removed CSRF token requirement from the API
Updated code examples across all languages

Version 1.0.0 - May 5, 2026

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

Stay Updated

Follow our changelog to stay informed about new features, improvements, and breaking changes. We follow semantic versioning for all API updates.

8Support & Resources

Additional Resources

                            
                                Best Practices
                            
                            Always use HTTPS when making API calls
Implement proper error handling for all API responses
Respect rate limits to ensure consistent service
Never log sensitive data like note content or passcodes
Use appropriate expiry settings based on content sensitivity

This API documentation is designed to help you integrate Secure Notes into your applications securely and efficiently. If you have questions or suggestions, please don't hesitate to contact us.