> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Music Purposes

> Retrieve a list of available music purposes for filtering and searching music tracks

## Overview

Retrieve a comprehensive list of available music purposes for filtering and searching music tracks. Use these purpose values to find music that matches the specific use case, context, or application of your video content.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/music/purposes
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

<ResponseField name="purposes" type="array of strings">
  Array of available music purpose names. Each purpose represents a distinct use case, context, or application scenario for filtering music tracks in search queries.
</ResponseField>

***

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    "TV Theme",
    "Heroic",
    "Nature / Beauty",
    "Action",
    "Adventure",
    "Comedy",
    "Drama",
    "Fantasy",
    "Horror",
    "Shopping",
    "Sports",
    "Thriller",
    "Wedding",
    "80s",
    "Educational",
    "News / Current Affairs",
    "On-Hold",
    "Road Trip",
    "Sci-Fi",
    "Time Lapse",
    "Aerobics / Fitness",
    "Atmospheric",
    "Branding / Identity",
    "Corporate / Business",
    "Children / Preschool",
    "Crime",
    "Landscape / Panorama",
    "Mystery / Tension",
    "Nightclub",
    "Technology",
    "Slow-Mo",
    "War / Military",
    "Western / Cowboy",
    "Bollywood",
    "Historical / Period",
    "Real Estate",
    "Christmas",
    "Surfing",
    "Detective / Spy",
    "Dramedy",
    "Game Show",
    "50s",
    "60s",
    "70s",
    "Chase Sequence",
    "Elevator Music",
    "Exotic",
    "Failure / Defeat",
    "Fairytale",
    "Fanfare",
    "Frantic / Busy",
    "Futuristic",
    "Lullaby",
    "Luxury",
    "Retro",
    "Romantic Comedy",
    "Sex / Erotic",
    "Lazy / Plodding",
    "Space / Cosmos",
    "Success / Victory",
    "Superhero",
    "Swampy / Outback",
    "Tribal",
    "Magical / Supernatural",
    "Simple / Minimal",
    "Adrenaline",
    "Evil / Villainous",
    "Religious / Church",
    "Theatre / Showtunes",
    "Regal / Royal",
    "Circus / Carnival",
    "Tropical",
    "Fashion / Beauty",
    "Animation / Explainer",
    "Trailer / Promo",
    "Yoga / Relaxation",
    "Meditation"
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.pictory.ai/pictoryapis/v1/music/purposes \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v1/music/purposes"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  purposes = response.json()

  # Print all available purposes
  for purpose in purposes:
      print(purpose)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/purposes',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const purposes = await response.json();
  console.log('Available purposes:', purposes);
  ```
</CodeGroup>

## Usage Notes

<Tip>
  Use these exact purpose values when searching for music to ensure valid selection from available categories. Purpose values are case-sensitive and must match exactly as returned by this endpoint.
</Tip>

<Note>
  **Purpose Diversity**: The API provides 74 distinct purpose options spanning various contexts, from media types (TV Theme, Animation/Explainer, Trailer/Promo) to genres (Action, Comedy, Horror) to specific applications (Corporate/Business, Wedding, Real Estate), enabling precise matching of music to your video's intended use and context.
</Note>

## Common Use Cases

### 1. Populate a Purpose Selector

Fetch all available purposes to populate a dropdown or selection interface in your application:

```python theme={null}
purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

# Use purposes to populate UI dropdown
purpose_options = [{"label": purpose, "value": purpose} for purpose in purposes]
```

### 2. Categorize Purposes by Context

Organize purposes into logical categories for simplified user selection:

```javascript theme={null}
const response = await fetch('https://api.pictory.ai/pictoryapis/v1/music/purposes', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});
const purposes = await response.json();

// Categorize by type
const mediaGenres = purposes.filter(p =>
  ['Action', 'Adventure', 'Comedy', 'Drama', 'Fantasy', 'Horror', 'Thriller', 'Sci-Fi'].includes(p)
);

const businessPurposes = purposes.filter(p =>
  p.includes('Corporate') || p.includes('Business') || p.includes('Branding') ||
  p.includes('Real Estate') || p.includes('Technology')
);

const timePerods = purposes.filter(p =>
  ['50s', '60s', '70s', '80s', 'Retro', 'Futuristic', 'Historical / Period'].includes(p)
);

const videoPurposes = purposes.filter(p =>
  p.includes('Animation') || p.includes('Trailer') || p.includes('Time Lapse') ||
  p.includes('Slow-Mo') || p.includes('Explainer')
);

const eventPurposes = purposes.filter(p =>
  ['Wedding', 'Christmas', 'Circus / Carnival', 'Game Show'].includes(p)
);

const wellnessPurposes = purposes.filter(p =>
  p.includes('Yoga') || p.includes('Meditation') || p.includes('Relaxation') ||
  p.includes('Aerobics') || p.includes('Fitness')
);
```

### 3. Validate User Input

Ensure user-selected purposes are valid before using them in music search requests:

```python theme={null}
valid_purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

user_purpose = "Corporate / Business"
if user_purpose in valid_purposes:
    # Proceed with music search using this purpose
    print(f"Searching for {user_purpose} music...")
else:
    print("Invalid purpose selected")
```

### 4. Build Multi-Category Purpose Filter

Create a categorized purpose filter for intuitive music discovery:

```python theme={null}
import requests

purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

# Organize by category
categories = {
    "Film & TV": [p for p in purposes if any(x in p for x in ['TV Theme', 'Action', 'Adventure', 'Comedy', 'Drama', 'Fantasy', 'Horror', 'Thriller', 'Sci-Fi', 'Western', 'Detective', 'Spy'])],

    "Business & Corporate": [p for p in purposes if any(x in p for x in ['Corporate', 'Business', 'Branding', 'Identity', 'Technology', 'Real Estate', 'Educational', 'News'])],

    "Video Production": [p for p in purposes if any(x in p for x in ['Animation', 'Explainer', 'Trailer', 'Promo', 'Time Lapse', 'Slow-Mo'])],

    "Events & Occasions": [p for p in purposes if any(x in p for x in ['Wedding', 'Christmas', 'Circus', 'Carnival', 'Game Show', 'Shopping'])],

    "Time Periods": [p for p in purposes if p in ['50s', '60s', '70s', '80s', 'Retro', 'Historical / Period', 'Futuristic']],

    "Wellness & Lifestyle": [p for p in purposes if any(x in p for x in ['Yoga', 'Meditation', 'Relaxation', 'Aerobics', 'Fitness', 'Fashion', 'Beauty', 'Luxury'])],

    "Moods & Emotions": [p for p in purposes if any(x in p for x in ['Heroic', 'Success', 'Victory', 'Failure', 'Defeat', 'Adrenaline', 'Romantic', 'Lullaby'])],

    "Nature & Places": [p for p in purposes if any(x in p for x in ['Nature', 'Beauty', 'Landscape', 'Panorama', 'Space', 'Cosmos', 'Tropical', 'Swampy', 'Outback'])],

    "Cultural & Regional": [p for p in purposes if any(x in p for x in ['Bollywood', 'Western', 'Cowboy', 'Religious', 'Church', 'Tribal', 'Exotic'])],

    "Special Applications": [p for p in purposes if any(x in p for x in ['On-Hold', 'Elevator', 'Nightclub', 'Road Trip', 'Surfing', 'Chase Sequence'])]
}

for category, purpose_list in categories.items():
    print(f"\n{category}:")
    for purpose in sorted(purpose_list):
        print(f"  - {purpose}")
```

### 5. Smart Purpose Recommendation

Suggest relevant purposes based on video content analysis:

```javascript theme={null}
async function recommendPurposes(videoKeywords) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/purposes',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );
  const allPurposes = await response.json();

  // Map keywords to relevant purposes
  const keywordMappings = {
    'office': ['Corporate / Business', 'Technology', 'Educational'],
    'wedding': ['Wedding', 'Romantic Comedy', 'Fashion / Beauty'],
    'product': ['Branding / Identity', 'Corporate / Business', 'Shopping'],
    'fitness': ['Aerobics / Fitness', 'Sports', 'Yoga / Relaxation'],
    'travel': ['Road Trip', 'Adventure', 'Landscape / Panorama'],
    'children': ['Children / Preschool', 'Fairytale', 'Animation / Explainer'],
    'tech': ['Technology', 'Futuristic', 'Corporate / Business'],
    'luxury': ['Luxury', 'Fashion / Beauty', 'Regal / Royal'],
    'nature': ['Nature / Beauty', 'Landscape / Panorama', 'Time Lapse']
  };

  const recommendations = new Set();

  videoKeywords.forEach(keyword => {
    const mapped = keywordMappings[keyword.toLowerCase()];
    if (mapped) {
      mapped.forEach(purpose => {
        if (allPurposes.includes(purpose)) {
          recommendations.add(purpose);
        }
      });
    }
  });

  return Array.from(recommendations);
}

// Example usage
const suggestions = await recommendPurposes(['office', 'tech', 'product']);
console.log('Recommended purposes:', suggestions);
// Output: ['Corporate / Business', 'Technology', 'Branding / Identity', ...]
```

### 6. Filter by Time Period

Create a dedicated filter for era-specific music:

```python theme={null}
def get_time_period_purposes(api_key):
    """
    Extract time period-specific purposes for historical or retro content
    """
    headers = {"Authorization": api_key}

    all_purposes = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/purposes",
        headers=headers
    ).json()

    time_periods = {
        "Classic Eras": ['50s', '60s', '70s', '80s'],
        "Historical": ['Historical / Period', 'Western / Cowboy'],
        "Retro & Vintage": ['Retro', 'Bollywood'],
        "Future": ['Futuristic', 'Sci-Fi', 'Space / Cosmos']
    }

    filtered_periods = {}
    for category, keywords in time_periods.items():
        filtered_periods[category] = [
            p for p in all_purposes
            if p in keywords
        ]

    return filtered_periods

# Example usage
periods = get_time_period_purposes("YOUR_API_KEY")
for category, purposes in periods.items():
    print(f"{category}: {', '.join(purposes)}")
```