Documents API

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

The Documents API allows you to upload, manage, and retrieve documents within vaults.

---

List Vault Documents

GET /vaults/{vault_id}/documents

Retrieve all documents in a vault.

Request

Path Parameters:

Parameter	Type	Required	Description
vault_id	string	Yes	Vault identifier

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 by: name, created_at, size (default: created_at)
order	string	No	asc or desc (default: desc)

Example Request

curl -X GET https://api.torvussecurity.com/v1/vaults/vault_abc123/documents \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "data": [
    {
      "id": "doc_xyz789",
      "name": "will-testament.pdf",
      "size": 1048576,
      "mime_type": "application/pdf",
      "created_at": "2025-10-01T10:00:00Z",
      "updated_at": "2025-10-01T10:00:00Z",
      "vault_id": "vault_abc123",
      "url": "https://api.torvussecurity.com/v1/documents/doc_xyz789/download",
      "metadata": {
        "encrypted": true,
        "checksum": "sha256:abc123..."
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 12,
    "total_pages": 1
  }
}

---

Upload Document

POST /vaults/{vault_id}/documents

Upload a new document to a vault.

Request

Path Parameters:

Parameter	Type	Required	Description
vault_id	string	Yes	Vault identifier

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Form Data:

Field	Type	Required	Description
file	file	Yes	File to upload (max 100MB)
name	string	No	Custom filename (defaults to uploaded filename)
description	string	No	Document description

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123/documents \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@/path/to/document.pdf" \
  -F "name=Important Document.pdf" \
  -F "description=Last will and testament"

Success Response (201 Created)

{
  "id": "doc_new456",
  "name": "Important Document.pdf",
  "description": "Last will and testament",
  "size": 2097152,
  "mime_type": "application/pdf",
  "created_at": "2025-10-08T14:30:00Z",
  "vault_id": "vault_abc123",
  "url": "https://api.torvussecurity.com/v1/documents/doc_new456/download",
  "metadata": {
    "encrypted": true,
    "checksum": "sha256:def456..."
  }
}

Error Responses

Status Code	Error	Description
400	Bad Request	No file provided or invalid file
401	Unauthorized	Missing or invalid API key
403	Forbidden	No permission to add documents
413	Payload Too Large	File exceeds 100MB limit
422	Unprocessable Entity	Vault released (immutable)

---

Get Document

GET /documents/{document_id}

Retrieve document metadata.

Example Request

curl -X GET https://api.torvussecurity.com/v1/documents/doc_xyz789 \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "id": "doc_xyz789",
  "name": "will-testament.pdf",
  "description": "Last will and testament",
  "size": 1048576,
  "mime_type": "application/pdf",
  "created_at": "2025-10-01T10:00:00Z",
  "updated_at": "2025-10-01T10:00:00Z",
  "vault_id": "vault_abc123",
  "url": "https://api.torvussecurity.com/v1/documents/doc_xyz789/download",
  "metadata": {
    "encrypted": true,
    "checksum": "sha256:abc123...",
    "virus_scan": {
      "status": "clean",
      "scanned_at": "2025-10-01T10:00:05Z"
    }
  }
}

---

Download Document

GET /documents/{document_id}/download

Download document file.

Example Request

curl -X GET https://api.torvussecurity.com/v1/documents/doc_xyz789/download \
  -H "Authorization: Bearer your_api_key" \
  --output document.pdf

Success Response (200 OK)

Returns the file binary with appropriate headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="will-testament.pdf"
Content-Length: 1048576

---

Update Document

PATCH /documents/{document_id}

Update document metadata (name, description).

Request Body

{
  "name": "Updated Filename.pdf",
  "description": "Updated description"
}

Success Response (200 OK)

{
  "id": "doc_xyz789",
  "name": "Updated Filename.pdf",
  "description": "Updated description",
  "size": 1048576,
  "mime_type": "application/pdf",
  "updated_at": "2025-10-08T15:00:00Z"
}

---

Delete Document

DELETE /documents/{document_id}

Permanently delete a document.

Example Request

curl -X DELETE https://api.torvussecurity.com/v1/documents/doc_xyz789 \
  -H "Authorization: Bearer your_api_key"

Success Response (204 No Content)

No response body.

Error Responses

Status Code	Error	Description
401	Unauthorized	Missing or invalid API key
403	Forbidden	No permission to delete
404	Not Found	Document not found
422	Unprocessable Entity	Vault released (cannot delete)

---

Rate Limits

Endpoint	Rate Limit
GET /vaults/{id}/documents	100/minute
GET /documents/{id}	200/minute
POST /vaults/{id}/documents	20/minute
GET /documents/{id}/download	100/minute
PATCH /documents/{id}	50/minute
DELETE /documents/{id}	20/minute

---

Last Updated: October 8, 2025