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

# API Quickstart

> Get your API key, search the catalog, and download your first licensed track in 5 minutes

This guide walks you through the complete workflow: from account creation to downloading a licensed track via the Trackyard API.

***

## Prerequisites

* A Trackyard account ([sign up here](https://app.trackyard.com))
* Basic familiarity with REST APIs

***

## Step 1: Get Your API Key

<Steps>
  <Step title="Sign up or log in">
    Go to [app.trackyard.com](https://app.trackyard.com) and create a free account or log in.
  </Step>

  <Step title="Navigate to API Keys">
    Click on **API Keys** in the dashboard or go directly to [app.trackyard.com/api-keys](https://app.trackyard.com/api-keys).
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a name (e.g., "My First Key"), and copy the key to your clipboard.

    <Warning>
      **Keep your API key secure!** Never commit it to version control or share it publicly. Store it in environment variables.
    </Warning>
  </Step>
</Steps>

```bash theme={null}
# Store your API key in an environment variable
export TRACKYARD_API_KEY="your_api_key_here"
```

***

## Step 2: Search for Music

Use the `/search` endpoint to find tracks. Describe what you need in plain English — Trackyard's AI will infer genre, mood, BPM, and instrumentation automatically.

```bash theme={null}
curl -X POST https://api.trackyard.com/api/external/v1/search \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "upbeat electronic music for tech startup video",
    "limit": 5,
    "filters": {
      "has_vocals": false
    }
  }'
```

<Accordion title="Example Response">
  ```json theme={null}
  {
    "tracks": [
      {
        "id": "trk_abc123",
        "title": "Digital Sunrise",
        "artist": "Sync Lab",
        "duration_seconds": 142,
        "bpm": 128,
        "key": "C Major",
        "genres": ["Electronic", "Corporate"],
        "moods": ["Upbeat", "Energetic", "Modern"],
        "has_vocals": false,
        "preview_url": "https://cdn.trackyard.com/previews/trk_abc123.mp3"
      },
      // ... 4 more tracks
    ],
    "credits_remaining": 487
  }
  ```
</Accordion>

<Tip>
  **Pro tip:** The more specific your query, the better the results. Try "moody lo-fi piano for a coffee shop vlog" instead of just "lofi music."
</Tip>

***

## Step 3: Download a Licensed Track

Once you've found a track you like, use the `/download-track` endpoint to get the audio file. The license is automatically included — no extra step required.

### Option A: Download Full Track

```bash theme={null}
curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id": "trk_abc123"}' \
  --output track.mp3
```

### Option B: Download Smart-Trimmed Clip

Need exactly 30 seconds? Trackyard analyzes the waveform and selects the best-sounding segment automatically.

```bash theme={null}
curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "track_id": "trk_abc123",
    "duration_seconds": 30
  }' \
  --output clip-30s.mp3
```

### Option C: Align Musical Peak to Specific Offset

Want the big hit to land at exactly 12 seconds (e.g., when your product appears on screen)?

```bash theme={null}
curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "track_id": "trk_abc123",
    "duration_seconds": 22,
    "hit_point_seconds": 12
  }' \
  --output clip-with-hit.mp3
```

<Info>
  **How it works:** Trackyard's algorithm finds the dominant energy peak in the track and aligns it to your specified offset. Perfect for syncing music to video reveals, product shots, or title cards.
</Info>

***

## Step 4: Use the Track

That's it! You now have a licensed MP3 file ready to use in your project. The license is perpetual — use it forever with no renewals or expiration.

<Card title="What's Included in the License" icon="file-contract" color="#EC8D28">
  * ✅ Perpetual usage rights (no expiration)
  * ✅ Social media (Instagram, TikTok, YouTube, etc.)
  * ✅ Podcasts and streaming platforms
  * ✅ Online ads and branded content
  * ✅ Corporate and training videos
  * ✅ Film and TV (usage tier-dependent)

  See our [Licensing Model](/core-concepts/how-trackyard-works#licensing-model) for full details.
</Card>

***

## Check Your Usage

Monitor your credit balance and API usage anytime:

```bash theme={null}
# Get account info
curl https://api.trackyard.com/api/external/v1/me \
  -H "Authorization: Bearer $TRACKYARD_API_KEY"

# Get usage history
curl "https://api.trackyard.com/api/external/v1/usage?limit=50" \
  -H "Authorization: Bearer $TRACKYARD_API_KEY"
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Search API Reference" icon="magnifying-glass" href="/api-reference/search">
    Learn about all available search filters and parameters
  </Card>

  <Card title="Download API Reference" icon="download" href="/api-reference/download-track">
    Advanced clip trimming options and hit point alignment
  </Card>

  <Card title="Code Examples" icon="code" href="/api-reference/examples">
    Python and JavaScript SDKs with full examples
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases/social-media-content-farms">
    See how others are using Trackyard at scale
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    * Check that your API key is correct and not expired
    * Ensure you're passing it in the `Authorization: Bearer` header
    * Verify your account is active
  </Accordion>

  <Accordion title="402 Out of Credits">
    * Your account has run out of credits
    * Top up or upgrade your plan at [app.trackyard.com/billing](https://app.trackyard.com/billing)
  </Accordion>

  <Accordion title="429 Rate Limit Exceeded">
    * You've exceeded your rate limit (10 requests/minute for free tier)
    * Wait for the `retry_after` seconds indicated in the response
    * Consider upgrading for higher limits
  </Accordion>

  <Accordion title="No results returned">
    * Try a more specific query ("moody piano for a rainy scene" vs "sad music")
    * Remove overly restrictive filters
    * Check for typos in filter parameters
  </Accordion>
</AccordionGroup>

Need more help? Email [support@trackyard.com](mailto:support@trackyard.com)