Skip to main content

Torvus Security Platform API Changelog

All notable changes to the Torvus Security Platform API will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

API Base URL: https://api.torvussecurity.com

Unreleased​

Changes that are in development but not yet released.

Added​

  • Enhanced monitoring and observability infrastructure
  • Usage analytics tracking for API consumption patterns
  • Geographic distribution insights (planned)

Changed​

  • None

Deprecated​

  • None

Removed​

  • None

Fixed​

  • None

Security​

  • Enhanced rate limiting protection
  • Improved error handling and logging

1.0.0 - 2025-10-01​

🎉 Initial Public Release - Torvus Security Platform API v1

Added​

Core Endpoints​

  • Health Check (GET /v1/health)

    • Basic API health status
    • No authentication required
    • Response includes version and status

  • Authentication (POST /v1/auth/whoami)

    • API key validation
    • Returns key metadata and permissions
    • Requires valid API key

Vault Management​

  • List Vaults (GET /v1/vaults)

    • Retrieve all vaults accessible to the API key
    • Supports pagination via limit and offset parameters
    • Returns vault metadata including status and creation date

  • Create Vault (POST /v1/vaults)

    • Create new estate planning vault
    • Requires: name, owner_email, optional metadata
    • Returns created vault with ID and status

  • Get Vault (GET /v1/vaults/{id})

    • Retrieve specific vault by ID
    • Requires: Vault must be accessible to the API key owner
    • Returns complete vault details

  • Update Vault (PUT /v1/vaults/{id})

    • Update vault metadata
    • Supports: name, status, settings updates
    • Returns updated vault object

  • Delete Vault (DELETE /v1/vaults/{id})

    • Soft-delete vault (status → inactive)
    • Requires: Owner or admin permissions
    • Returns 204 No Content on success

Document Management​

  • List Documents (GET /v1/documents)

    • Retrieve documents for a vault
    • Query parameter: vault_id (required)
    • Supports pagination and filtering by document type

  • Upload Document (POST /v1/documents)

    • Upload estate planning documents
    • Supports: PDF, DOCX, images (PNG, JPG)
    • Max file size: 25MB
    • Returns document metadata and storage URL

  • Get Document (GET /v1/documents/{id})

    • Retrieve document metadata
    • Does not return file content (use download endpoint)

  • Download Document (GET /v1/documents/{id}/download)

    • Download document file content
    • Returns pre-signed URL (expires in 1 hour)
    • Requires: Read access to parent vault

  • Delete Document (DELETE /v1/documents/{id})

    • Permanently delete document
    • Requires: Owner or admin permissions
    • Returns 204 No Content

Recipient Management​

  • List Recipients (GET /v1/recipients)

    • Retrieve recipients for a vault
    • Query parameter: vault_id (required)
    • Returns recipient metadata and contact info

  • Add Recipient (POST /v1/recipients)

    • Add beneficiary or executor to vault
    • Requires: name, email, relationship type
    • Sends notification email to recipient

  • Update Recipient (PUT /v1/recipients/{id})

    • Update recipient information
    • Supports: contact info, notification preferences

  • Remove Recipient (DELETE /v1/recipients/{id})

    • Remove recipient from vault
    • Returns 204 No Content

Crypto Account Management​

  • List Crypto Accounts (GET /v1/crypto-accounts)

    • Retrieve cryptocurrency accounts for a vault
    • Query parameter: vault_id (required)

  • Add Crypto Account (POST /v1/crypto-accounts)

    • Add cryptocurrency wallet or account
    • Supports: BTC, ETH, and other major cryptocurrencies
    • Stores encrypted wallet information

  • Get Crypto Account (GET /v1/crypto-accounts/{id})

    • Retrieve specific crypto account details

  • Update Crypto Account (PUT /v1/crypto-accounts/{id})

    • Update crypto account metadata

  • Delete Crypto Account (DELETE /v1/crypto-accounts/{id})

    • Remove crypto account from vault

Authentication & Authorization​

API Key Authentication​

  • Bearer token authentication via Authorization header
  • Format: Authorization: Bearer your_api_key_here
  • Keys are scoped to specific tiers with different rate limits

API Tiers​

  • Free Tier: 1,000 requests/day, read-only access
  • Professional Tier: 10,000 requests/day, full CRUD access
  • Enterprise Tier: 100,000 requests/day, priority support, custom limits

Rate Limiting​

  • Free Tier: 60 requests/minute, 1,000 requests/day
  • Professional Tier: 600 requests/minute, 10,000 requests/day
  • Enterprise Tier: 6,000 requests/minute, 100,000 requests/day

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1633024800

Rate Limit Exceeded Response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 42 seconds.",
    "retry_after": 42
  }
}

Error Handling​

Standard Error Response Format​

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}

HTTP Status Codes​

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded, no response body
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., duplicate)
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error (we log these)
  • 503 Service Unavailable - Temporary service disruption

Pagination​

All list endpoints support pagination:

Query Parameters:

  • limit (default: 20, max: 100) - Number of results per page
  • offset (default: 0) - Number of results to skip

Response Format:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 156,
    "has_more": true
  }
}

Webhooks​

Webhooks notify your application of events in real-time:

Supported Events:

  • vault.created
  • vault.updated
  • document.uploaded
  • recipient.added
  • crypto_account.added

Webhook Payload:

{
  "event": "vault.created",
  "timestamp": "2025-10-01T12:00:00Z",
  "data": {
    "vault_id": "vault_abc123",
    "owner_email": "user@example.com"
  }
}

Webhook Security:

  • HMAC-SHA256 signature in X-Torvus-Signature header
  • Verify signature to prevent spoofing

Versioning​

  • Current Version: v1
  • Version in URL: /v1/endpoint
  • Deprecation Policy: 6 months notice before removing deprecated endpoints
  • Sunset Header: Sunset: Sat, 31 Mar 2026 23:59:59 GMT

Data Formats​

  • Request Content-Type: application/json
  • Response Content-Type: application/json
  • Date Format: ISO 8601 (2025-10-01T12:00:00Z)
  • Timezone: UTC

Security​

  • Transport Security: TLS 1.2+ required
  • API Keys: Encrypted at rest, hashed for validation
  • Data Encryption: AES-256 for sensitive data
  • IP Whitelisting: Available for Enterprise tier
  • Audit Logging: All API requests logged for security audits

0.9.0 - 2025-09-15​

Added​

  • Beta release for select partners
  • All core endpoints functional
  • Rate limiting implemented
  • Basic documentation available

Changed​

  • Improved error messages for validation failures
  • Enhanced rate limit headers

Fixed​

  • Document upload timeout issues for large files
  • Pagination bugs in list endpoints

0.8.0 - 2025-09-01​

Added​

  • Private beta release
  • Initial API endpoints (vaults, documents, recipients)
  • Authentication via API keys
  • Rate limiting framework

Known Issues​

  • Document upload fails for files >10MB (fixed in v0.9.0)
  • Rate limit reset time calculation incorrect (fixed in v0.9.0)

Migration Guides​

From v0.9 to v1.0​

Breaking Changes: None! v1.0 is fully backward compatible with v0.9.

New Features:

  • Crypto account endpoints
  • Enhanced webhook events
  • Improved error responses

Recommended Actions:

  1. Update error handling to use new error format
  2. Implement webhook signature verification
  3. Update to latest SDK versions

Deprecation Schedule​

Planned Deprecations​

None currently planned.

Deprecated (with removal dates)​

None currently.

API Support​

Documentation: https://developers.torvussecurity.com Support Email: api-support@torvussecurity.com Status Page: https://status.torvussecurity.com Community: https://community.torvussecurity.com

Changelog Metadata​

Last Updated: 2025-10-15 Maintained By: Torvus Security Engineering Team Changelog Format: Keep a Changelog 1.0.0 Versioning: Semantic Versioning 2.0.0

How to Stay Updated​

  1. Watch This Repository: Get notified of changes via GitHub
  2. Subscribe to Newsletter: API updates sent monthly
  3. Follow Status Page: https://status.torvussecurity.com
  4. Join Community: https://community.torvussecurity.com

Contributing to Changelog​

Internal team members: See docs-internal/development/changelog-guidelines.md for instructions on updating this changelog.

Note: This changelog documents changes to the public API only. Internal API changes are tracked separately in docs-internal/api/CHANGELOG-INTERNAL.md.