Thrive Global search API

openapi: 3.0.0
info:
  title: Thrive Global Partner audio experiences search 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: search
  description: Search the full Thrive content library (premium capability — contact your Thrive Global representative to enable)
paths:
  /v1/search:
    get:
      operationId: searchContent
      tags:
      - search
      summary: Search the Thrive content library
      description: 'Search the entire Thrive content library — Resets, Stories, Microsteps, Courses, Podcasts, Journeys, Challenges, Soundscapes, Bedtime Stories, and Meditations — in a single request. Every match is returned as a complete, ready-to-render item, so there are no follow-up by-id calls to make.


        **Thrive Search is a premium capability of the Partner API.** To enable it for your organisation, contact your Thrive Global representative. Once enabled, your existing bearer token unlocks this endpoint automatically — no new credentials required. Requests made before Search is enabled return `403 Forbidden`.


        Results are returned in relevance order, capped at approximately 20 hits, and are not paginated. This endpoint responds with a bare `{ data: [...] }` array rather than the `{ message, valid, data }` envelope used by the collection endpoints.'
      security:
      - BearerAuth: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
        description: Search text (min length 1)
        example: sleep
      - name: types
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated content types to search: reset, story, microstep, learnCourse, podcast, journey, challenge, soundscape, bedtime-story, meditation. Omitted = all ten. An unknown value returns 422.'
        example: reset,podcast,soundscape
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: en-US
        description: Locale, forwarded as the thrive-locale header
      responses:
        '200':
          description: Search results in relevance order
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultItem'
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '403':
          description: Forbidden — Thrive Search is not enabled for your account. Contact your Thrive Global representative to enable it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
        '422':
          description: Invalid query parameters (e.g. unknown type, missing query)
          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
components:
  schemas:
    SearchResultItem:
      type: object
      description: A search result. Items of type `soundscape`, `bedtime-story`, or `meditation` carry the same fields as SoundscapeItem / BedtimeStoryItem / MeditationItem plus `snippet`, without `media` and without the `title`/`mediaType` fields. Other types carry the base fields below; additional fields depend on `type` (e.g. a reset carries manifestUrl/themes, a podcast carries summary). Every result carries the taxonomy fields `tags`/`conditions`/`coreHealthBehaviors` as term objects (empty arrays where no values apply). Search items deliberately omit `createdAt`/`updatedAt` for a consistent shape across types — use the dedicated by-id endpoint when you need timestamps.
      required:
      - id
      - type
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - reset
          - story
          - microstep
          - learnCourse
          - podcast
          - journey
          - challenge
          - soundscape
          - bedtime-story
          - meditation
        mediaType:
          type: string
          enum:
          - AUDIO
          - TEXT
          - VIDEO
          description: Absent on soundscape, bedtime-story, and meditation items
        title:
          type: string
          description: Absent on soundscape, bedtime-story, and meditation items (use `name`)
        snippet:
          type: string
          nullable: true
          description: Matched text, highlight markup stripped
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
          description: Tags as term objects; may be empty.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
          description: Health conditions as term objects; empty for most types today.
        coreHealthBehaviors:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyTerm'
          description: Core health behaviors as term objects; populated for challenges (from journeys), empty for most other types today.
      additionalProperties: true
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT