Skip to content

Latest commit

 

History

History
2100 lines (1661 loc) · 35.4 KB

API.md

File metadata and controls

2100 lines (1661 loc) · 35.4 KB

VaultStadio API Documentation

Last updated: 2026-02-16

Overview

VaultStadio provides a RESTful API for file storage and management. All endpoints are prefixed with /api/v1.

Endpoints by area

Area Section
Authentication Login, register, refresh, logout
Storage Folders, upload, download, rename, delete, star, trash
Batch operations Batch delete, move, copy, star, ZIP, empty trash
Thumbnail & preview Thumbnails and file preview
Chunked upload Large file upload
Folder upload Folder upload with structure
Search Search, advanced search, suggestions
Metadata Image, video, document metadata
Share Share links
User Profile, password, quota
Admin User management, system stats
Plugins List, enable/disable plugins
Health Health and readiness
Version history File versioning (Phase 6)
Sync Device sync (Phase 6)
Federation Cross-instance (Phase 6)
Collaboration Real-time collaboration (Phase 6)
AI Providers, chat, vision, tagging (Phase 6)
WebDAV WebDAV protocol (Phase 6)
S3 S3-compatible API (Phase 6)
Activity Activity log

Table of contents

Base URL: http://localhost:8080/api/v1

Interactive Documentation: http://localhost:8080/swagger-ui

Authentication

Most endpoints require authentication via JWT token.

Obtain Token

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "username": "username",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2024-01-08T00:00:00Z"
  }
}

Use Token

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication Endpoints

Register

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "username",
  "password": "password123"
}

Response: 201 Created

{
  "id": "user-uuid",
  "email": "user@example.com",
  "username": "username",
  "role": "user",
  "createdAt": "2024-01-01T00:00:00Z"
}

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Logout

POST /api/v1/auth/logout
Authorization: Bearer <token>

Response: 204 No Content

Refresh Token

Refresh an expired access token using a valid refresh token. Implements token rotation for security.

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "username": "username",
      "role": "user"
    },
    "token": "new-access-token...",
    "refreshToken": "new-refresh-token...",
    "expiresAt": "2024-02-01T00:00:00Z"
  }
}

Note: Token rotation is implemented - each refresh invalidates the old refresh token and issues a new pair of tokens.

Get Current User

Available at both /api/v1/auth/me and /api/v1/user/me (equivalent endpoints).

GET /api/v1/auth/me
Authorization: Bearer <token>

Response:

{
  "id": "user-uuid",
  "email": "user@example.com",
  "username": "username",
  "role": "user",
  "quota": {
    "used": 1073741824,
    "total": 10737418240
  }
}

Storage Endpoints

List Folder Contents

GET /api/v1/storage/folder
GET /api/v1/storage/folder/{folderId}
Authorization: Bearer <token>

Query Parameters:

Parameter Type Description Default
sort string Sort field (name, size, createdAt, updatedAt) name
order string Sort order (asc, desc) asc
limit int Items per page 50
offset int Pagination offset 0

Response:

{
  "items": [
    {
      "id": "item-uuid",
      "name": "Documents",
      "path": "/Documents",
      "type": "folder",
      "parentId": null,
      "size": 0,
      "mimeType": null,
      "isStarred": false,
      "isTrashed": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "item-uuid-2",
      "name": "photo.jpg",
      "path": "/photo.jpg",
      "type": "file",
      "parentId": null,
      "size": 1048576,
      "mimeType": "image/jpeg",
      "isStarred": true,
      "isTrashed": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Create Folder

POST /api/v1/storage/folder
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "New Folder",
  "parentId": null
}

Response: 201 Created

{
  "id": "new-folder-uuid",
  "name": "New Folder",
  "path": "/New Folder",
  "type": "folder",
  ...
}

Upload File

POST /api/v1/storage/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary>
parentId: folder-uuid (optional)

Response: 201 Created

{
  "id": "file-uuid",
  "name": "uploaded-file.pdf",
  "path": "/uploaded-file.pdf",
  "type": "file",
  "size": 2097152,
  "mimeType": "application/pdf",
  ...
}

Download File

GET /api/v1/storage/download/{itemId}
Authorization: Bearer <token>

Response: Binary file with appropriate Content-Type header.

Get Item Details

GET /api/v1/storage/{itemId}
Authorization: Bearer <token>

Update Item (Rename/Move)

PATCH /api/v1/storage/{itemId}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "New Name",
  "parentId": "new-parent-folder-uuid"
}

Delete Item

DELETE /api/v1/storage/{itemId}
Authorization: Bearer <token>

Response: 204 No Content

Toggle Star

POST /api/v1/storage/{itemId}/star
Authorization: Bearer <token>

Move to Trash

POST /api/v1/storage/{itemId}/trash
Authorization: Bearer <token>

Restore from Trash

POST /api/v1/storage/{itemId}/restore
Authorization: Bearer <token>

Get Starred Items

GET /api/v1/storage/starred
Authorization: Bearer <token>

Get Trash

GET /api/v1/storage/trash
Authorization: Bearer <token>

Get Recent Items

GET /api/v1/storage/recent
Authorization: Bearer <token>

Get Breadcrumbs

GET /api/v1/storage/{itemId}/breadcrumbs
Authorization: Bearer <token>

Response:

[
  { "id": null, "name": "Home", "path": "/" },
  { "id": "folder-1", "name": "Documents", "path": "/Documents" },
  { "id": "folder-2", "name": "Work", "path": "/Documents/Work" }
]

Batch Operations Endpoints

Batch Delete

Delete multiple items at once.

POST /api/v1/storage/batch/delete
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemIds": ["item-uuid-1", "item-uuid-2", "item-uuid-3"],
  "permanent": false
}

Response:

{
  "success": true,
  "data": {
    "successful": 3,
    "failed": 0,
    "errors": []
  }
}

Batch Move

Move multiple items to a destination folder.

POST /api/v1/storage/batch/move
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemIds": ["item-uuid-1", "item-uuid-2"],
  "destinationId": "folder-uuid"
}

Batch Copy

Copy multiple items to a destination folder.

POST /api/v1/storage/batch/copy
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemIds": ["item-uuid-1", "item-uuid-2"],
  "destinationId": "folder-uuid"
}

Batch Star

Star or unstar multiple items.

POST /api/v1/storage/batch/star
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemIds": ["item-uuid-1", "item-uuid-2"],
  "starred": true
}

Download as ZIP

Download multiple items as a single ZIP file.

POST /api/v1/storage/batch/download-zip
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemIds": ["item-uuid-1", "item-uuid-2", "item-uuid-3"]
}

Response: Binary ZIP file with Content-Type: application/zip

Empty Trash

Permanently delete all items in trash.

POST /api/v1/storage/batch/empty-trash
Authorization: Bearer <token>

Thumbnail & Preview Endpoints

Get Thumbnail

Generate and serve a thumbnail for an image file.

GET /api/v1/storage/item/{itemId}/thumbnail?size=medium
Authorization: Bearer <token>

Query Parameters:

Parameter Type Description Default
size string Thumbnail size (small: 64px, medium: 128px, large: 256px, xlarge: 512px) medium

Response: PNG image binary

Get Preview

Get file content for preview (images, text, PDF, video, audio).

GET /api/v1/storage/item/{itemId}/preview
Authorization: Bearer <token>

Supported MIME Types:

  • Images: image/*
  • Videos: video/*
  • Audio: audio/*
  • Text: text/*
  • PDF: application/pdf
  • JSON: application/json

Chunked Upload Endpoints

For uploading large files (> 100MB).

Initialize Chunked Upload

POST /api/v1/storage/upload/init
Authorization: Bearer <token>
Content-Type: application/json

{
  "fileName": "large-file.zip",
  "fileSize": 5368709120,
  "mimeType": "application/zip",
  "parentId": "folder-uuid"
}

Response:

{
  "uploadId": "upload-session-uuid",
  "chunkSize": 10485760,
  "totalChunks": 512
}

Upload Chunk

POST /api/v1/storage/upload/{uploadId}/chunk/{chunkIndex}
Authorization: Bearer <token>
Content-Type: application/octet-stream

<binary chunk data>

Get Upload Status

GET /api/v1/storage/upload/{uploadId}/status
Authorization: Bearer <token>

Response:

{
  "uploadId": "upload-session-uuid",
  "fileName": "large-file.zip",
  "totalSize": 5368709120,
  "uploadedBytes": 2684354560,
  "progress": 0.5,
  "receivedChunks": [0, 1, 2, 3],
  "missingChunks": [4, 5, 6, 7],
  "isComplete": false
}

Complete Chunked Upload

POST /api/v1/storage/upload/{uploadId}/complete
Authorization: Bearer <token>

Cancel Chunked Upload

DELETE /api/v1/storage/upload/{uploadId}
Authorization: Bearer <token>

Folder Upload Endpoint

Upload an entire folder with structure preserved.

POST /api/v1/storage/upload-folder
Authorization: Bearer <token>
Content-Type: multipart/form-data

parentId: folder-uuid (optional)
<relativePath>: <file binary>
<relativePath>: <file binary>
...

Response:

{
  "success": true,
  "data": {
    "uploadedFiles": 25,
    "createdFolders": 5,
    "errors": []
  }
}

Search Endpoints

Search Files

GET /api/v1/search?q=query&limit=50&offset=0
Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
q string Search query (required)
limit int Results limit
offset int Pagination offset

Response:

{
  "items": [...],
  "total": 10,
  "limit": 50,
  "offset": 0
}

Advanced Search

Search with filters for file type, size, and date range.

POST /api/v1/search/advanced
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "report",
  "searchContent": true,
  "fileTypes": ["pdf", "doc"],
  "minSize": 1024,
  "maxSize": 10485760,
  "fromDate": "2024-01-01",
  "toDate": "2024-12-31",
  "limit": 50,
  "offset": 0
}

Search Suggestions (Autocomplete)

GET /api/v1/search/suggestions?prefix=doc&limit=10
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": ["document.pdf", "documentation.md", "docker-compose.yml"]
}

Metadata Endpoints

Get All File Metadata

GET /api/v1/storage/item/{itemId}/metadata
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "itemId": "item-uuid",
    "metadata": {
      "width": "1920",
      "height": "1080",
      "cameraMake": "Canon",
      "cameraModel": "EOS R5",
      "dateTaken": "2024-01-15T10:30:00Z"
    },
    "extractedBy": ["com.vaultstadio.plugins.image-metadata"]
  }
}

Get Image Metadata

GET /api/v1/storage/item/{itemId}/metadata/image
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "width": 1920,
    "height": 1080,
    "cameraMake": "Canon",
    "cameraModel": "EOS R5",
    "dateTaken": "2024-01-15T10:30:00Z",
    "aperture": "f/2.8",
    "exposureTime": "1/250",
    "iso": 400,
    "focalLength": "50mm",
    "gpsLatitude": 40.7128,
    "gpsLongitude": -74.0060,
    "colorSpace": "sRGB",
    "bitDepth": 8,
    "keywords": ["landscape", "nature"],
    "copyright": "© 2024 Photographer"
  }
}

Get Video Metadata

GET /api/v1/storage/item/{itemId}/metadata/video
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "width": 3840,
    "height": 2160,
    "duration": 3600,
    "durationFormatted": "1:00:00",
    "videoCodec": "h264",
    "audioCodec": "aac",
    "frameRate": "29.97",
    "bitrate": 15000000,
    "aspectRatio": "16:9",
    "colorSpace": "bt709",
    "isHDR": false,
    "channels": 2,
    "sampleRate": 48000,
    "chapterCount": 5,
    "subtitleTracks": ["en", "es"],
    "audioLanguages": ["en", "es"]
  }
}

Get Document Metadata

GET /api/v1/storage/item/{itemId}/metadata/document
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "title": "Annual Report 2024",
    "author": "John Doe",
    "subject": "Financial Report",
    "keywords": ["finance", "annual", "report"],
    "creator": "Microsoft Word",
    "producer": "Adobe PDF",
    "creationDate": "2024-01-15T09:00:00Z",
    "modificationDate": "2024-01-20T14:30:00Z",
    "pageCount": 50,
    "wordCount": 25000,
    "isIndexed": true,
    "indexedAt": "2024-01-20T15:00:00Z"
  }
}

Share Endpoints

List Shares

GET /api/v1/shares
Authorization: Bearer <token>

Response:

[
  {
    "id": "share-uuid",
    "itemId": "file-uuid",
    "itemName": "document.pdf",
    "token": "abc123def456",
    "url": "http://localhost:8080/share/abc123def456",
    "password": null,
    "expiresAt": "2024-02-01T00:00:00Z",
    "maxDownloads": 10,
    "downloadCount": 3,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Create Share

POST /api/v1/shares
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemId": "file-uuid",
  "expirationDays": 7,
  "password": "optional-password",
  "maxDownloads": 10
}

Response: 201 Created

{
  "id": "share-uuid",
  "token": "abc123def456",
  "url": "http://localhost:8080/share/abc123def456",
  ...
}

Delete Share

DELETE /api/v1/shares/{shareId}
Authorization: Bearer <token>

Response: 204 No Content

Access Shared File (Public)

GET /api/v1/share/{token}

If password protected:

POST /api/v1/share/{token}
Content-Type: application/json

{
  "password": "share-password"
}

User Endpoints

Get User Profile

GET /api/v1/users/me
Authorization: Bearer <token>

Update Profile

PATCH /api/v1/users/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "new-username"
}

Change Password

POST /api/v1/users/me/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "currentPassword": "old-password",
  "newPassword": "new-password"
}

Get Quota

GET /api/v1/users/me/quota
Authorization: Bearer <token>

Response:

{
  "used": 1073741824,
  "total": 10737418240,
  "percentage": 10.0
}

Admin Endpoints

Requires admin role.

List Users

GET /api/v1/admin/users
Authorization: Bearer <admin-token>

Create User

POST /api/v1/admin/users
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "username",
  "password": "password123",
  "role": "user",
  "quotaBytes": 10737418240
}

Update User

PATCH /api/v1/admin/users/{userId}
Authorization: Bearer <admin-token>

Delete User

DELETE /api/v1/admin/users/{userId}
Authorization: Bearer <admin-token>

System Stats

GET /api/v1/admin/stats
Authorization: Bearer <admin-token>

Response:

{
  "totalUsers": 10,
  "totalFiles": 1000,
  "totalStorage": 10737418240,
  "activeShares": 25
}

Plugin Endpoints

List Plugins

GET /api/v1/plugins
Authorization: Bearer <token>

Get Plugin Details

GET /api/v1/plugins/{pluginId}
Authorization: Bearer <token>

Enable/Disable Plugin (Admin)

POST /api/v1/admin/plugins/{pluginId}/enable
POST /api/v1/admin/plugins/{pluginId}/disable
Authorization: Bearer <admin-token>

Health Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "2.0.0"
}

Readiness Check

GET /ready

Response:

{
  "ready": true,
  "checks": {
    "database": {
      "status": "up",
      "latencyMs": 5
    },
    "storage": {
      "status": "up",
      "latencyMs": 2
    }
  }
}

Error Responses

All errors follow this format:

{
  "error": "error_code",
  "message": "Human readable message",
  "details": { ... }
}

Common Error Codes

Code HTTP Status Description
unauthorized 401 Missing or invalid token
forbidden 403 Insufficient permissions
not_found 404 Resource not found
validation_error 400 Invalid request data
conflict 409 Resource already exists
quota_exceeded 413 Storage quota exceeded
internal_error 500 Server error

Rate Limiting

API requests are rate limited:

  • Authenticated: 1000 requests per hour
  • Unauthenticated: 100 requests per hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Pagination

List endpoints support pagination:

GET /api/v1/storage/folder?limit=20&offset=40

Response includes pagination info:

{
  "items": [...],
  "total": 100,
  "limit": 20,
  "offset": 40
}

Version History Endpoints (Phase 6)

Get Version History

GET /api/v1/versions/item/{itemId}
Authorization: Bearer <token>

Response:

{
  "itemId": "file-uuid",
  "currentVersion": 5,
  "versions": [
    {
      "versionNumber": 5,
      "size": 2048576,
      "checksum": "sha256:abc123...",
      "createdBy": "user-uuid",
      "createdAt": "2024-01-15T14:30:00Z",
      "comment": "Final review"
    },
    {
      "versionNumber": 4,
      "size": 2000000,
      "checksum": "sha256:def456...",
      "createdBy": "user-uuid",
      "createdAt": "2024-01-14T10:00:00Z",
      "comment": null
    }
  ]
}

Get Specific Version

GET /api/v1/versions/item/{itemId}/version/{versionNumber}
Authorization: Bearer <token>

Download Version

GET /api/v1/versions/item/{itemId}/version/{versionNumber}/download
Authorization: Bearer <token>

Response: Binary file content

Restore Version

POST /api/v1/versions/item/{itemId}/restore
Authorization: Bearer <token>
Content-Type: application/json

{
  "versionNumber": 3,
  "comment": "Restoring previous version"
}

Compare Versions

GET /api/v1/versions/item/{itemId}/diff?from=2&to=5
Authorization: Bearer <token>

Response:

{
  "fromVersion": 2,
  "toVersion": 5,
  "changes": {
    "sizeChange": 48576,
    "linesAdded": 50,
    "linesRemoved": 10
  }
}

Delete Version

DELETE /api/v1/versions/{versionId}
Authorization: Bearer <token>

Cleanup Versions

Apply retention policy to remove old versions.

POST /api/v1/versions/item/{itemId}/cleanup
Authorization: Bearer <token>
Content-Type: application/json

{
  "maxVersions": 10,
  "maxAgeDays": 90,
  "minKeep": 3
}

Sync Endpoints (Phase 6)

Register Device

POST /api/v1/sync/devices
Authorization: Bearer <token>
Content-Type: application/json

{
  "deviceId": "device-uuid",
  "deviceName": "My MacBook",
  "deviceType": "desktop"
}

Response:

{
  "id": "device-uuid",
  "name": "My MacBook",
  "type": "desktop",
  "lastSyncAt": null,
  "isActive": true,
  "createdAt": "2024-01-15T10:00:00Z"
}

List Devices

GET /api/v1/sync/devices
Authorization: Bearer <token>

Deactivate Device

POST /api/v1/sync/devices/{deviceId}/deactivate
Authorization: Bearer <token>

Remove Device

DELETE /api/v1/sync/devices/{deviceId}
Authorization: Bearer <token>

Pull Changes

Get changes from server since last sync.

POST /api/v1/sync/pull
Authorization: Bearer <token>
Content-Type: application/json

{
  "deviceId": "device-uuid",
  "cursor": "2024-01-15T10:00:00Z"
}

Response:

{
  "changes": [
    {
      "itemId": "file-uuid",
      "action": "created",
      "item": { ... },
      "timestamp": "2024-01-15T11:00:00Z"
    },
    {
      "itemId": "file-uuid-2",
      "action": "modified",
      "item": { ... },
      "timestamp": "2024-01-15T11:30:00Z"
    }
  ],
  "cursor": "2024-01-15T12:00:00Z",
  "hasMore": false
}

Push Changes

Send local changes to server.

POST /api/v1/sync/push
Authorization: Bearer <token>
Content-Type: application/json

{
  "deviceId": "device-uuid",
  "changes": [
    {
      "itemId": "file-uuid",
      "action": "modified",
      "checksum": "sha256:abc123...",
      "modifiedAt": "2024-01-15T12:00:00Z"
    }
  ]
}

Get Conflicts

GET /api/v1/sync/conflicts
Authorization: Bearer <token>

Response:

{
  "conflicts": [
    {
      "id": "conflict-uuid",
      "itemId": "file-uuid",
      "localVersion": { ... },
      "remoteVersion": { ... },
      "detectedAt": "2024-01-15T12:00:00Z"
    }
  ]
}

Resolve Conflict

POST /api/v1/sync/conflicts/{conflictId}/resolve
Authorization: Bearer <token>
Content-Type: application/json

{
  "resolution": "keep_local"
}

Resolution options: keep_local, keep_remote, keep_both

Federation Endpoints (Phase 6)

Instance Discovery (Public)

GET /api/v1/federation/.well-known/vaultstadio

Response:

{
  "instanceName": "My VaultStadio",
  "version": "2.0.0",
  "capabilities": ["RECEIVE_SHARES", "SEND_SHARES", "FEDERATED_IDENTITY"],
  "publicKey": "-----BEGIN PUBLIC KEY-----..."
}

Request Federation

POST /api/v1/federation/instances/request
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetDomain": "storage.example.com",
  "message": "Request to federate"
}

List Federated Instances

GET /api/v1/federation/instances
Authorization: Bearer <token>

Block Instance

POST /api/v1/federation/instances/{instanceId}/block
Authorization: Bearer <token>

Remove Instance

DELETE /api/v1/federation/instances/{instanceId}
Authorization: Bearer <token>

Create Federated Share

POST /api/v1/federation/shares
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemId": "file-uuid",
  "targetInstance": "storage.example.com",
  "targetUserId": "user@storage.example.com",
  "permissions": ["READ", "WRITE"]
}

List Outgoing Shares

GET /api/v1/federation/shares/outgoing
Authorization: Bearer <token>

List Incoming Shares

GET /api/v1/federation/shares/incoming?status=PENDING
Authorization: Bearer <token>

Accept Share

POST /api/v1/federation/shares/{shareId}/accept
Authorization: Bearer <token>

Decline Share

POST /api/v1/federation/shares/{shareId}/decline
Authorization: Bearer <token>

Revoke Share

POST /api/v1/federation/shares/{shareId}/revoke
Authorization: Bearer <token>

Link Federated Identity

POST /api/v1/federation/identities
Authorization: Bearer <token>
Content-Type: application/json

{
  "remoteInstance": "storage.example.com",
  "remoteUserId": "user-uuid"
}

List Federated Identities

GET /api/v1/federation/identities
Authorization: Bearer <token>

Unlink Identity

DELETE /api/v1/federation/identities/{identityId}
Authorization: Bearer <token>

Collaboration Endpoints (Phase 6)

Join Session

POST /api/v1/collaboration/sessions/join
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemId": "file-uuid"
}

Response:

{
  "id": "session-uuid",
  "itemId": "file-uuid",
  "participants": [
    {
      "userId": "user-uuid",
      "displayName": "John Doe",
      "cursorPosition": null,
      "isActive": true
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z"
}

Leave Session

POST /api/v1/collaboration/sessions/{sessionId}/leave
Authorization: Bearer <token>

Get Session

GET /api/v1/collaboration/sessions/{sessionId}
Authorization: Bearer <token>

Get Participants

GET /api/v1/collaboration/sessions/{sessionId}/participants
Authorization: Bearer <token>

Get Document State

GET /api/v1/collaboration/documents/{itemId}
Authorization: Bearer <token>

Response:

{
  "itemId": "file-uuid",
  "version": 15,
  "content": "Document content...",
  "lastModifiedBy": "user-uuid",
  "lastModifiedAt": "2024-01-15T14:30:00Z"
}

Save Document

POST /api/v1/collaboration/documents/{itemId}/save
Authorization: Bearer <token>

Get Comments

GET /api/v1/collaboration/documents/{itemId}/comments
Authorization: Bearer <token>

Response:

{
  "comments": [
    {
      "id": "comment-uuid",
      "content": "Please review this section",
      "authorId": "user-uuid",
      "authorName": "John Doe",
      "startLine": 10,
      "startColumn": 5,
      "endLine": 10,
      "endColumn": 50,
      "quotedText": "The section text",
      "isResolved": false,
      "replies": [],
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Comment

POST /api/v1/collaboration/documents/{itemId}/comments
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Please review this section",
  "startLine": 10,
  "startColumn": 5,
  "endLine": 10,
  "endColumn": 50,
  "quotedText": "The section text"
}

Resolve Comment

POST /api/v1/collaboration/documents/{itemId}/comments/{commentId}/resolve
Authorization: Bearer <token>

Reply to Comment

POST /api/v1/collaboration/documents/{itemId}/comments/{commentId}/replies
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Done, please check"
}

Delete Comment

DELETE /api/v1/collaboration/documents/{itemId}/comments/{commentId}
Authorization: Bearer <token>

WebSocket Connection

Real-time updates via WebSocket:

ws://localhost:8080/api/v1/collaboration/ws/{sessionId}
Authorization: Bearer <token>

Messages:

// Cursor update
{
  "type": "cursor",
  "userId": "user-uuid",
  "position": { "line": 10, "column": 5 }
}

// Content change
{
  "type": "operation",
  "operation": {
    "type": "insert",
    "position": 150,
    "text": "new text"
  }
}

// Participant joined
{
  "type": "participant_joined",
  "participant": { ... }
}

AI Endpoints (Phase 6)

List Providers (Admin)

GET /api/v1/ai/providers
Authorization: Bearer <admin-token>

Response:

{
  "providers": [
    {
      "type": "ollama",
      "baseUrl": "http://localhost:11434",
      "isActive": true,
      "isAvailable": true
    },
    {
      "type": "openrouter",
      "baseUrl": "https://openrouter.ai/api",
      "isActive": false,
      "isAvailable": true
    }
  ]
}

Configure Provider (Admin)

POST /api/v1/ai/providers
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "type": "ollama",
  "baseUrl": "http://localhost:11434",
  "apiKey": null,
  "model": "llava"
}

Set Active Provider (Admin)

POST /api/v1/ai/providers/active
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "type": "ollama"
}

List Models

GET /api/v1/ai/models
Authorization: Bearer <token>

Response:

{
  "models": [
    {
      "id": "llava",
      "name": "LLaVA",
      "provider": "ollama",
      "capabilities": ["vision", "chat"]
    }
  ]
}

Chat Completion

POST /api/v1/ai/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "Describe this image" }
  ],
  "model": "llava"
}

Response:

{
  "content": "This image shows...",
  "model": "llava",
  "usage": {
    "promptTokens": 10,
    "completionTokens": 50
  }
}

Vision (Image Analysis)

POST /api/v1/ai/vision
Authorization: Bearer <token>
Content-Type: application/json

{
  "imageBase64": "data:image/jpeg;base64,...",
  "prompt": "What is in this image?",
  "mimeType": "image/jpeg"
}

Describe Image

POST /api/v1/ai/describe
Authorization: Bearer <token>
Content-Type: application/json

{
  "imageBase64": "data:image/jpeg;base64,...",
  "mimeType": "image/jpeg"
}

Response:

{
  "description": "A sunset over the ocean with..."
}

Auto-Tag Image

POST /api/v1/ai/tag
Authorization: Bearer <token>
Content-Type: application/json

{
  "imageBase64": "data:image/jpeg;base64,...",
  "mimeType": "image/jpeg"
}

Response:

{
  "tags": ["sunset", "ocean", "beach", "nature", "landscape"]
}

Classify Content

POST /api/v1/ai/classify
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "This is a financial report...",
  "categories": ["finance", "marketing", "engineering", "hr"]
}

Response:

{
  "category": "finance",
  "confidence": 0.95
}

Summarize Text

POST /api/v1/ai/summarize
Authorization: Bearer <token>
Content-Type: application/json

{
  "text": "Long document text...",
  "maxLength": 200
}

Response:

{
  "summary": "This document discusses..."
}

WebDAV Endpoints (Phase 6)

VaultStadio provides WebDAV access for desktop integration.

Base URL: http://localhost:8080/webdav

Supported Methods

Method Description
OPTIONS Get supported methods
GET Download file
PUT Upload/update file
DELETE Delete file/folder
MKCOL Create folder
COPY Copy file/folder
MOVE Move/rename file/folder
PROPFIND List properties
PROPPATCH Update properties
LOCK Lock resource
UNLOCK Unlock resource

Authentication

Authorization: Basic base64(email:password)

Example Usage

# Mount on macOS
mount_webdav http://localhost:8080/webdav /Volumes/VaultStadio

# Mount on Linux
sudo mount -t davfs http://localhost:8080/webdav /mnt/vaultstadio

# Windows
net use Z: http://localhost:8080/webdav /user:email password

S3-Compatible API (Phase 6)

VaultStadio provides an S3-compatible API for tools like rclone, s3cmd, etc.

Base URL: http://localhost:8080/s3

Supported Operations

Operation Endpoint Description
ListBuckets GET /s3 List root folders as buckets
ListObjects GET /s3/{bucket} List objects in bucket
HeadBucket HEAD /s3/{bucket} Check bucket exists
CreateBucket PUT /s3/{bucket} Create bucket (folder)
DeleteBucket DELETE /s3/{bucket} Delete empty bucket
GetObject GET /s3/{bucket}/{key} Download object
HeadObject HEAD /s3/{bucket}/{key} Get object metadata
PutObject PUT /s3/{bucket}/{key} Upload object
DeleteObject DELETE /s3/{bucket}/{key} Delete object

Authentication

AWS Signature Version 4:

Authorization: AWS4-HMAC-SHA256 Credential=...

Credentials:

  • Access Key ID: Your email
  • Secret Access Key: Your password or API key

Example Usage

# rclone configuration
rclone config create vaultstadio s3 \
  provider=Other \
  endpoint=http://localhost:8080/s3 \
  access_key_id=user@example.com \
  secret_access_key=your-password

# s3cmd configuration
s3cmd --configure \
  --host=localhost:8080 \
  --host-bucket="%(bucket)s.localhost:8080" \
  --access_key=user@example.com \
  --secret_key=your-password

Activity Endpoints

Get Recent Activity

GET /api/v1/activity?limit=50
Authorization: Bearer <token>

Response:

{
  "activities": [
    {
      "id": "activity-uuid",
      "type": "file.uploaded",
      "itemId": "file-uuid",
      "itemName": "document.pdf",
      "userId": "user-uuid",
      "userName": "John Doe",
      "timestamp": "2024-01-15T10:00:00Z",
      "details": {
        "size": 1048576
      }
    }
  ]
}

Get Item Activity

GET /api/v1/activity/item/{itemId}
Authorization: Bearer <token>

Activity Types:

  • file.uploaded
  • file.downloaded
  • file.deleted
  • file.moved
  • file.copied
  • file.renamed
  • file.starred
  • file.shared
  • folder.created
  • version.created
  • version.restored

Webhooks (Planned)

Coming in a future release:

{
  "event": "file.uploaded",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "itemId": "file-uuid",
    "name": "document.pdf"
  }
}