{"openapi":"3.0.0","paths":{"/api/v1/assets":{"post":{"operationId":"AssetsController_createAsset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetDto"}}}},"responses":{"201":{"description":"Asset created successfully"}},"summary":"Create a new asset","tags":["Assets"]},"get":{"operationId":"AssetsController_listAssets","parameters":[{"name":"companyId","required":false,"in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator ID","schema":{"type":"string"}},{"name":"searchTerm","required":false,"in":"query","description":"Search term","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"enum":["DRAFT","PENDING_VERIFICATION","VERIFIED","REJECTED","PENDING_DISTRIBUTION","DEPLOYED","ACTIVE","SUSPENDED","ARCHIVED"],"type":"string"}},{"name":"assetType","required":false,"in":"query","description":"Filter by asset type","schema":{"enum":["MUSIC","FILM_TV","ATHLETE_CONTRACT","IMAGE_RIGHTS","SPORTS_MEMORABILIA","EVENT_RIGHTS","MERCHANDISE_RIGHTS","CONTENT_RIGHTS","BRAND_PARTNERSHIP","INTELLECTUAL_PROPERTY","PRIZE_PURSE","ROYALTY_STREAM","REVENUE_SHARE","UTILITY_TOKEN","FAN_TOKEN","MEMBERSHIP","REAL_ESTATE","ART","COLLECTIBLE","CARBON_CREDITS","COMMODITIES","SECURITIES","EQUIPMENT","VEHICLES","OTHER"],"type":"string"}}],"responses":{"200":{"description":"Assets retrieved successfully"}},"summary":"List assets with filtering and pagination","tags":["Assets"]}},"/api/v1/assets/{id}":{"get":{"operationId":"AssetsController_getAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Asset retrieved successfully"},"403":{"description":"Forbidden - User does not have access to this asset"},"404":{"description":"Asset not found"}},"summary":"Get asset by ID","tags":["Assets"]},"patch":{"operationId":"AssetsController_updateAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssetDto"}}}},"responses":{"200":{"description":"Asset updated successfully"},"404":{"description":"Asset not found"}},"summary":"Update asset","tags":["Assets"]},"delete":{"operationId":"AssetsController_deleteAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Asset deleted successfully"},"404":{"description":"Asset not found"}},"summary":"Delete asset (soft delete)","tags":["Assets"]}},"/api/v1/assets/{id}/deployments":{"get":{"description":"Retrieves all blockchain deployments for a specific asset across different networks.","operationId":"AssetsController_getAssetDeployments","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Asset deployments retrieved successfully","content":{"application/json":{"schema":{"example":{"success":true,"data":[{"mintedAssetId":"550e8400-e29b-41d4-a716-446655440001","assetId":"550e8400-e29b-41d4-a716-446655440000","chain":"POLYGON","contractAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","tokenType":"TOKEN","deploymentTxHash":"0x123abc...","deployedAt":"2025-10-24T12:00:00.000Z","metadata":{"chainId":80002,"explorerUrl":"https://amoy.polygonscan.com/address/0x742d35..."}}]}}}}},"404":{"description":"Asset not found"}},"summary":"Get asset deployment history","tags":["Assets"]}},"/api/v1/assets/{id}/deploy":{"post":{"description":"Deploys an asset to the specified blockchain network via the factory contract. The asset must be in VERIFIED or PENDING_DISTRIBUTION status and have a complete distribution configuration.","operationId":"AssetsController_deployAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployAssetDto"}}}},"responses":{"201":{"description":"Asset successfully deployed to blockchain","content":{"application/json":{"schema":{"example":{"assetId":"550e8400-e29b-41d4-a716-446655440000","chain":"POLYGON","contractAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","transactionHash":"0x123abc...","explorerUrl":"https://amoy.polygonscan.com/address/0x742d35...","tokenType":"TOKEN","status":"DEPLOYED","deployedAt":"2025-10-24T12:00:00.000Z"}}}}},"400":{"description":"Invalid deployment parameters or asset not ready for deployment"},"404":{"description":"Asset not found"},"500":{"description":"Blockchain deployment failed"}},"summary":"Deploy asset to blockchain","tags":["Assets"]}},"/api/v1/assets/{assetId}/rights":{"post":{"operationId":"AssetRightsController_addRights","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"201":{"description":"Rights holder added successfully"}},"summary":"Add rights holder for an asset","tags":["Asset Rights"]},"get":{"operationId":"AssetRightsController_getRights","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Rights holders retrieved successfully"}},"summary":"Get all rights holders for an asset","tags":["Asset Rights"]}},"/api/v1/assets/{assetId}/rights/{rightsId}/verify":{"patch":{"operationId":"AssetRightsController_verifyRights","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}},{"name":"rightsId","required":true,"in":"path","description":"Rights ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Rights verification status updated"}},"summary":"Verify or reject rights holder","tags":["Asset Rights"]}},"/api/v1/assets/{assetId}/documents":{"post":{"operationId":"AssetDocumentsController_uploadDocument","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"201":{"description":"Document uploaded successfully, OCR processing started"},"400":{"description":"Invalid file or missing parameters"}},"summary":"Upload document with automatic OCR processing","tags":["Asset Documents"]},"get":{"operationId":"AssetDocumentsController_getDocuments","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Documents retrieved successfully"}},"summary":"Get all documents for an asset with OCR status","tags":["Asset Documents"]}},"/api/v1/assets/{assetId}/documents/{documentId}/ocr":{"post":{"operationId":"AssetDocumentsController_extractOcr","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}},{"name":"documentId","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}},{"name":"language","required":false,"in":"query","description":"OCR language (eng, spa, fra, deu)","schema":{"example":"eng","type":"string"}}],"responses":{"200":{"description":"OCR extraction completed successfully","content":{"application/json":{"schema":{"example":{"id":"doc-123","assetId":"asset-456","ocrStatus":"COMPLETED","extractedData":{"text":"Extracted document text...","confidence":94.5,"language":"eng","extractedAt":"2025-10-24T10:30:00Z","metadata":{"processingTimeMs":3200,"wordCount":150,"paragraphs":5}}}}}}},"400":{"description":"Unsupported file type or invalid document"},"404":{"description":"Document not found"}},"summary":"Extract text from document using OCR","tags":["Asset Documents"]},"get":{"operationId":"AssetDocumentsController_getOcrResults","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}},{"name":"documentId","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"responses":{"200":{"description":"OCR results retrieved successfully","content":{"application/json":{"schema":{"example":{"id":"doc-123","ocrStatus":"COMPLETED","extractedData":{"text":"Extracted document text...","confidence":94.5,"language":"eng","metadata":{"processingTimeMs":3200,"wordCount":150,"paragraphs":5}}}}}}},"404":{"description":"Document not found"}},"summary":"Get OCR extraction results for a document","tags":["Asset Documents"]}},"/api/v1/assets/{assetId}/documents/{documentId}/ipfs-backup":{"post":{"description":"Creates an immutable backup of the document on IPFS via Pinata. This is essential for legal documents to maintain tamper-proof records for compliance and audit trails.","operationId":"AssetDocumentsController_backupDocumentToIpfs","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}},{"name":"documentId","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Document backed up to IPFS successfully","content":{"application/json":{"schema":{"example":{"documentId":"doc-123","ipfsHash":"QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","ipfsUrl":"https://gateway.pinata.cloud/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","pinSize":245678,"timestamp":"2025-10-24T10:30:00.000Z","alreadyBackedUp":false}}}}},"400":{"description":"IPFS service not configured or invalid document"},"404":{"description":"Document not found"}},"summary":"Backup document to IPFS for immutable storage","tags":["Asset Documents"]}},"/api/v1/assets/{assetId}/documents/ipfs-backup-all":{"post":{"description":"Batch operation to backup all documents of an asset to IPFS. Useful for ensuring all legal documents are stored immutably.","operationId":"AssetDocumentsController_backupAllDocumentsToIpfs","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"All documents backed up to IPFS","content":{"application/json":{"schema":{"example":{"totalDocuments":5,"successfulBackups":5,"results":[{"documentId":"doc-123","ipfsHash":"QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","ipfsUrl":"https://gateway.pinata.cloud/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","pinSize":245678,"timestamp":"2025-10-24T10:30:00.000Z","alreadyBackedUp":false}]}}}}},"400":{"description":"IPFS service not configured"}},"summary":"Backup all documents for an asset to IPFS","tags":["Asset Documents"]}},"/api/v1/assets/{assetId}/documents/{documentId}/ipfs":{"get":{"description":"Retrieves the IPFS hash and URL for a document if it has been backed up to IPFS.","operationId":"AssetDocumentsController_getIpfsBackupInfo","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}},{"name":"documentId","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"responses":{"200":{"description":"IPFS backup information retrieved","content":{"application/json":{"schema":{"example":{"documentId":"doc-123","fileName":"title-deed.pdf","ipfsHash":"QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","ipfsUrl":"https://gateway.pinata.cloud/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG","isBackedUp":true}}}}},"404":{"description":"Document not found"}},"summary":"Get IPFS backup information for a document","tags":["Asset Documents"]}},"/api/v1/assets/{assetId}/distribution":{"post":{"description":"Configure how the asset will be distributed (token/NFT), pricing, supply, and royalties","operationId":"DistributionConfigController_createDistributionConfig","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDistributionConfigDto"}}}},"responses":{"201":{"description":"Distribution configuration created successfully"},"404":{"description":"Asset not found"},"409":{"description":"Distribution configuration already exists for this asset"}},"summary":"Create distribution configuration for an asset","tags":["Distribution Configuration"]},"get":{"description":"Retrieve the distribution configuration details","operationId":"DistributionConfigController_getDistributionConfig","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Distribution configuration retrieved successfully"},"404":{"description":"Distribution configuration not found"}},"summary":"Get distribution configuration for an asset","tags":["Distribution Configuration"]},"patch":{"description":"Update pricing, supply, royalties, or metadata for existing distribution configuration","operationId":"DistributionConfigController_updateDistributionConfig","parameters":[{"name":"assetId","required":true,"in":"path","description":"Asset ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDistributionConfigDto"}}}},"responses":{"200":{"description":"Distribution configuration updated successfully"},"404":{"description":"Distribution configuration not found"}},"summary":"Update distribution configuration","tags":["Distribution Configuration"]}}},"info":{"title":"PXL8 Assets API","description":"Real World Asset (RWA) Management & Tokenization API","version":"1.0","contact":{}},"tags":[{"name":"Assets","description":"Asset CRUD operations"},{"name":"Asset Rights","description":"Rights holder management and verification"},{"name":"Asset Documents","description":"Document upload and management"},{"name":"Distribution Configuration","description":"Token/NFT distribution configuration"}],"servers":[{"url":"https://api.pxl8.io","description":"Production API"},{"url":"http://localhost:3007","description":"Local Development"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreateAssetDto":{"type":"object","properties":{}},"UpdateAssetDto":{"type":"object","properties":{}},"DeployAssetDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain to deploy to","enum":["POLYGON","BASE","ETHEREUM","ARBITRUM","OPTIMISM","SOLANA"],"example":"POLYGON"},"chainId":{"type":"number","description":"Chain ID (80002 = Polygon Amoy, 137 = Polygon, 8453 = Base, 1 = Ethereum)","example":80002},"companyId":{"type":"string","description":"Company ID that owns the asset","example":"company_2abc123"},"ownerId":{"type":"string","description":"Owner Clerk user ID (will receive tokens/NFT ownership)","example":"user_2xyz789"},"royaltyReceiver":{"type":"string","description":"Wallet address to receive NFT royalties (required for NFTs, optional for tokens)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"}},"required":["chain","chainId","companyId","ownerId"]},"CreateDistributionConfigDto":{"type":"object","properties":{"assetId":{"type":"string","description":"ID of the asset to configure distribution for","example":"550e8400-e29b-41d4-a716-446655440000"},"assetStructure":{"type":"string","description":"Asset structure type (FUNGIBLE for tokens, NON_FUNGIBLE for NFTs)","enum":["FUNGIBLE","NON_FUNGIBLE"],"example":"FUNGIBLE"},"totalSupply":{"type":"string","description":"Total supply of tokens/NFTs (as string for large numbers)","example":"1000000"},"pricePerTokenUsd":{"type":"number","description":"Price per token/NFT in USD","example":10.5},"minInvestmentUsd":{"type":"number","description":"Minimum investment amount in USD","example":100},"maxInvestmentUsd":{"type":"number","description":"Maximum investment amount in USD","example":50000},"raiseGoalUsd":{"type":"number","description":"Fundraising goal in USD","example":1000000},"royaltyPercentage":{"type":"number","description":"Royalty percentage for secondary sales (0-100)","example":5},"tokenSymbol":{"type":"string","description":"Token symbol (required for FUNGIBLE assets, 2-10 uppercase alphanumeric)","example":"REAL"},"tokenName":{"type":"string","description":"Token name (required for FUNGIBLE assets)","example":"Real Estate Token"},"metadataUri":{"type":"string","description":"Metadata URI for token/NFT metadata","example":"ipfs://QmXyz123.../metadata.json"}},"required":["assetId","assetStructure","totalSupply","pricePerTokenUsd"]},"UpdateDistributionConfigDto":{"type":"object","properties":{"totalSupply":{"type":"string","description":"Updated total supply of tokens/NFTs","example":"2000000"},"pricePerTokenUsd":{"type":"number","description":"Updated price per token/NFT in USD","example":12},"minInvestmentUsd":{"type":"number","description":"Updated minimum investment amount in USD","example":200},"maxInvestmentUsd":{"type":"number","description":"Updated maximum investment amount in USD","example":100000},"raiseGoalUsd":{"type":"number","description":"Updated fundraising goal in USD","example":2000000},"royaltyPercentage":{"type":"number","description":"Updated royalty percentage (0-100)","example":7.5},"tokenSymbol":{"type":"string","description":"Updated token symbol (2-10 uppercase alphanumeric)","example":"REALT"},"tokenName":{"type":"string","description":"Updated token name","example":"Real Estate Investment Token"},"metadataUri":{"type":"string","description":"Updated metadata URI","example":"ipfs://QmAbc456.../metadata.json"}}}}}}