Vaults API

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

The Vaults API allows you to programmatically create, manage, and delete vaults. All endpoints require authentication via API key or access token.

List All Vaults

GET /vaults

Retrieve a paginated list of all vaults you own or have access to.

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 20, max: 100)
`sort`	string	No	Sort field: `created_at`, `updated_at`, `name` (default: `created_at`)
`order`	string	No	Sort order: `asc`, `desc` (default: `desc`)
`status`	string	No	Filter by status: `active`, `released`, `archived`

Example Request

curl -X GET https://api.torvussecurity.com/v1/vaults?page=1&per_page=20 \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "data": [
    {
      "id": "vault_abc123xyz",
      "name": "Digital Legacy Vault",
      "description": "Important documents for family",
      "status": "active",
      "created_at": "2025-10-01T10:00:00Z",
      "updated_at": "2025-10-07T15:30:00Z",
      "released_at": null,
      "document_count": 12,
      "recipient_count": 3,
      "policy": {
        "type": "inactivity",
        "frequency": "monthly",
        "grace_period_days": 14
      },
      "owner": {
        "id": "user_def456ghi",
        "email": "user@example.com"
      }
    },
    {
      "id": "vault_xyz789abc",
      "name": "Journalism Evidence",
      "description": "Investigation materials",
      "status": "active",
      "created_at": "2025-09-15T08:00:00Z",
      "updated_at": "2025-10-08T09:00:00Z",
      "released_at": null,
      "document_count": 24,
      "recipient_count": 2,
      "policy": {
        "type": "manual",
        "backup_policy": "inactivity"
      },
      "owner": {
        "id": "user_def456ghi",
        "email": "user@example.com"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

Error Responses

Status Code	Error	Description
401	Unauthorized	Missing or invalid API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Get Vault by ID

GET /vaults/{vault_id}

Retrieve detailed information about a specific vault.

Request

Path Parameters:

Parameter	Type	Required	Description
`vault_id`	string	Yes	Unique vault identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example Request

curl -X GET https://api.torvussecurity.com/v1/vaults/vault_abc123xyz \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "id": "vault_abc123xyz",
  "name": "Digital Legacy Vault",
  "description": "Important documents for family",
  "status": "active",
  "created_at": "2025-10-01T10:00:00Z",
  "updated_at": "2025-10-07T15:30:00Z",
  "released_at": null,
  "document_count": 12,
  "recipient_count": 3,
  "policy": {
    "type": "inactivity",
    "frequency": "monthly",
    "grace_period_days": 14,
    "next_checkin_due": "2025-11-01T10:00:00Z",
    "last_checkin": "2025-10-01T10:00:00Z"
  },
  "settings": {
    "notifications_enabled": true,
    "auto_renew": true,
    "encryption_enabled": true
  },
  "owner": {
    "id": "user_def456ghi",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "metadata": {
    "size_bytes": 125829120,
    "last_accessed": "2025-10-07T15:30:00Z"
  }
}

Error Responses

Status Code	Error	Description
401	Unauthorized	Missing or invalid API key
403	Forbidden	You don't have access to this vault
404	Not Found	Vault not found
429	Too Many Requests	Rate limit exceeded

Create Vault

POST /vaults

Create a new vault.

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Vault name (max 100 characters)
`description`	string	No	Vault description (max 500 characters)
`policy_type`	string	No	Policy type: `manual`, `inactivity`, `date_based`, `death_certificate` (default: `manual`)
`settings`	object	No	Vault settings object

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Continuity Vault",
    "description": "Critical business documents and credentials",
    "policy_type": "inactivity",
    "settings": {
      "notifications_enabled": true,
      "encryption_enabled": true
    }
  }'

Success Response (201 Created)

{
  "id": "vault_new123abc",
  "name": "Business Continuity Vault",
  "description": "Critical business documents and credentials",
  "status": "active",
  "created_at": "2025-10-08T12:00:00Z",
  "updated_at": "2025-10-08T12:00:00Z",
  "released_at": null,
  "document_count": 0,
  "recipient_count": 0,
  "policy": {
    "type": "inactivity",
    "frequency": null,
    "grace_period_days": null
  },
  "settings": {
    "notifications_enabled": true,
    "auto_renew": false,
    "encryption_enabled": true
  },
  "owner": {
    "id": "user_def456ghi",
    "email": "user@example.com"
  }
}

Error Responses

Status Code	Error	Description
400	Bad Request	Invalid request body or missing required fields
401	Unauthorized	Missing or invalid API key
402	Payment Required	Vault limit reached on current plan
429	Too Many Requests	Rate limit exceeded

Update Vault

PATCH /vaults/{vault_id}

Update vault details. Only provided fields will be updated.

Request

Path Parameters:

Parameter	Type	Required	Description
`vault_id`	string	Yes	Unique vault identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body Parameters (all optional):

Parameter	Type	Description
`name`	string	New vault name (max 100 characters)
`description`	string	New description (max 500 characters)
`settings`	object	Updated settings object

Example Request

curl -X PATCH https://api.torvussecurity.com/v1/vaults/vault_abc123xyz \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Vault Name",
    "description": "Updated description",
    "settings": {
      "notifications_enabled": false
    }
  }'

Success Response (200 OK)

{
  "id": "vault_abc123xyz",
  "name": "Updated Vault Name",
  "description": "Updated description",
  "status": "active",
  "created_at": "2025-10-01T10:00:00Z",
  "updated_at": "2025-10-08T12:30:00Z",
  "released_at": null,
  "document_count": 12,
  "recipient_count": 3,
  "policy": {
    "type": "inactivity",
    "frequency": "monthly",
    "grace_period_days": 14
  },
  "settings": {
    "notifications_enabled": false,
    "auto_renew": true,
    "encryption_enabled": true
  },
  "owner": {
    "id": "user_def456ghi",
    "email": "user@example.com"
  }
}

Error Responses

Status Code	Error	Description
400	Bad Request	Invalid request body
401	Unauthorized	Missing or invalid API key
403	Forbidden	You don't own this vault
404	Not Found	Vault not found
422	Unprocessable Entity	Validation failed (e.g., vault already released)

Delete Vault

DELETE /vaults/{vault_id}

Permanently delete a vault and all its contents. This action cannot be undone.

Request

Path Parameters:

Parameter	Type	Required	Description
`vault_id`	string	Yes	Unique vault identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
`confirm`	boolean	Yes	Must be `true` to confirm deletion

Example Request

curl -X DELETE "https://api.torvussecurity.com/v1/vaults/vault_abc123xyz?confirm=true" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (204 No Content)

No response body. Vault and all contents permanently deleted.

Error Responses

Status Code	Error	Description
400	Bad Request	Missing `confirm=true` parameter
401	Unauthorized	Missing or invalid API key
403	Forbidden	You don't own this vault
404	Not Found	Vault not found
422	Unprocessable Entity	Vault already released (cannot delete)

Release Vault

POST /vaults/{vault_id}/release

Manually release a vault to all recipients immediately. Typically used with manual release policies.

Request

Path Parameters:

Parameter	Type	Required	Description
`vault_id`	string	Yes	Unique vault identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body Parameters:

Parameter	Type	Required	Description
`release_note`	string	No	Optional note to recipients (max 1000 characters)
`notify_recipients`	boolean	No	Send email notifications (default: true)

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123xyz/release \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "release_note": "Investigation complete - see attached evidence",
    "notify_recipients": true
  }'

Success Response (200 OK)

{
  "id": "vault_abc123xyz",
  "name": "Journalism Evidence",
  "status": "released",
  "released_at": "2025-10-08T13:00:00Z",
  "recipients_notified": 2,
  "release_note": "Investigation complete - see attached evidence"
}

Error Responses

Status Code	Error	Description
401	Unauthorized	Missing or invalid API key
403	Forbidden	You don't own this vault
404	Not Found	Vault not found
422	Unprocessable Entity	Vault already released

Archive Vault

POST /vaults/{vault_id}/archive

Archive a vault. Archived vaults are hidden from default lists but not deleted.

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123xyz/archive \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "id": "vault_abc123xyz",
  "name": "Old Vault",
  "status": "archived",
  "archived_at": "2025-10-08T13:15:00Z"
}

Restore Archived Vault

POST /vaults/{vault_id}/restore

Restore an archived vault to active status.

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123xyz/restore \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "id": "vault_abc123xyz",
  "name": "Old Vault",
  "status": "active",
  "restored_at": "2025-10-08T13:20:00Z"
}

Get Vault Statistics

GET /vaults/{vault_id}/statistics

Retrieve usage statistics and analytics for a vault.

Example Request

curl -X GET https://api.torvussecurity.com/v1/vaults/vault_abc123xyz/statistics \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "vault_id": "vault_abc123xyz",
  "storage": {
    "total_bytes": 125829120,
    "document_count": 12,
    "average_document_size": 10485760
  },
  "activity": {
    "last_document_upload": "2025-10-07T15:30:00Z",
    "last_checkin": "2025-10-01T10:00:00Z",
    "total_checkins": 24,
    "missed_checkins": 0
  },
  "recipients": {
    "total_recipients": 3,
    "verified_recipients": 3,
    "pending_verification": 0
  },
  "access": {
    "total_views": 0,
    "total_downloads": 0,
    "last_access": null
  }
}

Rate Limiting

The Vaults API has the following rate limits:

Endpoint	Rate Limit	Time Window
`GET /vaults`	100 requests	Per minute
`GET /vaults/{id}`	200 requests	Per minute
`POST /vaults`	20 requests	Per minute
`PATCH /vaults/{id}`	50 requests	Per minute
`DELETE /vaults/{id}`	10 requests	Per minute
`POST /vaults/{id}/release`	10 requests	Per minute

See Rate Limiting for details.

Error Codes

Common error codes returned by the Vaults API:

Code	Message	Solution
`vault_not_found`	Vault not found	Check vault ID is correct
`vault_already_released`	Vault already released	Cannot modify released vaults
`vault_limit_exceeded`	Vault limit reached	Upgrade plan or delete old vaults
`invalid_policy_type`	Invalid policy type	Use `manual`, `inactivity`, `date_based`, or `death_certificate`
`vault_name_required`	Vault name required	Provide a vault name
`vault_name_too_long`	Vault name too long	Max 100 characters

See Error Handling for complete error documentation.

Documents API - Manage vault documents
Recipients API - Manage vault recipients
Policies API - Configure release policies
Check-ins API - Handle vault check-ins

Last Updated: October 8, 2025

List All Vaults​

Request​

Example Request​

Success Response (200 OK)​

Error Responses​

Get Vault by ID​

Request​

Example Request​

Success Response (200 OK)​

Error Responses​

Create Vault​

Request​

Example Request​

Success Response (201 Created)​

Error Responses​

Update Vault​

Request​

Example Request​

Success Response (200 OK)​

Error Responses​

Delete Vault​

Request​

Example Request​

Success Response (204 No Content)​

Error Responses​

Release Vault​

Request​

Example Request​

Success Response (200 OK)​

Error Responses​

Archive Vault​

Example Request​

Success Response (200 OK)​

Restore Archived Vault​

Example Request​

Success Response (200 OK)​

Get Vault Statistics​

Example Request​

Success Response (200 OK)​

Rate Limiting​

Error Codes​

Related Endpoints​

List All Vaults

Request

Example Request

Success Response (200 OK)

Error Responses

Get Vault by ID

Request

Example Request

Success Response (200 OK)

Error Responses

Create Vault

Request

Example Request

Success Response (201 Created)

Error Responses

Update Vault

Request

Example Request

Success Response (200 OK)

Error Responses

Delete Vault

Request

Example Request

Success Response (204 No Content)

Error Responses

Release Vault

Request

Example Request

Success Response (200 OK)

Error Responses

Archive Vault

Example Request

Success Response (200 OK)

Restore Archived Vault

Example Request

Success Response (200 OK)

Get Vault Statistics

Example Request

Success Response (200 OK)

Rate Limiting

Error Codes

Related Endpoints