🔌 API Documentation

The BLAQclouds DRM-as-a-Service API provides programmatic access to content licensing, streaming, billing, and forensic watermark analysis. All requests require a Bearer API key.

🔐 Authentication 📂 Catalog 🎬 Streaming 💳 Billing 🔬 Forensics ⚠️ Error Codes

Quick Start

All API requests must include an Authorization header with a Bearer token:

Authorization: Bearer blk_live_yourkeyhere

Every response includes rate-limit headers:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset:     1722520800  (epoch seconds)

🔐 Authentication

3 endpoints

GET/api/v1/auth/verifyscope: (any)

Verify the API key and return organization details, plan, scopes, and rate limits.

Request:

curl -X GET https://api.blaqclouds.io/api/v1/auth/verify \
  -H "Authorization: Bearer blk_live_yourkeyhere"

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Media",
    "email": "ops@acme.com",
    "walletAddress": "0x1234...",
    "plan": "professional",
    "apusdBalance": 50.00,
    "isActive": true
  },
  "plan": {
    "name": "professional",
    "basePriceApusd": 49,
    "pricePerStream": 0.005,
    "watermarkingIncluded": true
  },
  "scopes": ["catalog", "stream", "billing", "forensics"],
  "rateLimits": { "perHour": 1000, "monthlyStreamLimit": 50000 }
}

POST/api/v1/auth/registerscope: (open)

Request:

curl -X POST https://api.blaqclouds.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Media",
    "email": "ops@acme.com",
    "plan": "professional",
    "walletAddress": "0x1234..."
  }'

Response:

{
  "organizationId": "uuid",
  "apiKey": "blk_live_abc123...",
  "scopes": ["catalog", "stream", "billing"],
  "message": "Organization registered. Save your API key."
}

POST/api/v1/auth/rotatescope: (any)

Rotate the API key (invalidates the old key immediately).

Request:

curl -X POST https://api.blaqclouds.io/api/v1/auth/rotate \
  -H "Authorization: Bearer blk_live_oldkey"

Response:

{
  "apiKey": "blk_live_newkey123...",
  "message": "Key rotated. Old key is now invalid."
}

📂 Catalog

2 endpoints

GET/api/v1/catalogscope: catalog

List all content the organization is licensed to access (videos + music).

Request:

curl -X GET https://api.blaqclouds.io/api/v1/catalog \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "content": [
    {
      "id": "content-uuid",
      "title": "Sample Video",
      "type": "video",
      "duration": 180,
      "resolution": "1080p",
      "thumbnail": "https://ipfs.io/...",
      "previewUrl": "https://ipfs.io/..."
    },
    {
      "id": "track-uuid",
      "title": "Sample Track",
      "type": "music",
      "duration": 240,
      "thumbnail": "https://ipfs.io/..."
    }
  ]
}

GET/api/v1/catalog/{contentId}scope: catalog

Get details for a specific content item.

Request:

curl -X GET https://api.blaqclouds.io/api/v1/catalog/content-uuid \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "id": "content-uuid",
  "title": "Sample Video",
  "type": "video",
  "duration": 180,
  "resolution": "1080p",
  "thumbnail": "https://ipfs.io/...",
  "hlsPlaylist": "https://ipfs.io/..."
}

🎬 Streaming

5 endpoints

POST/api/v1/stream/{contentId}scope: stream

Create a streaming session. Returns a playlist URL, binary_id for watermark tracking, and expiry.

Request:

curl -X POST https://api.blaqclouds.io/api/v1/stream/content-uuid \
  -H "Authorization: Bearer blk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "viewerId": "optional-uuid" }'

Response:

{
  "sessionId": "session-uuid",
  "playlistUrl": "/api/v1/stream/content-uuid/playlist?session=session-uuid",
  "binaryId": "0101010110100101...",
  "expiresAt": "2026-08-02T12:00:00.000Z"
}

GET/api/v1/stream/{contentId}/playlist?session=xxxscope: stream

Fetch the HLS playlist. For watermarked content, segment URLs are rewritten through the proxy.

Request:

curl -X GET "https://api.blaqclouds.io/api/v1/stream/content-uuid/playlist?session=session-uuid" \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXTINF:10.0,
/api/v1/stream/content-uuid/segment/0?session=session-uuid
#EXTINF:10.0,
/api/v1/stream/content-uuid/segment/1?session=session-uuid
#EXT-X-ENDLIST

GET/api/v1/stream/{contentId}/segment/{seg}?session=xxxscope: stream

Fetch a watermarked HLS segment (A/B variant based on binary_id bit).

Request:

curl -X GET "https://api.blaqclouds.io/api/v1/stream/content-uuid/segment/0?session=session-uuid" \
  -H "Authorization: Bearer blk_live_yourkey" \
  -o segment0.ts

Response:

Binary .ts segment data (application/vnd.apple.mpegurl or video/mp2t)

DELETE/api/v1/stream/{sessionId}scope: stream

End a streaming session (marks it as inactive).

Request:

curl -X DELETE https://api.blaqclouds.io/api/v1/stream/session-uuid \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{ "success": true }

GET/api/v1/stream/sessions/{sessionId}scope: stream

Get stream session details (binary_id, bytes served, active status).

Request:

curl -X GET https://api.blaqclouds.io/api/v1/stream/sessions/session-uuid \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "id": "session-uuid",
  "contentId": "content-uuid",
  "viewerId": "viewer-uuid",
  "binaryId": "0101010110...",
  "isActive": true,
  "bytesServed": 5242880,
  "expiresAt": "2026-08-02T12:00:00.000Z",
  "createdAt": "2026-08-01T12:00:00.000Z"
}

💳 Billing

5 endpoints

GET/api/v1/billing/usagescope: billing

Get current billing period usage (total streams, bytes, amount due, balance).

Request:

curl -X GET https://api.blaqclouds.io/api/v1/billing/usage \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "totalStreams": 1234,
  "totalBytes": 53687091200,
  "amountDue": 6.17,
  "balance": 50.00,
  "pendingCharges": 2.50,
  "periodStart": "2026-08-01T00:00:00.000Z",
  "periodEnd": "2026-09-01T00:00:00.000Z"
}

GET/api/v1/billing/invoicesscope: billing

List invoice history for the organization.

Request:

curl -X GET https://api.blaqclouds.io/api/v1/billing/invoices \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "invoices": [
    {
      "id": "inv-uuid",
      "periodStart": "2026-07-01T00:00:00.000Z",
      "periodEnd": "2026-08-01T00:00:00.000Z",
      "totalStreams": 5000,
      "amountApusd": 25.00,
      "amountUsd": 2.50,
      "paymentStatus": "paid",
      "paidAt": "2026-08-01T12:00:00.000Z"
    }
  ]
}

GET/api/v1/billing/balancescope: billing

Get APUSD balance and pending charges.

Request:

curl -X GET https://api.blaqclouds.io/api/v1/billing/balance \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "apusdBalance": 50.00,
  "pendingCharges": 2.50,
  "availableBalance": 47.50
}

POST/api/v1/billing/fundscope: billing

Fund the APUSD balance via Stripe or APUSD payment.

Request:

curl -X POST https://api.blaqclouds.io/api/v1/billing/fund \
  -H "Authorization: Bearer blk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50.00, "method": "stripe", "stripePaymentIntentId": "pi_xxx" }'

Response:

{
  "success": true,
  "newBalance": 100.00,
  "transactionId": "txn-uuid"
}

POST/api/v1/billing/autopayscope: billing

Configure automatic payment method for invoices.

Request:

curl -X POST https://api.blaqclouds.io/api/v1/billing/autopay \
  -H "Authorization: Bearer blk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "method": "stripe", "stripeCustomerId": "cus_xxx" }'

Response:

{
  "success": true,
  "autopayEnabled": true,
  "method": "stripe"
}

🔬 Forensics

3 endpoints

POST/api/v1/forensics/analyzescope: forensics

Analyze a leaked file (video or music) for forensic watermarks. Extracts the binary_id, traces it to the viewer, and returns the evidence chain. Video uses DTCWT frame watermark decoding; music uses STFT cross-correlation via the GPU machine.

Request:

curl -X POST https://api.blaqclouds.io/api/v1/forensics/analyze \
  -H "Authorization: Bearer blk_live_yourkey" \
  -F "file=@leaked-video.mp4" \
  -F "contentId=content-uuid" \
  -F "contentType=video"

Response:

{
  "binaryId": "01010101101001010110...",
  "confidence": 38,
  "classification": "strong_match",
  "contentType": "video",
  "matchedSession": {
    "organization": "Acme Media",
    "apiKey": "blk_live_abcd",
    "viewerId": "viewer-uuid",
    "walletAddress": "0x1234...",
    "ipAddress": "203.0.113.50",
    "sessionDate": "2026-07-28T14:30:00.000Z",
    "confidence": 40,
    "sessionId": "session-uuid",
    "binaryId": "01010101101001010110..."
  },
  "evidenceChain": {
    "apiKey": { "id": "key-uuid", "prefix": "blk_live_abcd", "name": "Production Key" },
    "organization": { "id": "org-uuid", "name": "Acme Media", "email": "ops@acme.com" },
    "wallet": { "address": "0x1234...", "hasOwnWallet": true },
    "session": {
      "id": "session-uuid",
      "binaryId": "01010101101001010110...",
      "isActive": false,
      "bytesServed": 52428800,
      "createdAt": "2026-07-28T14:30:00.000Z",
      "expiresAt": "2026-07-29T14:30:00.000Z"
    },
    "viewer": {
      "viewerId": "viewer-uuid",
      "ipAddress": "203.0.113.50",
      "userAgent": "Mozilla/5.0..."
    },
    "content": {
      "contentId": "content-uuid",
      "contentType": "video",
      "title": "Premium Content"
    }
  },
  "caseId": "case-uuid"
}

GET/api/v1/forensics/casesscope: forensics

List forensic cases for the organization (most recent first).

Request:

curl -X GET https://api.blaqclouds.io/api/v1/forensics/cases \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "cases": [
    {
      "id": "case-uuid",
      "contentId": "content-uuid",
      "contentType": "video",
      "binaryId": "0101010110100101...",
      "confidence": 38,
      "classification": "strong_match",
      "status": "completed",
      "matchedOrganization": "Acme Media",
      "matchedViewerId": "viewer-uuid",
      "matchedIpAddress": "203.0.113.50",
      "matchedWallet": "0x1234...",
      "matchedSessionDate": "2026-07-28T14:30:00.000Z",
      "createdAt": "2026-08-01T10:00:00.000Z"
    }
  ],
  "total": 1
}

GET/api/v1/forensics/cases/{caseId}scope: forensics

Get forensic case details with the full evidence chain (API key → org → wallet → session → viewer → IP → date).

Request:

curl -X GET https://api.blaqclouds.io/api/v1/forensics/cases/case-uuid \
  -H "Authorization: Bearer blk_live_yourkey"

Response:

{
  "case": {
    "id": "case-uuid",
    "contentId": "content-uuid",
    "contentType": "video",
    "binaryId": "0101010110100101...",
    "confidence": 38,
    "classification": "strong_match",
    "status": "completed",
    "matchedOrganization": "Acme Media",
    "matchedWallet": "0x1234...",
    "createdAt": "2026-08-01T10:00:00.000Z"
  },
  "evidenceChain": {
    "apiKey": { "id": "key-uuid", "prefix": "blk_live_abcd", "name": "Production Key" },
    "organization": { "id": "org-uuid", "name": "Acme Media", "email": "ops@acme.com" },
    "wallet": { "address": "0x1234...", "hasOwnWallet": true },
    "session": {
      "id": "session-uuid",
      "binaryId": "0101010110100101...",
      "bytesServed": 52428800,
      "createdAt": "2026-07-28T14:30:00.000Z"
    },
    "viewer": {
      "viewerId": "viewer-uuid",
      "ipAddress": "203.0.113.50"
    },
    "content": {
      "contentId": "content-uuid",
      "contentType": "video",
      "title": "Premium Content"
    }
  }
}

⚠️ Error Codes

All errors follow a consistent JSON format.

Error response format:

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Code	HTTP Status	Error Message	Description
INVALID_API_KEY	401	Invalid API key	API key is missing, invalid, or revoked.
INSUFFICIENT_SCOPE	403	Insufficient permissions	API key lacks the required scope for this endpoint.
LICENSE_REQUIRED	403	License required	No active content license for the requested content.
INSUFFICIENT_BALANCE	402	Insufficient balance	APUSD balance is too low to complete the request.
NOT_FOUND	404	Content not found	The requested resource was not found.
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded	Too many requests in the current hour window.
BAD_REQUEST	400	Bad request	Request body or parameters are missing or invalid.
INTERNAL_ERROR	500	Internal error	An unexpected server error occurred.

BLAQclouds DRM-as-a-Service API · Base URL: https://api.blaqclouds.io

← Back to BLAQclouds