API Documentation

Professional, secure, and easy-to-use API for SecureNote.link

Overview

Welcome to the SecureNote.link API documentation. This API allows you to create, retrieve, and manage secure, one-time notes with optional password protection and expiration. All endpoints are HTTPS only and require Content-Type: application/json for requests with a body.

🌐 Base URL: https://your-domain.com 🛡️ Version: v1

Quick Navigation

Authentication & Rate Limiting

  • No authentication required for standard endpoints.
  • General API: 100 requests / 15 min
  • Password verification: 10 requests / 15 min
  • All requests must use HTTPS

Description

Create a new encrypted secret with optional password protection and expiration.

Request Body 
{
  "encryptedData": "string (required)",
  "iv": "string (required)",
  "password": "string (optional)",
  "expiresIn": "number (optional, hours: 1, 24, 72, 168)"
}
Response 
{
  "id": "string",
  "passwordProtected": true,
  "expiresIn": 24
}
Rate Limit 100 requests per 15 minutes

Code Examples

// JavaScript fetch example
fetch('/api/v1/secrets', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    encryptedData: '...',
    iv: '...',
    password: 'optional',
    expiresIn: 24
  })
})
# Curl example
curl -X POST https://your-domain.com/api/v1/secrets \
  -H "Content-Type: application/json" \
  -d '{"encryptedData":"...","iv":"..."}'

Description

Retrieve a secret (marks it as accessed). Secret is deleted after retrieval if no password.

ParametersID (32-character hex string)
Response 
{
  "content": {
    "encryptedData": "string",
    "iv": "string"
  },
  "passwordProtected": false
}
NotesSecret is deleted after retrieval if no password

Code Examples

// JavaScript fetch example
fetch('/api/v1/secrets/your-secret-id')
  .then(res => res.json())
  .then(data => console.log(data));
# Curl example
curl https://your-domain.com/api/v1/secrets/your-secret-id

Description

Verify the password for a secret without revealing it.

Request Body 
{
  "password": "string (required)"
}
Response 
{
  "valid": true
}
Rate Limit 10 requests per 15 minutes

Code Examples

// JavaScript fetch example
fetch('/api/v1/secrets/your-secret-id/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ password: 'yourpassword' })
}).then(res => res.json()).then(data => console.log(data));
# Curl example
curl -X POST https://your-domain.com/api/v1/secrets/your-secret-id/verify \
  -H "Content-Type: application/json" \
  -d '{"password":"yourpassword"}'

Description

Check the API service health status.

Response{"status":"ok"}

Code Examples

// JavaScript fetch example
fetch('/api/v1/health')
  .then(res => res.json())
  .then(data => console.log(data));
# Curl example
curl https://your-domain.com/api/v1/health

Description

Returns administrative status and statistics.

Response{"activeSecrets":123,"uptime":"72h"}

Description

Trigger a purge of expired secrets.

Response{"purged": 42}

Error Codes

  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Authentication failed
  • 403: Forbidden - Access denied
  • 404: Not Found - Secret not found
  • 410: Gone - Secret expired
  • 429: Too Many Requests - Rate limit exceeded
  • 500: Internal Server Error - Server error

Security Features

  • Encrypted data stored securely.
  • One-time access for secrets without passwords.
  • Optional password protection with verification.
  • Automatic expiration of secrets.
  • HTTPS enforced for all API calls.