Audicin for Apps API – Complete Usage Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This document describes how tenants (Audicin for Apps API partners) interact with the Audicin for Apps API to:

• Browse the music catalogue
• Understand song categorisation
• Preview songs (no license required)
• Check licenses
• Stream full songs (license required)

Authentication

All tenant endpoints require an API key.

Header

X-API-KEY: <your-api-key>

Common Authentication Errors

Core Concepts

Songs

A Song represents a licensable audio track.

• Songs can be listed and inspected freely
• Streaming the full audio requires a valid license
• Preview audio is always allowed (with an active subscription)

Each song includes:

• Metadata (title, duration, description)
• One or more artists
• Categories (main + secondary)
• Media (cover image, preview audio)

Categories (Discovery Model)

Each song is classified using two category dimensions.

Main Category (Brainwave)

Main Category (Brainwave) - Represents the binaural beat band embedded throughout the song

Order:

1. Delta
2. Theta
3. Alpha
4. Beta
5. Gamma

Secondary Category (Purpose)

Represents the context or activity where the song is used.

Purposes:

• Work
• Focus
• Relax
• Creativity
• Commute
• Mood boost
• Sleep

Example Categories on a Song

"categories": [
  { "id": "60V2DA5FZG88KTXC9ZVE6ZA2M7", "name": "Beta", "type": "main" },
  { "id": "1E1YPC105Y81AVTKRY1SSS1151", "name": "Work", "type": "secondary" }
]

Browsing the Catalogue

List Songs

GET /tenants/songs

Query Parameters

Preview Audio (No License Required)

GET /tenants/stream/songPreview/{songId}

Rules:

• API key required
• Active subscription required
• No license required
• Returns a temporary presigned URL

Licenses

A License represents a time-bound permission for a tenant to stream a specific song.

Licenses are:

• Song-scoped
• Time-bound
• State-based (ACTIVE, SUSPENDED,REVOKED, etc.)

List Tenant Licenses

GET /tenants/myLicenses?page=0&size=10

Example Response

{
  "content": [
    {
      "id": "109RCXQJ0Y8SXR896KW6BB1Z4Q",
      "song": {
        "songId": "6CJ5BGSCAQ8FC8CPGV8MMK0STT",
        "title": "Song no 19",
        "seconds": 154
      },
      "status": "ACTIVE",
      "validFrom": "2025-12-23T03:18:58Z",
      "validTo": "2026-01-23T03:02:58Z",
      "createdAt": "2025-12-23T03:16:39.553532Z"
    }
  ],
  "page": {
    "size": 10,
    "number": 0,
    "totalElements": 35,
    "totalPages": 4
  }
}

License Fields Explained

License Status Semantics

A license is usable only if all conditions are met:

status == ACTIVE
AND now >= validFrom
AND now <= validTo

Possible Statuses

Check License for a Specific Song

GET /tenants/myLicenses/check-access?songId={songId}&onlyValid=true

Example Response

{
  "id": "109RCXQJ0Y8SXR896KW6BB1Z4Q",
  "song": {
    "songId": "6CJ5BGSCAQ8FC8CPGV8MMK0STT",
    "title": "Song no 19",
    "seconds": 154
  },
  "status": "ACTIVE",
  "validFrom": "2025-12-23T03:18:58Z",
  "validTo": "2026-01-23T03:02:58Z",
  "createdAt": "2025-12-23T03:16:39.553532Z"
}

Full Song Streaming (License Required)

GET /tenants/stream/song/{songId}

Rules:

• API key required
• Active subscription required
• Valid license required
• License is checked in real time
• Returns a temporary presigned URL

Check License for a Song

GET /tenants/myLicenses/check-access?songId={songId}

Full Song Streaming (License Required)

Access Rules

• API key required (X-API-KEY)
• Active tenant subscription required
• Valid ACTIVE license for the song required
• Expired, revoked, or suspended licenses are rejected

Streaming Response

When access is granted, the API returns a temporary streaming descriptor:

{
  "songId": "6CJ5BGSCAQ8FC8CPGV8MMK0STT",
  "title": "Song no 19",
  "url": "https://example.com/...signed-url...",
  "method": "GET",
  "expiresInSeconds": 180,
  "songDuration": 154,
  "objectData": {
    "metadata": {},
    "size": 103070,
    "contentType": "audio/mpeg"
  }
}

Presigned URL Behavior

URLs are short-lived and single-purpose

• URLs are tenant-scoped

• URLs cannot be reused after expiration

• Playback should begin immediately

• Clients must not cache the URL

If playback is restarted, the client must request a new streaming URL.

Media Access

Download Images (Covers / Artist Avatars)

GET /tenants/downloadable/images/{mediaId}

Rules:

• Only image media allowed - avatar(artist), cover(song)
• Returns a presigned download URL

NOTE: the media can be queried with id existing on the coverMedia and avatarEntities of songs and artists respectively

Example Response

{
  "objectName": "140_a.png",
  "mediaId": "76Z8XE4PC098CS8TS6TVJK9481",
  "url": "http://localhost:9006/audicin-tracks/images/140_a.png"
}

End-to-End Tenant Flow (User Story)

1. Tenant authenticates using API key
2. Tenant browses songs in the catalogue
3. Tenant filters by:
   • Main category (brainwave: Delta, Theta, Alpha, Beta, Gamma)
   • Secondary category (purpose: Work, Focus, Relax, Creativity, Commute, Mood boost, Sleep)
4. Tenant previews songs without a license
5. Tenant acquires licenses via the developer portal
6. Tenant checks license availability
7. Tenant streams full songs using licensed access

Guarantees

• Catalogue access is open
• Preview audio is free (with subscription)
• Full audio is strictly license-enforced
• License suspension and expiry are enforced server-side
• Media delivery uses secure presigned URLs

Scope Summary

End of Audicin for Apps API Guide