### Authentication API

Source: https://registry.dev.reviz.dev/api/docs/index

Endpoints for user registration, login, authentication, and profile management.

```APIDOC
## POST /api/v1/auth/register

### Description
Register a new user.

### Method
POST

### Endpoint
/api/v1/auth/register

### Parameters
#### Request Body
- **username** (string) - Required - The desired username.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Response
#### Success Response (201)
- **message** (string) - A success message.
- **userId** (string) - The ID of the newly registered user.

#### Response Example
```json
{
  "message": "User registered successfully",
  "userId": "usr_123abc"
}
```
```

```APIDOC
## POST /api/v1/auth/login

### Description
Login a user and return an authentication token.

### Method
POST

### Endpoint
/api/v1/auth/login

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Response
#### Success Response (200)
- **token** (string) - The JWT authentication token.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```

```APIDOC
## POST /api/v1/auth/make-admin

### Description
Make a user an admin. This endpoint is restricted to administrators.

### Method
POST

### Endpoint
/api/v1/auth/make-admin

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user to make an admin.

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the user is now an admin.

#### Response Example
```json
{
  "message": "User has been promoted to admin."
}
```
```

```APIDOC
## POST /api/v1/auth/firebase

### Description
Authenticate a user using a Firebase ID token.

### Method
POST

### Endpoint
/api/v1/auth/firebase

### Parameters
#### Request Body
- **firebaseToken** (string) - Required - The Firebase ID token.

### Response
#### Success Response (200)
- **token** (string) - The JWT authentication token.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```

```APIDOC
## GET /api/v1/auth/profile

### Description
Get the profile information for the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/profile

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **userId** (string) - The user's ID.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.
- **isAdmin** (boolean) - Indicates if the user is an administrator.

#### Response Example
```json
{
  "userId": "usr_123abc",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "isAdmin": false
}
```
```

```APIDOC
## GET /api/v1/auth/verify

### Description
Verify the validity of a JWT token.

### Method
GET

### Endpoint
/api/v1/auth/verify

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for verification.

### Response
#### Success Response (200)
- **isValid** (boolean) - True if the token is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok

### Description
Initiates the TikTok OAuth callback process.

### Method
GET

### Endpoint
/api/v1/auth/tiktok

### Parameters
#### Query Parameters
- **code** (string) - Required - The authorization code received from TikTok.
- **state** (string) - Optional - The state parameter for CSRF protection.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message upon successful callback.

#### Response Example
```json
{
  "message": "TikTok OAuth callback processed successfully."
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/avatar

### Description
Proxies TikTok avatar URLs.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/avatar

### Parameters
#### Query Parameters
- **url** (string) - Required - The TikTok avatar URL to proxy.

### Response
#### Success Response (200)
- **image/png** or **image/jpeg** - The avatar image data.

#### Response Example
(Binary image data)
```

```APIDOC
## GET /api/v1/auth/tiktok/config

### Description
Provides TikTok Configuration Diagnostic information.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/config

### Response
#### Success Response (200)
- **configDetails** (object) - Details about the TikTok configuration.

#### Response Example
```json
{
  "configDetails": {
    "clientId": "your_client_id",
    "redirectUri": "your_redirect_uri"
  }
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/test-secrets

### Description
Tests access to TikTok Secret Manager.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/test-secrets

### Response
#### Success Response (200)
- **status** (string) - The status of the secret manager access test.

#### Response Example
```json
{
  "status": "Secret manager access successful."
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/debug

### Description
Debugs the TikTok Authentication Flow.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/debug

### Response
#### Success Response (200)
- **debugInfo** (object) - Detailed information about the debug session.

#### Response Example
```json
{
  "debugInfo": {
    "step": "initialization",
    "message": "Starting TikTok auth flow."
  }
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/test-auth-flow

### Description
Tests the TikTok Authentication Flow step by step.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/test-auth-flow

### Response
#### Success Response (200)
- **testResults** (array) - An array of test results for each step.

#### Response Example
```json
{
  "testResults": [
    {"step": "OAuth initiation", "status": "passed"},
    {"step": "Token exchange", "status": "passed"}
  ]
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/test-mock-auth

### Description
Tests TikTok Authentication using mock data.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/test-mock-auth

### Response
#### Success Response (200)
- **mockAuthStatus** (string) - The status of the mock authentication test.

#### Response Example
```json
{
  "mockAuthStatus": "Mock authentication successful."
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/oauth-url

### Description
Retrieves the TikTok OAuth URL for testing client credentials.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/oauth-url

### Response
#### Success Response (200)
- **oauthUrl** (string) - The generated TikTok OAuth URL.

#### Response Example
```json
{
  "oauthUrl": "https://www.tiktok.com/auth/authorize?client_id=..."
}
```
```

```APIDOC
## GET /api/v1/auth/tiktok/test-credentials

### Description
Tests TikTok client credentials.

### Method
GET

### Endpoint
/api/v1/auth/tiktok/test-credentials

### Response
#### Success Response (200)
- **credentialStatus** (string) - The status of the client credential test.

#### Response Example
```json
{
  "credentialStatus": "Client credentials are valid."
}
```
```

```APIDOC
## GET /api/v1/auth/connect/tiktok

### Description
Connects a TikTok account to an existing Firebase user.

### Method
GET

### Endpoint
/api/v1/auth/connect/tiktok

### Parameters
#### Query Parameters
- **firebaseToken** (string) - Required - The Firebase token of the user.
- **tiktokCode** (string) - Required - The authorization code from TikTok.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "message": "TikTok account connected successfully."
}
```
```

```APIDOC
## GET /api/v1/auth/connect/tiktok/callback

### Description
Handles the TikTok connect callback, establishing the canonical path.

### Method
GET

### Endpoint
/api/v1/auth/connect/tiktok/callback

### Parameters
#### Query Parameters
- **code** (string) - Required - The authorization code from TikTok.
- **state** (string) - Optional - The state parameter for CSRF protection.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message upon successful callback.

#### Response Example
```json
{
  "message": "TikTok connect callback processed successfully."
}
```
```

--------------------------------

### Algorhythm Export (Legacy) API

Source: https://registry.dev.reviz.dev/api/docs/index

Legacy endpoints for exporting and syncing composite assets with the Algorhythm service.

```APIDOC
## GET /api/v1/algorhythm-export/composites

### Description
Export all Composite assets (Legacy)

### Method
GET

### Endpoint
/api/v1/algorhythm-export/composites

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/algorhythm-export/composites/{compositeId}

### Description
Get specific Composite asset by ID (Legacy)

### Method
GET

### Endpoint
/api/v1/algorhythm-export/composites/{compositeId}

#### Path Parameters
- **compositeId** (string) - Required - The ID of the composite asset.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/algorhythm-export/composites/by-song/{songId}

### Description
Export Composite assets for specific song (Legacy)

### Method
GET

### Endpoint
/api/v1/algorhythm-export/composites/by-song/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/algorhythm-export/sync-statistics

### Description
Get sync statistics (Legacy)

### Method
GET

### Endpoint
/api/v1/algorhythm-export/sync-statistics

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/algorhythm-export/sync-to-algorhythm

### Description
Sync all composites to Algorhythm (Legacy)

### Method
POST

### Endpoint
/api/v1/algorhythm-export/sync-to-algorhythm

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/algorhythm-export/sync-by-song/{songId}

### Description
Sync composites by song to Algorhythm (Legacy)

### Method
POST

### Endpoint
/api/v1/algorhythm-export/sync-by-song/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/algorhythm-export/test-webhook

### Description
Test webhook connectivity (Legacy)

### Method
GET

### Endpoint
/api/v1/algorhythm-export/test-webhook

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### Test API

Source: https://registry.dev.reviz.dev/api/docs/index

API endpoints for testing OpenAI integration and configurations.

```APIDOC
## GET /api/v1/api/test-openai

### Description
Test OpenAI configuration and basic connectivity

### Method
GET

### Endpoint
/api/v1/api/test-openai

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/api/test-openai/simple

### Description
Test simple OpenAI completion

### Method
POST

### Endpoint
/api/v1/api/test-openai/simple

#### Request Body
- **object** (object) - Required - Simple completion request.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/api/test-openai/extract-metadata

### Description
Test metadata extraction like Stars layer

### Method
POST

### Endpoint
/api/v1/api/test-openai/extract-metadata

#### Request Body
- **StarsMetadataDto** (object) - Required - Metadata extraction request.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/api/test-openai/debug-environment

### Description
Debug all environment configurations

### Method
GET

### Endpoint
/api/v1/api/test-openai/debug-environment

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/api/test-openai/songs-metadata

### Description
Test Songs metadata field transformation for frontend alignment

### Method
GET

### Endpoint
/api/v1/api/test-openai/songs-metadata

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### Algorhythm Export API

Source: https://registry.dev.reviz.dev/api/docs/index

Endpoints for exporting and syncing composite assets with the Algorhythm service.

```APIDOC
## GET /api/v1/v1/algorhythm-export/composites

### Description
Export Composite assets for Algorhythm service

### Method
GET

### Endpoint
/api/v1/v1/algorhythm-export/composites

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/v1/algorhythm-export/composites/{compositeId}

### Description
Get specific Composite asset by ID

### Method
GET

### Endpoint
/api/v1/v1/algorhythm-export/composites/{compositeId}

#### Path Parameters
- **compositeId** (string) - Required - The ID of the composite asset.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/v1/algorhythm-export/composites/by-song/{songId}

### Description
Export Composite assets for specific song

### Method
GET

### Endpoint
/api/v1/v1/algorhythm-export/composites/by-song/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/v1/algorhythm-export/sync-to-algorhythm

### Description
Sync Composite assets to Algorhythm service

### Method
POST

### Endpoint
/api/v1/v1/algorhythm-export/sync-to-algorhythm

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/v1/algorhythm-export/sync-by-song/{songId}

### Description
Sync Composite assets for specific song to Algorhythm

### Method
POST

### Endpoint
/api/v1/v1/algorhythm-export/sync-by-song/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/v1/algorhythm-export/test-webhook

### Description
Test webhook connectivity to Algorhythm

### Method
GET

### Endpoint
/api/v1/v1/algorhythm-export/test-webhook

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/v1/algorhythm-export/sync-statistics

### Description
Get Algorhythm sync statistics

### Method
GET

### Endpoint
/api/v1/v1/algorhythm-export/sync-statistics

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### Taxonomy Migration API

Source: https://registry.dev.reviz.dev/api/docs/index

API endpoints for managing taxonomy migration processes.

```APIDOC
## POST /api/v1/api/taxonomy/migration/analyze

### Description
Analyze taxonomy migration

### Method
POST

### Endpoint
/api/v1/api/taxonomy/migration/analyze

### Parameters
#### Request Body
- **AnalyzeContentDto** (object) - Required - Data for analysis.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/api/taxonomy/migration/execute

### Description
Execute taxonomy migration

### Method
POST

### Endpoint
/api/v1/api/taxonomy/migration/execute

### Parameters
#### Request Body
- **object** (object) - Required - Execution payload.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/api/taxonomy/migration/report

### Description
Get taxonomy migration report

### Method
GET

### Endpoint
/api/v1/api/taxonomy/migration/report

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/api/taxonomy/migration/preview

### Description
Preview taxonomy migration

### Method
POST

### Endpoint
/api/v1/api/taxonomy/migration/preview

### Parameters
#### Request Body
- **object** (object) - Required - Preview payload.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/api/taxonomy/migration/deprecated

### Description
Get deprecated taxonomy migration items

### Method
GET

### Endpoint
/api/v1/api/taxonomy/migration/deprecated

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### Optimized Composite Queries API

Source: https://registry.dev.reviz.dev/api/docs/index

Optimized endpoints for querying composite assets.

```APIDOC
## GET /api/v1/assets/composites/by-song/{songId}

### Description
Get composites by song ID (OPTIMIZED)

### Method
GET

### Endpoint
/api/v1/assets/composites/by-song/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/full/{songId}

### Description
Get FULL composites by song ID (C.FUL only)

### Method
GET

### Endpoint
/api/v1/assets/composites/full/{songId}

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/by-id/{compositeId}

### Description
Get composite by ID (OPTIMIZED)

### Method
GET

### Endpoint
/api/v1/assets/composites/by-id/{compositeId}

#### Path Parameters
- **compositeId** (string) - Required - The ID of the composite.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/by-song/{songId}/algorhythm

### Description
Get composites by song ID in AlgoRhythm format

### Method
GET

### Endpoint
/api/v1/assets/composites/by-song/{songId}/algorhythm

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/layers/{songId}/algorhythm

### Description
Get layer assets by song ID in AlgoRhythm format

### Method
GET

### Endpoint
/api/v1/assets/composites/layers/{songId}/algorhythm

#### Path Parameters
- **songId** (string) - Required - The ID of the song.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/search

### Description
Search composites (OPTIMIZED)

### Method
GET

### Endpoint
/api/v1/assets/composites/search

#### Query Parameters
- **query** (string) - Required - The search query.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/assets/composites/performance/metrics

### Description
Get performance metrics

### Method
GET

### Endpoint
/api/v1/assets/composites/performance/metrics

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### Taxonomy API

Source: https://registry.dev.reviz.dev/api/docs/index

Endpoints for managing and querying the NNA taxonomy.

```APIDOC
## GET /api/v1/taxonomy/layers

### Description
Get a map of layer codes to layer names.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers

### Response
#### Success Response (200)
- **layers** (object) - An object where keys are layer codes and values are layer names.

#### Response Example
```json
{
  "layers": {
    "L1": "Layer 1 Name",
    "L2": "Layer 2 Name"
  }
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layers/{layer}/categories

### Description
Get categories for a specific layer.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers/{layer}/categories

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.

### Response
#### Success Response (200)
- **categories** (array) - An array of category objects.

#### Response Example
```json
{
  "categories": [
    {"code": "C1", "name": "Category 1"},
    {"code": "C2", "name": "Category 2"}
  ]
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layers/{layer}/categories/{category}/subcategories

### Description
Get subcategories for a specific category within a layer.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers/{layer}/categories/{category}/subcategories

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.
- **category** (string) - Required - The category code.

### Response
#### Success Response (200)
- **subcategories** (array) - An array of subcategory objects.

#### Response Example
```json
{
  "subcategories": [
    {"code": "SC1", "name": "Subcategory 1"},
    {"code": "SC2", "name": "Subcategory 2"}
  ]
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layers/{layer}/subcategory-counts

### Description
Get subcategory counts for a specific layer.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers/{layer}/subcategory-counts

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.

### Response
#### Success Response (200)
- **subcategoryCounts** (object) - An object mapping subcategory codes to their counts.

#### Response Example
```json
{
  "subcategoryCounts": {
    "SC1": 15,
    "SC2": 22
  }
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layers/{layer}/categories/{category}/subcategory-count

### Description
Get the count of subcategories for a specific category in a layer.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers/{layer}/categories/{category}/subcategory-count

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.
- **category** (string) - Required - The category code.

### Response
#### Success Response (200)
- **subcategoryCount** (integer) - The count of subcategories.

#### Response Example
```json
{
  "subcategoryCount": 37
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layers/{layer}/category-count

### Description
Get the count of categories for a specific layer.

### Method
GET

### Endpoint
/api/v1/taxonomy/layers/{layer}/category-count

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.

### Response
#### Success Response (200)
- **categoryCount** (integer) - The count of categories.

#### Response Example
```json
{
  "categoryCount": 50
}
```
```

```APIDOC
## GET /api/v1/taxonomy/layer-count

### Description
Get the count of active taxonomy layers.

### Method
GET

### Endpoint
/api/v1/taxonomy/layer-count

### Response
#### Success Response (200)
- **layerCount** (integer) - The total number of active layers.

#### Response Example
```json
{
  "layerCount": 10
}
```
```

```APIDOC
## GET /api/v1/taxonomy/index

### Description
Get the taxonomy index across all layers.

### Method
GET

### Endpoint
/api/v1/taxonomy/index

### Response
#### Success Response (200)
- **taxonomyIndex** (object) - The complete taxonomy index.

#### Response Example
```json
{
  "taxonomyIndex": {
    "L1": {
      "C1": {
        "SC1": { "name": "Subcategory 1", "count": 15 },
        "SC2": { "name": "Subcategory 2", "count": 22 }
      }
    }
  }
}
```
```

```APIDOC
## GET /api/v1/taxonomy/version

### Description
Get the current taxonomy version.

### Method
GET

### Endpoint
/api/v1/taxonomy/version

### Response
#### Success Response (200)
- **version** (string) - The current version of the taxonomy.

#### Response Example
```json
{
  "version": "1.2.0"
}
```
```

```APIDOC
## GET /api/v1/taxonomy/health

### Description
Check the health status of the taxonomy service.

### Method
GET

### Endpoint
/api/v1/taxonomy/health

### Response
#### Success Response (200)
- **status** (string) - The health status (e.g., 'OK', 'Degraded').

#### Response Example
```json
{
  "status": "OK"
}
```
```

```APIDOC
## GET /api/v1/taxonomy/tree

### Description
Get the full taxonomy tree structure.

### Method
GET

### Endpoint
/api/v1/taxonomy/tree

### Response
#### Success Response (200)
- **taxonomyTree** (object) - The complete taxonomy tree.

#### Response Example
```json
{
  "taxonomyTree": {
    "layers": [
      {
        "code": "L1",
        "name": "Layer 1 Name",
        "categories": [
          {
            "code": "C1",
            "name": "Category 1",
            "subcategories": [
              { "code": "SC1", "name": "Subcategory 1" },
              { "code": "SC2", "name": "Subcategory 2" }
            ]
          }
        ]
      }
    ]
  }
}
```
```

```APIDOC
## POST /api/v1/taxonomy/convert/hfn-to-mfa

### Description
Convert HFN (alpha) to MFA (numeric) representation.

### Method
POST

### Endpoint
/api/v1/taxonomy/convert/hfn-to-mfa

### Parameters
#### Request Body
- **hfn** (string) - Required - The HFN value to convert.

### Response
#### Success Response (200)
- **mfa** (string) - The converted MFA value.

#### Response Example
```json
{
  "mfa": "12345"
}
```
```

```APIDOC
## POST /api/v1/taxonomy/convert/mfa-to-hfn

### Description
Convert MFA (numeric) to HFN (alpha) representation.

### Method
POST

### Endpoint
/api/v1/taxonomy/convert/mfa-to-hfn

### Parameters
#### Request Body
- **mfa** (string) - Required - The MFA value to convert.

### Response
#### Success Response (200)
- **hfn** (string) - The converted HFN value.

#### Response Example
```json
{
  "hfn": "ABCDE"
}
```
```

```APIDOC
## POST /api/v1/taxonomy/nodes

### Description
Add new nodes to the taxonomy.

### Method
POST

### Endpoint
/api/v1/taxonomy/nodes

### Parameters
#### Request Body
- **nodeData** (object) - Required - The data for the new taxonomy node(s).

### Response
#### Success Response (201)
- **message** (string) - A success message.
- **nodeIds** (array) - IDs of the created nodes.

#### Response Example
```json
{
  "message": "Taxonomy nodes created successfully.",
  "nodeIds": ["node_xyz789"]
}
```
```

```APIDOC
## PUT /api/v1/taxonomy/nodes/{id}

### Description
Update an existing taxonomy node.

### Method
PUT

### Endpoint
/api/v1/taxonomy/nodes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the node to update.
#### Request Body
- **updateData** (object) - Required - The data to update the node with.

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Taxonomy node updated successfully."
}
```
```

```APIDOC
## DELETE /api/v1/taxonomy/nodes/{id}

### Description
Delete a taxonomy node.

### Method
DELETE

### Endpoint
/api/v1/taxonomy/nodes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the node to delete.

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Taxonomy node deleted successfully."
}
```
```

```APIDOC
## POST /api/v1/taxonomy/import

### Description
Import taxonomy data.

### Method
POST

### Endpoint
/api/v1/taxonomy/import

### Parameters
#### Request Body
- **taxonomyData** (object) - Required - The taxonomy data to import.

### Response
#### Success Response (200)
- **message** (string) - A success message indicating import completion.

#### Response Example
```json
{
  "message": "Taxonomy data imported successfully."
}
```
```

```APIDOC
## GET /api/v1/taxonomy/export

### Description
Export the current taxonomy data.

### Method
GET

### Endpoint
/api/v1/taxonomy/export

### Response
#### Success Response (200)
- **taxonomyData** (object) - The exported taxonomy data.

#### Response Example
```json
{
  "taxonomyData": {
    "layers": [...] 
  }
}
```
```

```APIDOC
## POST /api/v1/taxonomy/validate

### Description
Validate a taxonomy triplet (layer/category/subcategory).

### Method
POST

### Endpoint
/api/v1/taxonomy/validate

### Parameters
#### Request Body
- **layer** (string) - Required - The layer code.
- **category** (string) - Required - The category code.
- **subcategory** (string) - Required - The subcategory code.

### Response
#### Success Response (200)
- **isValid** (boolean) - True if the triplet is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

```APIDOC
## POST /api/v1/taxonomy/rollback

### Description
Rollback the taxonomy to a previous state.

### Method
POST

### Endpoint
/api/v1/taxonomy/rollback

### Parameters
#### Request Body
- **versionId** (string) - Required - The ID of the version to roll back to.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "message": "Taxonomy rolled back successfully."
}
```
```

```APIDOC
## GET /api/v1/taxonomy/history

### Description
Get the history of taxonomy changes.

### Method
GET

### Endpoint
/api/v1/taxonomy/history

### Response
#### Success Response (200)
- **history** (array) - An array of historical change records.

#### Response Example
```json
{
  "history": [
    {"timestamp": "2023-10-27T10:00:00Z", "action": "update", "details": "Updated category C1"}
  ]
}
```
```

```APIDOC
## POST /api/v1/taxonomy/next-sequence

### Description
Get the next sequential number, HFN, and MFA for a taxonomy path.

### Method
POST

### Endpoint
/api/v1/taxonomy/next-sequence

### Parameters
#### Request Body
- **path** (string) - Required - The taxonomy path (e.g., 'L1/C1').

### Response
#### Success Response (200)
- **sequenceNumber** (integer) - The next sequential number.
- **hfn** (string) - The corresponding HFN value.
- **mfa** (string) - The corresponding MFA value.

#### Response Example
```json
{
  "sequenceNumber": 15,
  "hfn": "ABCDE15",
  "mfa": "1234515"
}
```
```

```APIDOC
## POST /api/v1/taxonomy/validate-sequence

### Description
Validate the availability of a sequence for a taxonomy path.

### Method
POST

### Endpoint
/api/v1/taxonomy/validate-sequence

### Parameters
#### Request Body
- **path** (string) - Required - The taxonomy path.
- **sequenceNumber** (integer) - Required - The sequence number to validate.

### Response
#### Success Response (200)
- **isAvailable** (boolean) - True if the sequence is available, false otherwise.

#### Response Example
```json
{
  "isAvailable": true
}
```
```

```APIDOC
## GET /api/v1/taxonomy/debug/taxonomy/{layer}

### Description
Debug dump for a given taxonomy layer (internal use).

### Method
GET

### Endpoint
/api/v1/taxonomy/debug/taxonomy/{layer}

### Parameters
#### Path Parameters
- **layer** (string) - Required - The layer code.

### Response
#### Success Response (200)
- **debugDump** (object) - Debug information for the specified layer.

#### Response Example
```json
{
  "debugDump": {
    "layerCode": "L1",
    "internalData": "..."
  }
}
```
```

--------------------------------

### AI Public API

Source: https://registry.dev.reviz.dev/api/docs/index

Public endpoints for interacting with AI services.

```APIDOC
## GET /api/v1/ai-public/health

### Description
AI service health check (Public)

### Method
GET

### Endpoint
/api/v1/ai-public/health

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/ai-public/test-album-art

### Description
Test album art fetching (Public)

### Method
GET

### Endpoint
/api/v1/ai-public/test-album-art

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## GET /api/v1/ai-public/capabilities

### Description
Get AI service capabilities (Public)

### Method
GET

### Endpoint
/api/v1/ai-public/capabilities

### Parameters

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/ai-public/test-generate-metadata

### Description
Test AI metadata generation (Public)

### Method
POST

### Endpoint
/api/v1/ai-public/test-generate-metadata

#### Request Body
- **GenerateMetadataDto** (object) - Required - Data for metadata generation.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/ai-public/test-regenerate-description

### Description
Test regenerate description only (Public)

### Method
POST

### Endpoint
/api/v1/ai-public/test-regenerate-description

#### Request Body
- **RegenerateDescriptionDto** (object) - Required - Data for description regeneration.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/ai-public/test-regenerate-tags

### Description
Test regenerate tags only (Public)

### Method
POST

### Endpoint
/api/v1/ai-public/test-regenerate-tags

#### Request Body
- **RegenerateTagsDto** (object) - Required - Data for tag regeneration.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/ai-public/test-structured-outputs

### Description
Test structured outputs implementation (Public)

### Method
POST

### Endpoint
/api/v1/ai-public/test-structured-outputs

#### Request Body
- **object** (object) - Required - Structured output test data.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

```APIDOC
## POST /api/v1/ai-public/test-hybrid-extraction

### Description
Test HybridExtractionService directly (Public)

### Method
POST

### Endpoint
/api/v1/ai-public/test-hybrid-extraction

#### Request Body
- **object** (object) - Required - Hybrid extraction test data.

### Request Example

### Response
#### Success Response (200)

#### Response Example

```

--------------------------------

### AI Services API

Source: https://registry.dev.reviz.dev/api/docs/index

Endpoints for AI-driven metadata extraction, generation, and analysis.

```APIDOC
## POST /api/v1/ai/extract-metadata

### Description
🚀 Extract AI metadata for assets with 100% frontend compliance.

### Method
POST

### Endpoint
/api/v1/ai/extract-metadata

### Parameters
#### Request Body
- **assetId** (string) - Required - The ID of the asset.
- **content** (string) - Required - The content of the asset.

### Response
#### Success Response (200)
- **metadata** (object) - Extracted metadata.

#### Response Example
```json
{
  "metadata": {
    "title": "Extracted Title",
    "description": "AI generated description."
  }
}
```
```

```APIDOC
## POST /api/v1/ai/generate-metadata

### Description
🚀 Generate AI metadata for assets (DEPRECATED).

### Method
POST

### Endpoint
/api/v1/ai/generate-metadata

### Parameters
#### Request Body
- **assetId** (string
```