BCCCR Docs

User Tools

Site Tools

Trace: • api
wiki:api

Table of Contents

BCCCR API Documentation

Platform Registration

POST /api/platforms/register

Submit a platform registration application for BCCCR review.

Request Body

{
  "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>"
}

Response (Success)

{
  "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>"
  }
}

Notes

  • 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

GET /api/platforms/status/{email}

Check the status of a platform registration application.

Response (Success)

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

GET /api/admin/applications/pending

Get all pending platform applications (admin only).

Response (Success)

{
  "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>"
    }
  ]
}

POST /api/admin/applications/{id}/approve

Approve a platform application (admin only).

Request Body

{
  "notes": "<optional_admin_notes>"
}

Response (Success)

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

POST /api/admin/applications/{id}/reject

Reject a platform application (admin only).

Request Body

{
  "notes": "<rejection_reason>"
}

Response (Success)

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

POST /api/contracts/register

Register up to 250 contract hashes for a single publication.

Request Body

{
  "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

Validation Rules

  • 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

Response (Success)

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

Response (Validation Error)

{
  "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

Example cURL

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"]}'

POST /api/contracts/validate

Validate a contract hash and return legitimacy and usage information.

Request Body

{
  "contract_hash": "<contract_hash>"
}
  • contract_hash (string, required): The contract hash to validate

Response (Success)

{
  "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>"
  }
}

Response (Not Found or Inactive)

{
  "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

Example cURL

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"}'

PUT /api/contracts/{hash}/revoke

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

Request Body

{
  "reason": "<reason for revocation>"
}
  • reason (string, optional): Reason for revocation (max 500 chars)

Response (Success)

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

Response (Not Allowed or Already Revoked)

{
  "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

Example cURL

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"}'
Sales Reporting

POST /api/sales

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

Request Body

{
  "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"
}

Required Fields

  • 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

Optional Fields

  • 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)

Validation Rules

  • 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

Response (Success)

{
  "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"
  }
}

Response (Validation Error)

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

Business Logic

  • 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

Example cURL

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}'
Content Mirroring

POST /api/mirrors

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

Request Body

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

Required Fields

  • 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)

Optional Fields

  • 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)

Validation Rules

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

Response (Success)

{
  "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"
  }
}

Business Logic

  • 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

Example cURL

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"}'

GET /api/mirrors/{ipfsHash}

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

Response (Success)

{
  "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

Example cURL

curl -X GET http://localhost:8000/api/mirrors/QmOriginalContent \
  -H "X-API-Key: <your-api-key>"
wiki/api.txt · Last modified: by 127.0.0.1