1 2 3<!DOCTYPE html> 4<html lang="en" data-bs-theme="auto" data-fs-theme="midnight"> 5 <head> 6 <meta charset="utf-8"> 7 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 8 9 <meta name="language" content="EN"> 10 <meta name="viewport" content="width=device-width, initial-scale=1"> 11 <meta name="application-name" content="Fireside"> 12 <meta name="author" content="Very Good Software, LLC"> 13 <meta name="owner" content="Very Good Software, LLC"> 14 <meta name="copyright" content="Very Good Software, LLC"> 15 <meta name="description" content="Build podcast integrations with Fireside API authentication, endpoints, resources, and examples. Read the API guide and start building today."> 16 <meta name="keywords" content="Fireside, podcast, podcasts, podcasting"> 17 18 <title>Fireside API Documentation</title> 19 <link rel="canonical" href="https://fireside.fm/docs/api"> 20 <meta property="og:title" content="Fireside API Documentation"> 21<meta property="og:description" content="Build podcast integrations with Fireside API authentication, endpoints, resources, and examples. Read the API guide and start building today."> 22<meta property="og:url" content="https://fireside.fm/docs/api"> 23<meta property="og:image" content="https://fireside.fm/social/fireside-v1.png"> 24<meta property="og:image:width" content="1200"> 25<meta property="og:image:height" content="630"> 26<meta property="og:image:type" content="image/png"> 27<meta property="og:image:alt" content="Fireside logo"> 28<meta property="og:type" content="website"> 29<meta property="og:site_name" content="Fireside"> 30 <meta name="twitter:card" content="summary_large_image"> 31<meta name="twitter:title" content="Fireside API Documentation"> 32<meta name="twitter:description" content="Build podcast integrations with Fireside API authentication, endpoints, resources, and examples. Read the API guide and start building today."> 33<meta name="twitter:image" content="https://fireside.fm/social/fireside-v1.png"> 34<meta name="twitter:image:alt" content="Fireside logo"> 35 36 <meta name="csrf-param" content="authenticity_token" /> 37<meta name="csrf-token" content="_EVvm2lWewDnL6uxXKUmuKvcB_DiDVOmv_qDQWJRHnD-pSplf31bqgYM437Pe3fNWIzvAj_CvqRbSsnpa9fiuA" /> 38 39
39<script>
vendor: 440 bytes, lines 39-47
39 40 !function(f,b,e,v,n,t,s) { 41 if(f.fbq)return;n=f.fbq=function(){n.callMethod? 42 n.callMethod.apply(n,arguments):n.queue.push(arguments)}; 43 if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0'; 44 n.queue=[];t=b.createElement(e);t.async=!0;t.src=v; 45 s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s) 46 }(window,document,'script','https://connect.facebook.net/en_US/fbevents.js'); 47 fbq('init', "
471705079104957292
vendor: 38 bytes, lines 47-49
47"); 48 fbq('track', 'PageView'); 49
49</script>
49 50 51 52 <!-- Standardized Theme System --> 53
53<script> 54 (() => { 55 'use strict' 56 57 const getStoredTheme = () => localStorage.getItem('theme') 58 const setStoredTheme = theme => localStorage.setItem('theme', theme) 59 60 const getPreferredTheme = () => { 61 const storedTheme = getStoredTheme() 62 if (storedTheme) { 63 return storedTheme 64 } 65 return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light' 66 } 67 68 const setTheme = theme => { 69 document.documentElement.setAttribute('data-bs-theme', theme) 70 updateThemeIcon(theme) 71 } 72 73 const updateThemeIcon = theme => { 74 const themeIcon = document.getElementById('theme-icon') 75 if (themeIcon) { 76 themeIcon.textContent = theme === 'dark' ? 'âï¸' : 'ð' 77 } 78 } 79 80 const toggleTheme = () => { 81 const currentTheme = document.documentElement.getAttribute('data-bs-theme') || 'light' 82 const newTheme = currentTheme === 'dark' ? 'light' : 'dark' 83 setStoredTheme(newTheme) 84 setTheme(newTheme) 85 } 86 87 // Make toggleTheme globally available 88 window.toggleTheme = toggleTheme 89 90 // Initialize theme 91 setTheme(getPreferredTheme()) 92 93 // Listen for system theme changes 94 window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => { 95 const storedTheme = getStoredTheme() 96 if (!storedTheme) { 97 setTheme(getPreferredTheme()) 98 } 99 }) 100 })() 101 </script>
101 102 103 <link rel="icon" type="image/svg+xml" href="/favicon.svg"> 104 <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"> 105 <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> 106 <link rel="alternate" type="application/rss+xml" title="Fireside Blog" href="https://blog.fireside.fm/rss/" /> 107 <link rel="alternate" type="application/rss+xml" title="Standing in the Fire" href="https://feeds.fireside.fm/standinginthefire/rss" /> 108 <!-- Global site tag (gtag.js) - Google Analytics -->
vendor: 66 bytes, lines 108-109
108 109 <script async src="https://www.googletagmanager.com/gtag/js?id=
109G-SS9BQLJWNE
vendor: 14 bytes, lines 109-110
109"></script> 110
110<script> 111
vendor: 139 bytes, lines 111-114
111window.dataLayer = window.dataLayer || []; 112 function gtag(){dataLayer.push(arguments);} 113 gtag('js', new Date()); 114 gtag('config', '
114G-SS9BQLJWNE
vendor: 9 bytes, lines 114-116
114'); 115 116
116document.addEventListener('turbolinks:load', event => { 117 if (typeof gtag === 'function') { 118 gtag('config', 'G-SS9BQLJWNE', { 119 'page_location': event.data.url 120 }); 121 } 122 }); 123 </script>
123 124 125 <link rel="stylesheet" href="https://a.fireside.fm/assets/v2/shared-2b7f2f9f5668f7b48c878a3fc4ce2615e519e61c6832645a9dcac6fc4b903570.css" media="all" data-turbolinks-track="true" /> 126 <link rel="stylesheet" href="https://a.fireside.fm/assets/v2/landing-0a8675614b55dbe35a7947dd03e7469bf2582a8f6f5e67bfddde89a1fce72cce.css" media="all" data-turbolinks-track="true" /> 127 <style type="text/css"> 128 /* 129 Position-related CSS for the "Skip to Content" included directly in the 130 HTML so the link isn't rendered within the viewable area and then 131 abruptly/obtrusively moved off-screen after the CSS loads. 132 */ 133 a[href="#main"] { 134 position: absolute; 135 transform: translateY(-300%); 136 } 137 138 a[href="#main"]:focus { 139 transform: translateY(0); 140 } 141 </style> 142 143 </head> 144 <body> 145 146 <a href="#main">Skip to Content</a> 147 148 <svg style="display: none;" aria-hidden="true"> 149 <defs> 150 <!-- Wave 1: Original wave with moderate amplitude --> 151 <path id="divider-wave1" fill="var(--fs-body-bg)" d="M-1200,380c0,0,236.988-180,505.475,0 152s371.981,170,575.971,0s293.985-170,505.474,22s493.475,190,716.963-22s400,0,800,0s400,0,800,0v560.106H-1200V380z" /> 153 154 <!-- Wave 2: Higher amplitude, more dramatic curves --> 155 <path id="divider-wave2" fill="var(--fs-body-bg)" d="M-1200,320c0,0,200.988-220,450.475,0 156s320.981,200,520.971,0s250.985-200,450.474,30s420.475,220,620.963-30s400,0,800,0s400,0,800,0v560.106H-1200V320z" /> 157 158 <!-- Wave 3: Lower amplitude, gentler curves --> 159 <path id="divider-wave3" fill="var(--fs-body-bg)" d="M-1200,400c0,0,280.988-140,580.475,0 160s420.981,130,620.971,0s350.985-130,580.474,20s550.475,160,750.963-20s400,0,800,0s400,0,800,0v560.106H-1200V400z" /> 161 </defs> 162</svg> 163 164 165 <header class="landing-header bg-gradient-header"> 166 167<nav class="navbar navbar-expand-lg" data-component="primary-nav"> 168 <div class="container"> 169 <!-- Brand/Logo --> 170 <a class="navbar-brand d-flex align-items-center order-lg-1" href="/"> 171 <img alt="Fireside" height="36" class="d-inline-block align-top" loading="lazy" src="https://a.fireside.fm/assets/v2/shared/identity/horizontal_red_light-11b76edc6cbc14bf5cca09e98bc3f18019b5102908ac8c6fcde745b2359f2225.svg" /> 172</a> 173 <!-- Auth/CTA buttons --> 174 <div 175 class=" 176 navbar-context d-flex align-items-center justify-content-end gap-2 177 order-lg-3 178 " 179 > 180 <a class="btn btn-sm btn-outline-light" href="https://app.fireside.fm/login"> 181 <span>Log In</span> 182</a> <a class="btn btn-sm btn-action" href="https://app.fireside.fm/sign_up"> 183 <span class="text-white">Create an account</span> 184</a> 185 <!-- Mobile toggle button --> 186 <button 187 class="navbar-toggler" 188 type="button" 189 data-bs-toggle="collapse" 190 data-bs-target="#primaryNavigation" 191 aria-controls="primaryNavigation" 192 aria-expanded="false" 193 aria-label="Toggle navigation" 194 > 195 <span class="navbar-toggler-icon"></span> 196 </button> 197 </div> 198 199 <!-- Navigation links --> 200 <div 201 class="collapse navbar-collapse overlay-translucent order-lg-2" 202 id="primaryNavigation" 203 > 204 <ul class="navbar-nav"> 205 <li class="nav-item"><a class="nav-link" href="/pricing">Pricing</a></li> 206 <li class="nav-item"><a class="nav-link" href="/#about">About</a></li> 207 <li class="nav-item"><a class="nav-link" href="/support">Support</a></li> 208 </ul> 209 </div> 210 </div> 211</nav> 212 213 <section class="landing-section"> 214 <div class="block block-hero-content centered"> 215 <div class="container"> 216 <div class="hero-prose"> 217 <h1>API Documentation</h1> 218 219 <p class="lead"> 220 Programmatic access to your podcast data. Pull download metrics, 221 list your podcasts, and integrate with your own tools. 222 </p> 223 </div> 224 </div> 225 </div> 226 227 228<div class="divider"> 229<svg version="1.1" xmlns="http://www.w3.org/2000/svg" 230 xmlns:xlink="http://www.w3.org/1999/xlink" 231 x="0px" y="0px" 232 width="100%" height="100%"
233 viewBox="0 200 1600 700" 234 preserveAspectRatio="none"> 235 <defs> 236 <!-- Wave 1: Original wave with moderate amplitude --> 237 <path id="wave-0f47518bd0905370-1" fill="var(--fs-body-bg)" d="M-1200,380c0,0,236.988-180,505.475,0 238s371.981,170,575.971,0s293.985-170,505.474,22s493.475,190,716.963-22s400,0,800,0s400,0,800,0v560.106H-1200V380z" /> 239 240 <!-- Wave 2: Higher amplitude, more dramatic curves --> 241 <path id="wave-0f47518bd0905370-2" fill="var(--fs-body-bg)" d="M-1200,320c0,0,200.988-220,450.475,0 242s320.981,200,520.971,0s250.985-200,450.474,30s420.475,220,620.963-30s400,0,800,0s400,0,800,0v560.106H-1200V320z" /> 243 244 <!-- Wave 3: Lower amplitude, gentler curves --> 245 <path id="wave-0f47518bd0905370-3" fill="var(--fs-body-bg)" d="M-1200,400c0,0,280.988-140,580.475,0 246s420.981,130,620.971,0s350.985-130,580.474,20s550.475,160,750.963-20s400,0,800,0s400,0,800,0v560.106H-1200V400z" /> 247 </defs> 248 <g> 249 <use xlink:href='#wave-0f47518bd0905370-1' 250 opacity="0.3" 251 transform="translate(400, 110)" /> 252 <use xlink:href='#wave-0f47518bd0905370-2' 253 opacity="0.3" 254 transform="translate(-300, 130)" /> 255 <use xlink:href='#wave-0f47518bd0905370-3' 256 opacity="1.0" 257 transform="translate(100, 250)" /> 258 </g> 259</svg> 260</div> 261 </section> 262 263 </header> 264 265 <main id="main" tabindex="-1"> 266 267 268<section class="landing-section"> 269 <div class="container"> 270 <div class="row"> 271 <div class="col-lg-8 mx-auto"> 272 273 274 <h2 id="authentication" class="mt-5 mb-3">Authentication</h2> 275 276 <p> 277 All API requests require a Bearer token in the <code>Authorization</code> header. 278 Create API keys from your 279 <a href="https://app.fireside.fm/api_tokens">account settings</a>. 280 </p> 281 282 <pre><code>Authorization: Bearer fire_your_token_here</code></pre> 283 284 <p> 285 Tokens use the <code>fire_</code> prefix followed by 64 hex characters. 286 The raw token is shown once at creation — store it securely. 287 If a token is lost, revoke it and create a new one. 288 </p> 289 290 <p>Invalid or missing tokens return <strong>401 Unauthorized</strong>:</p> 291 292<pre><code>{ 293 "error": { 294 "message": "Invalid or missing API token", 295 "code": "unauthorized" 296 } 297}</code></pre> 298 299 300 <h2 id="base-url" class="mt-5 mb-3">Base URL</h2> 301 302 <p>All endpoints are under the <code>/api/v1/</code> namespace:</p> 303 304 <pre><code>https://fireside.fm/api/v1/</code></pre> 305 306 <p>All responses are JSON. Endpoints return appropriate HTTP status codes:</p> 307 308 <ul> 309 <li><code>200</code> — Success</li> 310 <li><code>401</code> — Invalid or missing token</li> 311 <li><code>404</code> — Resource not found (or not accessible to your account)</li> 312 <li><code>429</code> — Rate limit exceeded</li> 313 </ul> 314 315 316 <h2 id="rate-limiting" class="mt-5 mb-3">Rate Limiting</h2> 317 318 <p> 319 API requests are limited to <strong>30 requests per minute</strong> per API token, 320 or per IP address for unauthenticated requests. Every response includes rate limit headers: 321 </p> 322 323 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 324 <table class="table mt-3"> 325 <thead> 326 <tr> 327 <th>Header</th> 328 <th>Description</th> 329 </tr> 330 </thead> 331 <tbody> 332 <tr> 333 <td><code>X-RateLimit-Limit</code></td> 334 <td>Maximum requests per minute</td> 335 </tr> 336 <tr> 337 <td><code>X-RateLimit-Remaining</code></td> 338 <td>Requests remaining in the current window</td> 339 </tr> 340 <tr> 341 <td><code>Retry-After</code></td> 342 <td>Seconds to wait before retrying (only on 429 responses)</td> 343 </tr> 344 </tbody> 345 </table> 346 </div> 347 348 <p>When the limit is exceeded, the API returns <strong>429 Too Many Requests</strong>:</p> 349 350<pre><code>{ 351 "error": { 352 "message": "Rate limit exceeded.", 353 "code": "rate_limited" 354 } 355}</code></pre> 356 357 358 <h2 id="podcasts" class="mt-5 mb-3">List Podcasts</h2> 359 360 <pre><code>GET /api/v1/podcasts</code></pre> 361 362 <p>
363 Returns all podcasts you own or collaborate on. Only complete, 364 active podcasts are included. Results are paginated (50 per page). 365 </p> 366 367 <h3 class="h5 mt-4">Parameters</h3> 368 369 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 370 <table class="table mt-3"> 371 <thead> 372 <tr> 373 <th>Parameter</th> 374 <th>Type</th> 375 <th>Default</th> 376 <th>Description</th> 377 </tr> 378 </thead> 379 <tbody> 380 <tr> 381 <td><code>page</code></td> 382 <td>integer</td> 383 <td>1</td> 384 <td>Page number</td> 385 </tr> 386 </tbody> 387 </table> 388 </div> 389 390 <h3 class="h5 mt-4">Response</h3> 391 392<pre><code>{ 393 "data": [ 394 { 395 "token": "550e8400-e29b-41d4-a716-446655440000", 396 "title": "My Podcast", 397 "slug": "my-podcast", 398 "description": "A podcast about things.", 399 "subtitle": "Things and stuff", 400 "author_name": "Jane Doe", 401 "language": "en-us", 402 "explicit": false, 403 "artwork_url": "https://storage.example.com/covers/my-podcast.jpg", 404 "created_at": "2024-01-15T12:00:00Z" 405 } 406 ], 407 "pagination": { 408 "page": 1, 409 "per_page": 50, 410 "previous": null, 411 "next": 2 412 } 413}</code></pre> 414 415 <p> 416 The podcast fields are the same as the 417 <a href="#podcast-show">Get Podcast</a> endpoint, except 418 <code>total_downloads</code> which is only available on the 419 show endpoint. 420 </p> 421 422 423 <h2 id="podcast-show" class="mt-5 mb-3">Get Podcast</h2> 424 425 <pre><code>GET /api/v1/podcasts/:podcast_token</code></pre> 426 427 <p>Returns details for a single podcast, including <code>total_downloads</code>.</p> 428 429 <h3 class="h5 mt-4">Response</h3> 430 431<pre><code>{ 432 "data": { 433 "token": "550e8400-e29b-41d4-a716-446655440000", 434 "title": "My Podcast", 435 "slug": "my-podcast", 436 "description": "A podcast about things.", 437 "subtitle": "Things and stuff", 438 "author_name": "Jane Doe", 439 "language": "en-us", 440 "explicit": false, 441 "artwork_url": "https://storage.example.com/covers/my-podcast.jpg", 442 "total_downloads": 50000, 443 "created_at": "2024-01-15T12:00:00Z" 444 } 445}</code></pre> 446 447 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 448 <table class="table mt-3"> 449 <thead> 450 <tr> 451 <th>Field</th> 452 <th>Type</th> 453 <th>Description</th> 454 </tr> 455 </thead> 456 <tbody> 457 <tr> 458 <td><code>token</code></td> 459 <td>string</td> 460 <td>Unique podcast identifier (UUID). Use this in other API calls.</td> 461 </tr> 462 <tr> 463 <td><code>title</code></td> 464 <td>string</td> 465 <td>Podcast title</td> 466 </tr> 467 <tr> 468 <td><code>slug</code></td> 469 <td>string</td> 470 <td>URL slug</td> 471 </tr> 472 <tr> 473 <td><code>description</code></td> 474 <td>string</td> 475 <td>Podcast description</td> 476 </tr> 477 <tr> 478 <td><code>subtitle</code></td> 479 <td>string or null</td> 480 <td>Podcast subtitle</td> 481 </tr> 482 <tr> 483 <td><code>author_name</code></td> 484 <td>string</td> 485 <td>Author name</td> 486 </tr> 487 <tr> 488 <td><code>language</code></td> 489 <td>string</td> 490 <td>Language code (e.g. "en-us")</td> 491 </tr> 492 <tr> 493 <td><code>explicit</code></td> 494 <td>boolean</td> 495 <td>Whether the podcast is marked explicit</td> 496 </tr> 497 <tr> 498 <td><code>artwork_url</code></td> 499 <td>string or null</td> 500 <td>URL to the podcast cover artwork</td> 501 </tr> 502 <tr> 503 <td><code>total_downloads</code></td> 504 <td>integer</td> 505 <td>All-time total downloads for the podcast (show endpoint only)</td> 506 </tr> 507 <tr> 508 <td><code>created_at</code></td> 509 <td>string</td> 510 <td>Creation timestamp (ISO 8601)</td> 511 </tr> 512 </tbody> 513 </table> 514 </div> 515 516 517 <h2 id="episode-metrics" class="mt-5 mb-3">Episode Metrics</h2> 518 519 <pre><code>GET /api/v1/podcasts/:podcast_token/metrics/episodes</code></pre> 520 521 <p> 522 Per-episode download statistics for all published episodes, 523 ordered by publish date (newest first). Results are paginated (100 per page). 524 </p> 525 526 <h3 class="h5 mt-4">Parameters</h3> 527 528 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 529 <table class="table mt-3"> 530 <thead> 531 <tr> 532 <th>Parameter</th> 533 <th>Type</th> 534 <th>Default</th> 535 <th>Description</th> 536 </tr> 537 </thead> 538 <tbody> 539 <tr> 540 <td><code>page</code></td> 541 <td>integer</td> 542 <td>1</td> 543 <td>Page number</td> 544 </tr> 545 </tbody> 546 </table> 547 </div> 548 549 <h3 class="h5 mt-4">Response</h3> 550 551<pre><code>{ 552 "data": [ 553 { 554 "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", 555 "title": "Episode Title", 556 "slug": "episode-slug", 557 "url": "https://mypodcast.fireside.fm/episode-slug", 558 "season": 2, 559 "duration": 1830, 560 "explicit": false, 561 "published_at": "2026-03-01T00:00:00-05:00", 562 "downloads": { 563 "1_day": 500, 564 "7_day": 1200, 565 "14_day": 1800, 566 "30_day": 2500, 567 "90_day": 4000, 568 "spotify": 300, 569 "total": 5000 570 } 571 } 572 ], 573 "pagination": { 574 "page": 1, 575 "per_page": 100, 576 "previous": null, 577 "next": 2 578 } 579}</code></pre> 580 581 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 582 <table class="table mt-3"> 583 <thead> 584 <tr> 585 <th>Field</th> 586 <th>Type</th> 587 <th>Description</th> 588 </tr> 589 </thead> 590 <tbody> 591 <tr> 592 <td><code>token</code></td> 593 <td>string</td> 594 <td>Unique episode identifier</td> 595 </tr> 596 <tr> 597 <td><code>title</code></td> 598 <td>string</td> 599 <td>Episode title</td> 600 </tr> 601 <tr> 602 <td><code>slug</code></td> 603 <td>string</td> 604 <td>URL slug for the episode</td> 605 </tr> 606 <tr> 607 <td><code>url</code></td> 608 <td>string</td> 609 <td>Full URL to the episode page</td> 610 </tr> 611 <tr> 612 <td><code>season</code></td> 613 <td>integer or null</td> 614 <td>Season number</td> 615 </tr> 616 <tr> 617 <td><code>duration</code></td> 618 <td>integer or null</td> 619 <td>Duration in seconds</td> 620 </tr> 621 <tr> 622 <td><code>explicit</code></td> 623 <td>boolean</td> 624 <td>Whether the episode is marked explicit</td> 625 </tr> 626 <tr> 627 <td><code>published_at</code></td> 628 <td>string</td> 629 <td>Publish timestamp (ISO 8601)</td> 630 </tr> 631 <tr> 632 <td><code>downloads.1_day</code></td> 633 <td>integer or null</td> 634 <td>Downloads within 1 day of publish. <code>null</code> if not enough time has passed.</td> 635 </tr> 636 <tr> 637 <td><code>downloads.7_day</code></td> 638 <td>integer or null</td> 639 <td>Downloads within 7 days of publish</td> 640 </tr> 641 <tr> 642 <td><code>downloads.14_day</code></td> 643 <td>integer or null</td> 644 <td>Downloads within 14 days of publish</td> 645 </tr> 646 <tr> 647 <td><code>downloads.30_day</code></td> 648 <td>integer or null</td> 649 <td>Downloads within 30 days of publish</td> 650 </tr> 651 <tr> 652 <td><code>downloads.90_day</code></td> 653 <td>integer or null</td> 654 <td>Downloads within 90 days of publish</td> 655 </tr> 656 <tr> 657 <td><code>downloads.spotify</code></td> 658 <td>integer</td> 659 <td>Total Spotify streams, or 0 when the podcast has none. Already counted inside <code>downloads.total</code>.</td> 660 </tr> 661 <tr> 662 <td><code>downloads.total</code></td> 663 <td>integer</td> 664 <td>All-time total downloads for this episode, including any Spotify streams</td> 665 </tr> 666 <tr> 667 <td><code>pagination.page</code></td> 668 <td>integer</td> 669 <td>Current page number</td> 670 </tr> 671 <tr> 672 <td><code>pagination.per_page</code></td> 673 <td>integer</td> 674 <td>Results per page</td> 675 </tr> 676 <tr> 677 <td><code>pagination.previous</code></td> 678 <td>integer or null</td> 679 <td>Previous page number, or <code>null</code> if on the first page</td> 680 </tr> 681 <tr> 682 <td><code>pagination.next</code></td> 683 <td>integer or null</td> 684 <td>Next page number, or <code>null</code> if on the last page</td> 685 </tr> 686 </tbody> 687 </table> 688 </div> 689 690 691 <h2 id="downloads" class="mt-5 mb-3">Downloads by Month</h2> 692 693 <pre><code>GET /api/v1/podcasts/:podcast_token/metrics/downloads</code></pre> 694 695 <p>Monthly download totals for the podcast, in reverse chronological order. Results are paginated (36 per page).</p> 696 697 <h3 class="h5 mt-4">Parameters</h3> 698 699 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 700 <table class="table mt-3"> 701 <thead> 702 <tr> 703 <th>Parameter</th> 704 <th>Type</th> 705 <th>Default</th> 706 <th>Description</th> 707 </tr> 708 </thead> 709 <tbody> 710 <tr> 711 <td><code>page</code></td> 712 <td>integer</td> 713 <td>1</td> 714 <td>Page number</td> 715 </tr> 716 </tbody> 717 </table> 718 </div> 719 720 <h3 class="h5 mt-4">Response</h3> 721 722<pre><code>{ 723 "data": [ 724 { "date": "2026-03-01", "value": 1500 }, 725 { "date": "2026-02-01", "value": 1200 } 726 ], 727 "meta": { 728 "total_downloads": 50000 729 }, 730 "pagination": { 731 "page": 1, 732 "per_page": 36, 733 "previous": null, 734 "next": 2 735 } 736}</code></pre> 737 738 <div class="table-responsive" tabindex="0" role="region" aria-label="API reference table"> 739 <table class="table mt-3"> 740 <thead> 741 <tr> 742 <th>Field</th> 743 <th>Type</th> 744 <th>Description</th> 745 </tr> 746 </thead> 747 <tbody> 748 <tr> 749 <td><code>data[].date</code></td> 750 <td>string</td> 751 <td>
751First day of the period (YYYY-MM-DD)</td> 752 </tr> 753 <tr> 754 <td><code>data[].value</code></td> 755 <td>integer</td> 756 <td>Total downloads for that period</td> 757 </tr> 758 <tr> 759 <td><code>meta.total_downloads</code></td> 760 <td>integer</td> 761 <td>All-time total downloads for the podcast</td> 762 </tr> 763 <tr> 764 <td><code>pagination.page</code></td> 765 <td>integer</td> 766 <td>Current page number</td> 767 </tr> 768 <tr> 769 <td><code>pagination.per_page</code></td> 770 <td>integer</td> 771 <td>Results per page</td> 772 </tr> 773 <tr> 774 <td><code>pagination.previous</code></td> 775 <td>integer or null</td> 776 <td>Previous page number, or <code>null</code> if on the first page</td> 777 </tr> 778 <tr> 779 <td><code>pagination.next</code></td> 780 <td>integer or null</td> 781 <td>Next page number, or <code>null</code> if on the last page</td> 782 </tr> 783 </tbody> 784 </table> 785 </div> 786 787 788 <h2 id="quick-start" class="mt-5 mb-3">Quick Start</h2> 789 790 <p>1. Create an API key from your <a href="https://app.fireside.fm/api_tokens">API Keys page</a>.</p> 791 792 <p>2. List your podcasts:</p> 793 794<pre><code>curl -H "Authorization: Bearer fire_your_token" \ 795 https://fireside.fm/api/v1/podcasts</code></pre> 796 797 <p>3. Get episode metrics using a podcast token from the response:</p> 798 799<pre><code>curl -H "Authorization: Bearer fire_your_token" \ 800 https://fireside.fm/api/v1/podcasts/PODCAST_TOKEN/metrics/episodes</code></pre> 801 802 <p>4. Get monthly downloads:</p> 803 804<pre><code>curl -H "Authorization: Bearer fire_your_token" \ 805 https://fireside.fm/api/v1/podcasts/PODCAST_TOKEN/metrics/downloads</code></pre> 806 807 </div> 808 </div> 809 </div> 810</section> 811 812 </main> 813 814 <section class="landing-section bg-gradient-charcoal text-white landing-site-footer"> 815 816<div class="divider"> 817<svg version="1.1" xmlns="http://www.w3.org/2000/svg" 818 xmlns:xlink="http://www.w3.org/1999/xlink" 819 x="0px" y="0px" 820 width="100%" height="100%" 821 viewBox="0 200 1600 700" 822 preserveAspectRatio="none"> 823 <defs> 824 <!-- Wave 1: Original wave with moderate amplitude --> 825 <path id="wave-76f22d4b963e1f7b-1" fill="var(--fs-body-bg)" d="M-1200,380c0,0,236.988-180,505.475,0 826s371.981,170,575.971,0s293.985-170,505.474,22s493.475,190,716.963-22s400,0,800,0s400,0,800,0v560.106H-1200V380z" /> 827 828 <!-- Wave 2: Higher amplitude, more dramatic curves --> 829 <path id="wave-76f22d4b963e1f7b-2" fill="var(--fs-body-bg)" d="M-1200,320c0,0,200.988-220,450.475,0 830s320.981,200,520.971,0s250.985-200,450.474,30s420.475,220,620.963-30s400,0,800,0s400,0,800,0v560.106H-1200V320z" /> 831 832 <!-- Wave 3: Lower amplitude, gentler curves --> 833 <path id="wave-76f22d4b963e1f7b-3" fill="var(--fs-body-bg)" d="M-1200,400c0,0,280.988-140,580.475,0 834s420.981,130,620.971,0s350.985-130,580.474,20s550.475,160,750.963-20s400,0,800,0s400,0,800,0v560.106H-1200V400z" /> 835 </defs> 836 <g> 837 <use xlink:href='#wave-76f22d4b963e1f7b-1' 838 opacity="0.3" 839 transform="translate(450, 95)" /> 840 <use xlink:href='#wave-76f22d4b963e1f7b-2' 841 opacity="0.3" 842 transform="translate(-500, 185)" /> 843 <use xlink:href='#wave-76f22d4b963e1f7b-3' 844 opacity="1.0" 845 transform="translate(-200, 285)" /> 846 </g> 847</svg> 848</div> 849 850 <div class="container"> 851 852<div class="site-map"> 853 854 <div class="site-map__container"> 855 <div class="site-map__grid"> 856 <!-- Logo Column --> 857 <div class="site-map__column site-map__column--brand"> 858 <p class="site-map__brand-description"> 859 Fireside is a podcast hosting platform that grows with you. From your first episode to millions of downloads, we make it simple to share your voice with the world. 860 </p> 861 862 <a class="site-map__brand" href="/"> 863 <img alt="Fireside" height="36" loading="lazy" src="https://a.fireside.fm/assets/v2/shared/identity/symbol_red-33a25ed9b51284c569be1ae7950e67e9a9238c1051b9f219479f449137bbe1f4.svg" /> 864</a> </div> 865 866 <!-- Navigation Columns --> 867 <div class="site-map__column"> 868 <h3 class="site-map__column-title">Product</h3> 869 870 <ul class="site-map__link-list"> 871 <li class="site-map__link-item"> 872 <a class="site-map__link" href="/#product">Product</a> 873 </li> 874 <li class="site-map__link-item"> 875 <a class="site-map__link" href="/pricing">Pricing</a> 876 </li> 877 <li class="site-map__link-item"> 878 <a class="site-map__link" href="https://app.fireside.fm/sign_up">Create an account</a> 879 </li> 880 </ul> 881 </div> 882 <div class="site-map__column"> 883 <h3 class="site-map__column-title">Learn</h3> 884 885 <ul class="site-map__link-list"> 886 <li class="site-map__link-item"> 887 <a class="site-map__link" href="/#start">Start a podcast</a> 888 </li> 889 <li class="site-map__link-item"> 890 <a class="site-map__link" href="/#migrate">Move a podcast</a> 891 </li> 892 <li class="site-map__link-item"> 893 <a class="site-map__link" href="/docs/api">API Documentation</a> 894 </li> 895 </ul> 896 </div> 897 <div class="site-map__column"> 898 <h3 class="site-map__column-title">Connect</h3> 899 900 <ul class="site-map__link-list"> 901 <li class="site-map__link-item"> 902 <a class="site-map__link" href="/support">Support</a> 903 </li> 904 <li class="site-map__link-item"> 905 <a class="site-map__link" href="https://blog.fireside.fm">Our Blog</a> 906 </li> 907 <li class="site-map__link-item"> 908 <a class="site-map__link" href="https://standinginthefire.fireside.fm">Our Podcast</a> 909 </li> 910 </ul> 911 </div> 912 </div> 913 </div> 914</div> 915 <hr class="container"> 916 917<footer class="footer">
918 <div class="footer__container"> 919 920 921 <div class="footer__content"> 922 923 <div class="footer__social"> 924 <ul class="footer__social-list"> 925 <li class="footer__social-item"> 926 <a href="https://bsky.app/profile/fireside.fm" 927 class="footer__social-link footer__social-link--bluesky" 928 aria-label="Follow us on Bluesky" 929 target="_blank" 930 rel="noopener noreferrer"> 931 <i class="fa-brands fa-bluesky" aria-hidden="true"></i> 932 </a> 933 </li> 934 <li class="footer__social-item"> 935 <a href="https://x.com/firesidefm" 936 class="footer__social-link footer__social-link--x" 937 aria-label="Follow us on X" 938 target="_blank" 939 rel="noopener noreferrer"> 940 <i class="fa-brands fa-x-twitter" aria-hidden="true"></i> 941 </a> 942 </li> 943 <li class="footer__social-item"> 944 <a href="https://linkedin.com/company/firesidefm" 945 class="footer__social-link footer__social-link--linkedin" 946 aria-label="Connect with us on LinkedIn" 947 target="_blank" 948 rel="noopener noreferrer"> 949 <i class="fa-brands fa-linkedin" aria-hidden="true"></i> 950 </a> 951 </li> 952 <li class="footer__social-item"> 953 <a href="https://www.instagram.com/fireside.fm/" 954 class="footer__social-link footer__social-link--instagram" 955 aria-label="Follow us on Instagram" 956 target="_blank" 957 rel="noopener noreferrer"> 958 <i class="fa-brands fa-instagram" aria-hidden="true"></i> 959 </a> 960 </li> 961 <li class="footer__social-item"> 962 <a href="https://www.youtube.com/@standinginthefirepod" 963 class="footer__social-link footer__social-link--youtube" 964 aria-label="Fireside on YouTube" 965 target="_blank" 966 rel="noopener noreferrer"> 967 <i class="fa-brands fa-youtube" aria-hidden="true"></i> 968 </a> 969 </li> 970 </ul> 971 </div> 972 973 <div class="footer__trust"> 974 <ul class="footer__trust-list"> 975 <li class="footer__trust-item"> 976 <a class="footer__trust-link" href="/trust/accessibility">Accessibility</a> 977 </li> 978 <li class="footer__trust-item"> 979 <a class="footer__trust-link" href="/trust/cookies">Cookies</a> 980 </li> 981 <li class="footer__trust-item"> 982 <a class="footer__trust-link" href="/dmca">DMCA</a> 983 </li> 984 <li class="footer__trust-item"> 985 <a class="footer__trust-link" href="/trust/privacy">Privacy</a> 986 </li> 987 <li class="footer__trust-item"> 988 <a class="footer__trust-link" href="/trust/terms">Terms of Service</a> 989 </li> 990 <li class="footer__trust-item"> 991 <div class="footer__theme-toggle dropup" data-component="theme-toggler"> 992 <button type="button" 993 class="footer__theme-btn dropdown-toggle" 994 id="bd-theme" 995 data-bs-toggle="dropdown" 996 data-bs-display="static" 997 aria-expanded="false" 998 aria-label="Toggle theme (auto)"> 999 <i data-fa-symbol="circle-half-stroke" class="fa-solid fa-circle-half-stroke theme-icon-active" aria-hidden="true"></i> 1000 <span class="footer__theme-label" id="bd-theme-text">Theme</span> 1001 </button> 1002 <ul class="dropdown-menu overlay-translucent" aria-labelledby="bd-theme-text"> 1003 <li> 1004 <button type="button" class="dropdown-item d-flex align-items-center gap-2 active" data-bs-theme-value="auto" aria-pressed="true"> 1005 <i data-fa-symbol="circle-half-stroke" class="fa-solid fa-circle-half-stroke opacity-50" aria-hidden="true"></i> 1006 <small>Auto</small> 1007 </button> 1008 </li> 1009 <li> 1010 <button type="button" class="dropdown-item d-flex align-items-center gap-2" data-bs-theme-value="light" aria-pressed="false">
1011 <i data-fa-symbol="sun" class="fa-solid fa-sun opacity-50" aria-hidden="true"></i> 1012 <small>Light</small> 1013 </button> 1014 </li> 1015 <li> 1016 <button type="button" class="dropdown-item d-flex align-items-center gap-2" data-bs-theme-value="dark" aria-pressed="false"> 1017 <i data-fa-symbol="moon" class="fa-solid fa-moon opacity-50" aria-hidden="true"></i> 1018 <small>Dark</small> 1019 </button> 1020 </li> 1021 </ul> 1022 </div> 1023 </li> 1024 </ul> 1025 1026 <div class="footer__copyright"> 1027 <span class="footer__copyright-text">© 2026 Very Good Software, LLC All rights reserved.</span> 1028 </div> 1029 </div> 1030 </div> 1031 </div> 1032</footer> 1033 1034 </div> 1035 </section> 1036 1037
1037<script src="https://a.fireside.fm/assets/v2/shared/fireside-c8fd9c0962da070f90aeb1f78aca5e682129adb5e33372e8e05d998fdc4a8abd.js" defer="defer"></script>
1037 1038
1038<script src="https://a.fireside.fm/assets/v2/bootstrap5/bootstrap-ad585bcf4b4c07a47857ec07cafe657429d5c1f412dcb48ec324bd2d79a2ac46.js" defer="defer"></script>
1038 1039
1039<script src="https://a.fireside.fm/assets/v2/bootstrap5/light_dark_toggle-4b75a288c96f5e202c605aaeff66bd87a45fc82165a17f296252e8ab61ea805a.js" type="module" defer="defer"></script>
1039 1040
1040<script src="https://a.fireside.fm/assets/v2/bootstrap5/initializers-884a351b84598af96f972cbd9187a8f241b73b7d2022b883fef45ecc667a42df.js" defer="defer"></script>
1040 1041 1042 </body> 1043</html> 1044
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.