API Reference

Entitlements API

Verified entitlement concepts and the current public delivery endpoint that authorizes files from active customer entitlements.

Start with getting started Explore API docs

SoundSync

Verified endpoints

Only endpoint-backed behavior is documented here.

GET /api/delivery/entitlements/:entitlementId/files/:fileIndex

Authorizes an active customer entitlement and redirects to short-lived signed R2 delivery.

Auth: Customer library/download token
Scope: Entitlement, customer identity, product, source/sourceId, expansion rule, and file-index scoped.
Request fields: query token: string
query download_token: string
query libraryToken: string
Returns: 302 redirect to a short-lived signed R2 download URL, or JSON error for missing token, invalid entitlement/file index, inactive entitlement, expansion block, missing file, upstream failure, or delivery failure.
Side effects: Logs delivery and updates legacy serial download count when the entitlement metadata includes a serialId.
Notes: This endpoint keeps authorization and download accounting in SoundSync while R2 serves the file bytes directly. fileIndex is zero-based. Token ownership, active entitlement, expansion rules and file existence are checked before redirect. Do not persist the storage URL as a permanent download. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.

Request, response and error reference

Query and header parameters

[
  {
    "name": "token",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  },
  {
    "name": "download_token",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  },
  {
    "name": "libraryToken",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  }
]

No request body fields are read by this operation.

HTTP 302 response headers

{
  "Location": {
    "schema": {
      "type": "string",
      "format": "uri"
    },
    "description": "Short-lived authorized private download URL."
  }
}

Documented failures: 400, 500, 401, 503.

Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED.

POST /api/products/:id/delivery-files

Attach product delivery-file metadata from the developer product setup flow.

Auth: Account Bearer JWT
Scope: Developer-owned product setup.
Request fields: url: string (required)
name: string
size_gb: number
Returns: Product setup response controlled by product setup service.
Side effects: May update delivery-file configuration for the product. Not safe for read-only screenshot capture.
Notes: Attaches one file; a nested file object is also accepted. href aliases url; size aliases size_gb and is measured in GB. Use completed managed uploads. External delivery URLs must go through Upload by Link; signed, tokenized and raw private-storage URLs are rejected.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "size_gb": {
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "product": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 1
        },
        "name": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "shortDescription": {
          "type": [
            "string",
            "null"
          ]
        },
        "price": {
          "type": "number"
        },
        "salePrice": {
          "type": [
            "number",
            "null"
          ]
        },
        "regularPrice": {
          "type": "number"
        },
        "displayPrice": {
          "type": "number"
        },
        "priceDisplay": {
          "type": "string"
        },
        "regularPriceDisplay": {
          "type": "string"
        },
        "salePriceDisplay": {
          "type": [
            "string",
            "null"
          ]
        },
        "isOnSale": {
          "type": "boolean"
        },
        "currency": {
          "type": "string"
        },
        "imageUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "coverImage": {
          "type": [
            "string",
            "null"
          ]
        },
        "developerId": {
          "type": "integer",
          "minimum": 1
        },
        "developerName": {
          "type": "string"
        },
        "developer": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "minimum": 1
            },
            "name": {
              "type": "string"
            },
            "slug": {
              "type": [
                "string",
                "null"
              ]
            },
            "profileUrl": {
              "type": [
                "string",
                "null"
              ]
            },
            "verified": {
              "type": "boolean"
            }
          },
          "additionalProperties": true
        },
        "productType": {
          "type": "string"
        },
        "productTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "url": {
          "type": "string"
        },
        "subscriptionEnabled": {
          "type": "boolean"
        },
        "billingInterval": {
          "type": [
            "string",
            "null"
          ]
        },
        "checkoutEligible": {
          "type": "boolean"
        },
        "capabilities": {
          "type": "object",
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        },
        "requiresActivation": {
          "type": "boolean"
        },
        "supportsSerials": {
          "type": "boolean"
        },
        "supportsDownloads": {
          "type": "boolean"
        },
        "marketplaceAsset": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        }
      },
      "additionalProperties": true
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "size_gb": {
            "type": "number"
          }
        },
        "additionalProperties": true
      }
    },
    "setupStatus": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "setup_status": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500, 503.

SoundSync

Lifecycle sources

The implementation creates or validates entitlements from these sources.

Source	Creates or updates entitlement?	Public API surface	Notes
Purchase checkout	Yes	/api/checkout/product and Stripe webhook flows	Checkout/webhook implementation creates order and subscription-linked access; docs here do not expose internal webhook handlers as public customer APIs.
Serial activation/redeem	Yes	Licensing and redeem flows	Legacy serial download paths bridge to entitlements when possible.
Subscription checkout	Yes	Subscription checkout and Stripe subscription webhooks	Beta-gated; states are documented in Subscriptions API.
Partner external order	Yes	/api/partner/v1/orders	Partner API order fulfillment can enqueue order.fulfilled webhooks and create fulfillment material.
Manual grant	Implementation-dependent	Developer dashboard, not a verified public endpoint in this pass	Do not publish a manual-grant API until a route-level contract is verified.

Revocation and refunds

Refund, dispute, subscription expiration, serial revocation, and partner revoke flows can make access inactive. Clients must not assume a stored entitlement remains downloadable; always call the delivery endpoint with a current library token.