Thrive Global audio experiences API

openapi: 3.0.0
info:
  title: Thrive Global Partner audio experiences API
  description: 'API for accessing Thrive Global content and features. All content endpoints require a Bearer token obtained via the authentication endpoint.


    Response envelopes follow the pattern `{ message, valid, data }` where `data` contains the response payload. Collection endpoints nest items at a resource-specific path (e.g. `data.data.reset.thrive.get.items`).'
  version: 1.7.0
  contact:
    name: Thrive Global
    url: https://thriveglobal.com/contact/sales
servers:
- url: https://partners-api.thriveglobal.com
  description: Production server
- url: https://partners-api-stag.thriveglobal.com
  description: Staging server
tags:
- name: audio experiences
  description: Ambient soundscapes and narrated bedtime stories — audio for focus, relaxation, and sleep
paths:
  /v1/soundscapes:
    get:
      operationId: listSoundscapes
      tags:
      - audio experiences
      summary: List soundscapes
      description: Returns a paginated list of soundscapes — ambient audio tracks such as rainfall, ocean waves, and forest sounds that support focus, relaxation, and sleep. Each soundscape includes its playable audio, duration, imagery, captions where available, and tags.
      security:
      - BearerAuth: []
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Zero-based item offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: Page size. Values above 100 are clamped to 100, not rejected; `meta.pagination` reports the applied value.
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: en-US
        description: Locale, forwarded as the thrive-locale header
      responses:
        '200':
          description: A page of soundscapes
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                - links
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SoundscapeItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '422':
          description: Invalid query parameters (e.g. negative offset, zero limit)
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    example: 422
                  errors:
                    type: array
                    items:
                      type: object
        '502':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service temporarily unavailable
  /v1/soundscapes/{id}:
    get:
      operationId: getSoundscapeById
      tags:
      - audio experiences
      summary: Get a soundscape by id
      description: Returns a single soundscape by its id, including its playable audio, duration, imagery, captions where available, and tags. Returns `404` when no soundscape exists for the id and `422` when the id is not a UUID.
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Soundscape id
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: en-US
        description: Locale, forwarded as the thrive-locale header
      responses:
        '200':
          description: The soundscape
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SoundscapeItem'
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '404':
          description: No soundscape exists for the id
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not found
        '422':
          description: Invalid id (must be a UUID) or query parameters
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    example: 422
                  errors:
                    type: array
                    items:
                      type: object
        '502':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service temporarily unavailable
  /v1/bedtime-stories:
    get:
      operationId: listBedtimeStories
      tags:
      - audio experiences
      summary: List bedtime stories
      description: Returns a paginated list of bedtime stories — narrated audio stories that help listeners unwind and fall asleep. Each bedtime story includes its playable audio, duration, imagery, captions where available, and tags.
      security:
      - BearerAuth: []
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Zero-based item offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: Page size. Values above 100 are clamped to 100, not rejected; `meta.pagination` reports the applied value.
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: en-US
        description: Locale, forwarded as the thrive-locale header
      responses:
        '200':
          description: A page of bedtime stories
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                - links
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BedtimeStoryItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '422':
          description: Invalid query parameters (e.g. negative offset, zero limit)
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    example: 422
                  errors:
                    type: array
                    items:
                      type: object
        '502':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service temporarily unavailable
  /v1/bedtime-stories/{id}:
    get:
      operationId: getBedtimeStoryById
      tags:
      - audio experiences
      summary: Get a bedtime story by id
      description: Returns a single bedtime story by its id, including its playable audio, duration, imagery, captions where available, and tags. Returns `404` when no bedtime story exists for the id and `422` when the id is not a UUID.
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Bedtime story id
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: en-US
        description: Locale, forwarded as the thrive-locale header
      responses:
        '200':
          description: The bedtime story
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BedtimeStoryItem'
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '404':
          description: No bedtime story exists for the id
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not found
        '422':
          description: Invalid id (must be a UUID) or query parameters
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    example: 422
                  errors:
                    type: array
                    items:
                      type: object
        '502':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service temporarily unavailable
components:
  schemas:
    BedtimeStoryItem:
      type: object
      description: A bedtime story — a narrated audio story that helps listeners unwind and fall asleep.
      required:
      - id
      - type
      - name
      - description
      - createdAt
      - updatedAt
      - locale
      - tags
      - conditions
      - coreHealthBehaviors
      - durationInSeconds
      - media
      - assets
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - bedtime-story
        name:
          type: string
          example: The Sleepy Lighthouse
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        locale:
          type: string
          nullable: true
          description: Served locale, not request echo
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        coreHealthBehaviors:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        durationInSeconds:
          type: integer
          example: 1200
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaEntry'
          description: Playable renditions — the bedtime story audio file
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetEntry'
          description: Supporting files — captions and imagery
    PaginationMeta:
      type: object
      description: Applied pagination values — after defaulting and clamping, not what was requested.
      required:
      - pagination
      properties:
        pagination:
          type: object
          required:
          - offset
          - limit
          - total
          properties:
            offset:
              type: integer
              example: 0
            limit:
              type: integer
              example: 10
            total:
              type: integer
              nullable: true
              description: Best-effort display data; null when a total is not available. `links.next != null` is the authoritative "more results exist" signal.
    AssetEntry:
      type: object
      description: 'A supporting file: images, thumbnails, captions, transcripts.'
      required:
      - role
      - contentType
      - url
      - alt
      properties:
        role:
          type: string
          enum:
          - captions
          - transcript
          - image-landscape
          - image-portrait
          - thumbnail-landscape
          - thumbnail-portrait
          - image-featured
        contentType:
          type: string
          nullable: true
          example: image/jpeg
        url:
          type: string
          format: uri
        alt:
          type: string
          nullable: true
        sizes:
          type: object
          additionalProperties:
            type: string
          description: Explicit size-variant URLs where they exist. Never derive variants by transforming URLs.
    TaxonomyTerm:
      type: object
      description: One shape for all taxonomy layers (`tags`, `conditions`, `coreHealthBehaviors`). `id` is the durable key — persist this, not `slug`. `slug` is the kebab-case machine key used in query-parameter filters and may change if the term is renamed. `name` is the display string.
      required:
      - id
      - slug
      - name
      properties:
        id:
          type: string
          nullable: true
          description: Stable identifier for the term; null where none exists
        slug:
          type: string
          example: sleep
        name:
          type: string
          nullable: true
          example: Sleep
    PaginationLinks:
      type: object
      description: Opaque pagination URLs — follow `next` until it is null; do not parse them. All three attributes are always present (null when there is no such page).
      required:
      - self
      - next
      - prev
      properties:
        self:
          type: string
          example: /v1/soundscapes?offset=0&limit=10
        next:
          type: string
          nullable: true
          example: /v1/soundscapes?offset=10&limit=10
        prev:
          type: string
          nullable: true
          example: null
    SoundscapeItem:
      type: object
      description: A soundscape — an ambient audio track that supports focus, relaxation, and sleep.
      required:
      - id
      - type
      - name
      - description
      - createdAt
      - updatedAt
      - locale
      - tags
      - conditions
      - coreHealthBehaviors
      - durationInSeconds
      - media
      - assets
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - soundscape
        name:
          type: string
          example: Forest Rain
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        locale:
          type: string
          nullable: true
          description: Served locale, not request echo
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        coreHealthBehaviors:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
        durationInSeconds:
          type: integer
          nullable: true
          example: 600
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaEntry'
          description: Playable renditions — the soundscape audio file
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetEntry'
          description: Supporting files — captions and imagery
    MediaEntry:
      type: object
      description: A playable rendition. No entry means the rendition does not exist — never null placeholders.
      required:
      - kind
      - orientation
      - contentType
      - url
      properties:
        kind:
          type: string
          enum:
          - file
          - manifest
          - embed
        orientation:
          type: string
          enum:
          - landscape
          - portrait
          nullable: true
        contentType:
          type: string
          nullable: true
          example: audio/mpeg
          description: MIME type where known
        url:
          type: string
          format: uri
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT