# Audicin for Apps API – Complete Usage Guide

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

| HTTP Status | Meaning |
|  --- | --- |
| 401 | Missing or invalid API key |
| 402 | Subscription inactive |
| 403 | License, quota, or access restriction |


## 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


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

## Browsing the Catalogue

### List Songs


```
GET /tenants/songs
```

#### Query Parameters

| Name | Description |
|  --- | --- |
| page | Page number |
| size | Page size |
| title | Filter by song title |
| mainGenre | Filter by main category |
| secondaryGenre | Filter by secondary category |


## 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


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

| Field | Meaning |
|  --- | --- |
| `status` | Current operational state of the license |
| `validFrom` | Earliest timestamp when the license becomes usable |
| `validTo` | Expiration timestamp |
| `createdAt` | When the license was issued |


### License Status Semantics

A license is **usable only if all conditions are met**:


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

#### Possible Statuses

| Status | Meaning |
|  --- | --- |
| ACTIVE | License is valid and usable |
| SUSPENDED | Temporarily disabled (quota enforcement, downgrade, payment issues) |
| REVOKED | License revoked by admin |


### Check License for a Specific Song


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

#### Example Response


```json
{
  "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**:


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


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

| Capability | Allowed |
|  --- | --- |
| Browse songs & metadata | Yes |
| Browse artists | Yes |
| Preview audio | Yes (no license required) |
| Stream full songs | License required |
| Download images | Yes |


End of **Audicin for Apps API Guide**