BCCCR API Documentation

Submit a platform registration application for BCCCR review.

{
  "name": "<applicant_name>",
  "email": "<applicant_email>",
  "password": "<password>",
  "password_confirmation": "<password>",
  "platform_name": "<platform_name>",
  "platform_address": "<business_address>",
  "tin_number": "<tax_id>",
  "platform_phone": "<phone_number>",
  "platform_email": "<platform_contact_email>",
  "bank_account_number": "<account_number>",
  "bank_routing_number": "<routing_number>",
  "bank_name": "<bank_name>",
  "api_endpoint": "<optional_api_endpoint>"
}

{
  "success": true,
  "message": "Platform registration submitted successfully. Your application will be reviewed by BCCCR administrators.",
  "data": {
    "platform_name": "<platform_name>",
    "status": "pending",
    "registration_date": "<timestamp>"
  }
}

• Application status will be 'pending' until reviewed by BCCCR administrators
• API key will be generated upon approval
• All business information is required for compliance and settlement processing

Check the status of a platform registration application.

{
  "success": true,
  "message": "Registration status retrieved",
  "data": {
    "platform_name": "<platform_name>",
    "status": "<pending|active|inactive>",
    "registration_date": "<timestamp>",
    "approved_at": "<timestamp>",
    "admin_notes": "<notes>"
  }
}

Get all pending platform applications (admin only).

{
  "success": true,
  "message": "Pending applications retrieved",
  "data": [
    {
      "id": <application_id>,
      "name": "<applicant_name>",
      "email": "<email>",
      "platform_name": "<platform_name>",
      "platform_address": "<address>",
      "tin_number": "<tax_id>",
      "platform_phone": "<phone>",
      "platform_email": "<contact_email>",
      "bank_name": "<bank>",
      "created_at": "<timestamp>",
      "admin_notes": "<notes>"
    }
  ]
}

Approve a platform application (admin only).

{
  "notes": "<optional_admin_notes>"
}

{
  "success": true,
  "message": "Platform application approved successfully",
  "data": {
    "platform_name": "<platform_name>",
    "status": "active",
    "approved_at": "<timestamp>",
    "api_key": "<generated_api_key>"
  }
}

Reject a platform application (admin only).

{
  "notes": "<rejection_reason>"
}

{
  "success": true,
  "message": "Platform application rejected",
  "data": {
    "platform_name": "<platform_name>",
    "status": "inactive"
  }
}

Register up to 250 contract hashes for a single publication.

{
  "ipfs_hash": "<IPFS hash for the publication>",
  "metadata_cid": "<IPFS CID for the metadata>",
  "contract_hashes": [
    "<contract_hash_1>",
    "<contract_hash_2>"
    // ... up to 250
  ]
}

• ipfs_hash (string, required): The IPFS hash for the publication (applies to all contracts in the batch)
• metadata_cid (string, required): The IPFS CID for the metadata (applies to all contracts in the batch)
• contract_hashes (array, required): Up to 250 unique contract hashes to register in one call

• All contract hashes must be unique within the request and not already registered in the system
• All contracts in the batch will share the same IPFS hash and metadata CID

{
  "success": true,
  "message": "Contracts registered successfully",
  "data": {
    "registered_count": <number>,
    "ipfs_hash": "<IPFS hash>",
    "metadata_cid": "<metadata CID>",
    "contract_hashes": [ ... ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contract_hashes": ["Contract hashes already exist: ..."]
  }
}

• Returns HTTP 201 on success, HTTP 422 on validation error
• Requires a valid API key in the X-API-Key header

curl -X POST http://localhost:8000/api/contracts/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"ipfs_hash":"QmTest123","metadata_cid":"QmMeta456","contract_hashes":["hash1","hash2"]}'

Validate a contract hash and return legitimacy and usage information.

{
  "contract_hash": "<contract_hash>"
}

• contract_hash (string, required): The contract hash to validate

{
  "success": true,
  "message": "Contract found",
  "data": {
    "contract_hash": "<contract_hash>",
    "status": "active",
    "ipfs_hash": "<IPFS hash>",
    "metadata_cid": "<metadata CID>",
    "originating_platform_id": <platform_id>,
    "originating_platform_name": "<platform name>",
    "registered_at": "<timestamp>"
  }
}

{
  "success": false,
  "message": "Contract not found",
  "data": null
}

• Returns HTTP 200 on success, HTTP 404 if not found or not active
• Requires a valid API key in the X-API-Key header

curl -X POST http://localhost:8000/api/contracts/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"hash1"}'

Revoke a contract. Only the publishing platform can revoke its own contracts.

{
  "reason": "<reason for revocation>"
}

• reason (string, optional): Reason for revocation (max 500 chars)

{
  "success": true,
  "message": "Contract revoked successfully",
  "data": {
    "contract_hash": "<contract_hash>",
    "status": "revoked",
    "revoked_at": "<timestamp>",
    "reason": "<reason>"
  }
}

{
  "success": false,
  "message": "Only the publishing platform can revoke this contract",
  "data": null
}

{
  "success": false,
  "message": "Contract is already revoked",
  "data": null
}

• Returns HTTP 200 on success, HTTP 403 if not authorized, HTTP 400 if already revoked, HTTP 404 if not found
• Requires a valid API key in the X-API-Key header

curl -X PUT http://localhost:8000/api/contracts/hash1/revoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"reason":"No longer valid"}'

Report a cross-platform sale to track royalty obligations between platforms.

{
  "contract_hash": "0x1234567890abcdef...",
  "buyer_wallet_address": "0xabcdef1234567890...",
  "sale_amount": 29.99,
  "royalty_amount": 2.99,
  "transaction_hash": "0x9876543210fedcba...",
  "metadata": {
    "payment_method": "credit_card",
    "currency": "USD",
    "platform_fee": 1.50
  },
  "sold_at": "2024-01-15T10:30:00Z"
}

• contract_hash (string): The contract hash of the content being sold
• sale_amount (numeric): Total sale amount in USD (minimum $0.01)
• royalty_amount (numeric): Royalty amount owed to author in USD

• buyer_wallet_address (string): Buyer's wallet address (max 42 characters)
• transaction_hash (string): Blockchain transaction hash
• metadata (object): Additional transaction metadata
• sold_at (datetime): When the sale occurred (defaults to current time)

• Contract hash must be registered and active in the system
• Sale amount must be at least $0.01
• Royalty amount cannot exceed sale amount
• Royalty amount cannot be negative

{
  "success": true,
  "message": "Sale reported successfully",
  "data": {
    "transaction_id": 123,
    "royalty_id": 456,
    "contract_hash": "0x1234567890abcdef...",
    "sale_amount": 29.99,
    "royalty_amount": 2.99,
    "sold_at": "2024-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contract_hash": ["Contract hash is not registered."],
    "royalty_amount": ["Royalty amount cannot exceed sale amount."]
  }
}

• Creates a transaction record linking the sale to the contract and platforms
• Creates a royalty record where the selling platform owes the originating platform
• Both records are created in a database transaction to ensure consistency
• Logs the sale for audit and settlement processing

• Returns HTTP 201 on success, HTTP 422 on validation error
• Requires a valid API key in the X-API-Key header

curl -X POST http://localhost:8000/api/sales \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"0x1234567890abcdef","sale_amount":29.99,"royalty_amount":2.99}'

Report content mirroring with IPFS locations to create a decentralized backup system.

{
  "contract_hash": "0x1234567890abcdef...",
  "mirrored_ipfs_hash": "QmMirroredContent123",
  "mirror_location": "ipfs-node-1",
  "access_count": 0,
  "mirrored_at": "2024-01-15T10:30:00Z"
}

• contract_hash (string): The contract hash of the content being mirrored
• mirrored_ipfs_hash (string): The IPFS hash where the content is mirrored (max 64 characters)

• mirror_location (string): IPFS node location/identifier
• access_count (integer): Number of times this mirror was accessed
• mirrored_at (datetime): When the mirror was created (defaults to current time)

• Contract hash must be registered and active in the system
• Mirrored IPFS hash cannot exceed 64 characters
• Access count cannot be negative

{
  "success": true,
  "message": "Content mirror created successfully",
  "data": {
    "mirror_id": 123,
    "contract_hash": "0x1234567890abcdef...",
    "ipfs_hash": "QmOriginalContent",
    "mirrored_ipfs_hash": "QmMirroredContent123",
    "mirror_location": "ipfs-node-1",
    "access_count": 0,
    "mirrored_at": "2024-01-15T10:30:00Z",
    "action": "created"
  }
}

• Creates or updates a mirror record for the platform and IPFS hash
• If a mirror already exists for the same platform and IPFS hash, it updates the existing record
• Logs the mirror for audit and content discovery
• Enables decentralized backup through normal usage patterns

• Returns HTTP 201 on success, HTTP 422 on validation error
• Requires a valid API key in the X-API-Key header

curl -X POST http://localhost:8000/api/mirrors \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"0x1234567890abcdef","mirrored_ipfs_hash":"QmMirroredContent123"}'

Retrieve all mirrors for a specific IPFS hash to find available content locations.

{
  "success": true,
  "message": "Mirrors retrieved successfully",
  "data": {
    "ipfs_hash": "QmOriginalContent",
    "mirrors": [
      {
        "mirror_id": 123,
        "mirrored_ipfs_hash": "QmMirroredContent123",
        "mirror_location": "ipfs-node-1",
        "platform_name": "Platform A",
        "access_count": 5,
        "last_accessed_at": "2024-01-15T10:30:00Z",
        "mirrored_at": "2024-01-10T09:00:00Z"
      }
    ],
    "total_mirrors": 1
  }
}

• Returns HTTP 200 on success, HTTP 500 on server error
• Requires a valid API key in the X-API-Key header

curl -X GET http://localhost:8000/api/mirrors/QmOriginalContent \
  -H "X-API-Key: <your-api-key>"