DocuSync | Technical API Specification

Authentication Services

Security protocols for developer and system access.

POST /api/login

Exchange Credentials

Authenticates primary account credentials to generate a Laravel Sanctum Bearer Token.

Field	Type	Description
email	string	Developer registration email.
password	string	Secure account password.

POST /api/generate-keys

Header Key Rotation

Generates a fresh X-API-Key / X-API-Secret pair. Useful for automated key rotation strategies in production environments.

Identity & Usage

Manage developer account profile and monitor infrastructure utilization.

GET /api/profile

User Profile Context

Retrieves complete information about the authenticated developer account, including subscription tier limits and organization metadata.

Response Payload Mapping

Property	Type	Description
id	integer	Internal account identifier.
name	string	Full name associated with the account.
email	string	Verified communication address.
org_name	string	Assigned organization profile.
subscription	object	Includes `plan_name`, `storage_limit_mb`, and `document_expiry_days`.

Request Authorization

Authorization: Bearer [token]
X-API-Key: [public_key]
X-API-Secret: [secret_key]

Response Example

{
  "status": true,
  "data": {
    "id": 1,
    "name": "Acme Legal Admin",
    "subscription": {
      "plan": "Enterprise Gold",
      "limit": 51200
    }
  }
}

GET /api/storage/usage

Infrastructure Usage Analytics

Returns a microscopic breakdown of storage consumption across all tiers. Essential for monitoring quota before initiating large batch uploads.

Calculated Metrics

Metric Key	Description
total_limit_mb	The maximum capacity allowed by current subscription.
used_mb	Aggregate of all files in S3.
usage_percent	Precision float of consumption vs limit.
tier_breakdown	Object separating `standard` vs `compliance` storage volume.

Folder Management

APIs to organize document infrastructure into a logical hierarchy.

GET /api/folders

Inventory Listing

Retrieves all directories owned by the user. Includes metadata like child counts to facilitate tree-view rendering in client applications.

POST /api/create-folder

Initialize Directory

Creates a new logical container within the user's infrastructure.

Parameter	Type	Req	Effect / Constraint
name	string	Req	Folder name. Max 255 chars. Regex: `A-Za-z0-9_.-`
parent_id	integer	Opt	Target parent folder. If null, created in Root.
color	string	Opt	Hex code for UI display. Default: `#4f46e5`.

POST /api/update-folder/{id}

Update Folder / Relocate

Allows renaming a directory or changing its parent container. System strictly prevents circular references (moving a folder into its own descendant).

DELETE /api/delete-folder/{id}

Permanent Removal

Irreversibly deletes a logical container. Constraint: The folder must be entirely empty (no sub-folders or active documents) to prevent accidental data loss.

Document Engine

Core Document Lifecycle Management and S3 Interaction.

GET /api/documents

List Document Assets

Comprehensive list of document resources with pagination. Supports filtering by folder and storage tier.

Filter	Type	Description
folder_id	integer	Filter by directory.
storage_type	enum	Filter by `standard`(1) or `compliance`(2).

POST /api/upload-document

Secure Payload Upload

Transmits binary objects directly into DocuSync's encrypted S3 infrastructure. Triggers automated antivirus scanning and checksum generation (SHA-256).

Parameter	Type	Req	Description
document	file	Req	Binary file. Allowed: PDF, DOCX, JPG, PNG, CSV. Max: 50MB.
title	string	Req	Display title for the resource.
storage_type	string	Req	`standard` or `compliance`.
folder_id	integer	Opt	Target directory ID.
retention_period	integer	Opt	Required if type is compliance. Range: 1-15 (years).

GET /api/download-document/{id}

Fetch S3 Access Token

Generates a temporary, 15-minute expiring AWS Pre-signed URL. This allows the client to stream the binary safely without exposing the master credentials.

GET /api/documents/{id}

Full Document Context

Returns a detailed blueprint of the document. Includes: Encryption Metadata, Fingerprint (Hash), Storage Analytics, Breadcrumbs, and a full chronological Audit History.

POST /api/update-document/title/{id}

Metadata Refinement

Updates the document title in the database. Block Logic: This request is rejected with a 403 error if the document is currently under a Compliance Retention lock.

POST /api/move-document/folder/{id}

Logical Relocation

Changes the folder_id reference for a document. Does not physically move the object in S3, ensuring zero downtime for links.

Compliance Vault

SEC/FINRA Immutable Storage & Retention Lifecycle.

POST /api/move-to-compliance/{id}

Engage WORM Lock

Transitions a document from standard storage to the Compliance Vault. Once moved, the document becomes globally immutable (no edit/delete) until the retention period expires.

Parameter	Type	Req	Description
retention_period	integer	Req	Protective lock duration in years (1-15).

POST /api/move-to-standard/{id}

Post-Retention Release

Moves a released document (retention period ended) back to Standard storage. Reinstates standard management rights (rename/delete).

POST /api/retention-period/extend/{id}

Extend Legal Hold

Adds additional years to a document's lock period. This is the only update permitted for locked assets.

GET /api/compliance/logs

Vault Asset Audit

List of all system-wide compliance locks, including start date, expiration date, and officer ID responsible for the lock.

GET /api/compliance/analytics

Vault Vital Statistics

Real-time status report of the vault. Useful for legal discovery dashboards.

System Integrity

Tamper-Evident Audit Trails & Forensic Traces.

GET /api/audit/logs

Master Audit History

Chronological feed of every technical event within the tenant infrastructure. Every entry is cryptographically linked to the previous one to prevent tampering.

GET /api/audit/logs/{id}

Microscopic Trace Breakdown

Extreme detail for a single event. Includes Browser Fingerprint, Device OS, and Raw Transactional Context.

Data Recovery

Manage the document trash lifecycle and permanent purges.

GET /api/trash

Recycle Bin Inventory

Listing of documents with status 'trash'. Assets in this list are held for 90 days before automated physical deletion (unless purged earlier).

DELETE /api/trash-document/{id}

Logical Deletion

Changes document status to 'trash'. Condition: Will fail for Compliance documents under active lock.

POST /api/trash/restore/{id}

Restore Document

Resurrects a document from the Recycle Bin back to its original hierarchical location.

DELETE /api/trash/permanent/{id}

Physical S3 Purge

Irreversibly deletes the physical binary object from AWS S3 buckets. Recommended after confirming legal clearance for disposal.

Global Tools & Automation

Broad infrastructure features and document generation services.

GET /api/search

Infrastructure-Wide Search

Crawls through all folders and document titles simultaneously. Returns a flattened set of matching resources.