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

# Get Devotionals

> Retrieve devotionals for the authenticated user's church. When X-Client-Date header is provided, returns a single devotional for that date with metadata. Otherwise, returns a paginated list of devotionals.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/devotionals
openapi: 3.1.0
info:
  title: TheFaithApp Partner API
  version: 1.0.0
  description: >-
    The v1 API for third-party apps that sign in TheFaithApp members and access
    church-scoped content and workflows.
  contact:
    name: TheFaithApp Support
    email: support@thefaithapp.com
servers:
  - url: https://api.thefaithapp.com
    description: Production
security:
  - apiKeyAuth: []
    bearerAuth: []
tags:
  - name: Hosted Auth
    description: Sign members in through the hosted TheFaithApp authentication flow.
  - name: Core Experience
    description: Load member context and the personalized home experience.
  - name: Content
    description: >-
      Read sermons, media, YouTube videos, devotionals, and streaming
      configuration.
  - name: Engagement
    description: Manage member favorites and devotional bookmarks.
  - name: Churches
    description: Read church profiles, public directory records, and branch information.
  - name: Events & Volunteers
    description: >-
      Browse events and volunteer opportunities, then manage registrations and
      commitments.
  - name: Notifications & Bulletins
    description: Read church and member notifications and published bulletins.
  - name: Prayer
    description: Submit a prayer request for the authenticated member.
  - name: Member Connections
    description: Manage the member’s campus and ministry connections.
  - name: Community Groups
    description: >-
      Discover groups and manage membership, feeds, attendance, study guides,
      and leader notes.
  - name: Community Preferences & Research
    description: >-
      Manage community preferences, summaries, and consent-based research
      participation.
  - name: Resource Sharing
    description: Offer shared resources and manage member loan requests and transitions.
  - name: Mutual Aid
    description: >-
      Manage needs and offers, private responses, safety reports, and member
      activity.
  - name: Analytics
    description: Record product analytics events and retrieve aggregate metrics.
  - name: Notification Analytics
    description: Record and summarize notification delivery, open, and click events.
paths:
  /v1/devotionals:
    get:
      tags:
        - Content
      summary: Get Devotionals
      description: >-
        Retrieve devotionals for the authenticated user's church. When
        X-Client-Date header is provided, returns a single devotional for that
        date with metadata. Otherwise, returns a paginated list of devotionals.
      operationId: getDevotionals
      parameters:
        - name: X-Client-Date
          in: header
          description: >-
            The date for which to retrieve the devotional (format: YYYY-MM-DD).
            If provided, returns a single devotional for that date with
            metadata. If not provided, returns a paginated list of devotionals.
          required: false
          schema:
            type: string
            format: date
        - name: X-Client-Timezone
          in: header
          description: >-
            The timezone to use for date calculations (e.g.,
            'America/New_York'). Only used when X-Client-Date is provided. If
            not provided, uses UTC.
          required: false
          schema:
            type: string
        - name: search
          in: query
          description: >-
            Search term to filter devotionals. Only used when X-Client-Date is
            not provided.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: >-
            Page number for pagination (default: 1). Only used when
            X-Client-Date is not provided.
          required: false
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: >-
            Devotional information. Returns either a single devotional with
            metadata when X-Client-Date is provided, or a paginated list of
            devotionals when no date is specified.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/DevotionalResponse'
                  - $ref: '#/components/schemas/PaginatedDevotionalsResponse'
              examples:
                single_devotional:
                  summary: Response when X-Client-Date header is provided
                  value:
                    devotional:
                      id: 1
                      client_id: 2
                      thumbnail: devotionals/NIh2IeZv2g1k4AoNVhkoQarVWAkSAAnQLrr4DF7j.jpg
                      title: We're Not Mere Humans
                      author: Chris Parker
                      content: <div class="wp-block-media-text alignwide">...</div>
                      bible_reading: >-
                        <p><strong><em>These things have I written unto
                        you...</em></strong></p>
                      confession: <p><strong>CONFESSION</strong></p>...
                      studies: <p><strong>FURTHER STUDY:</strong></p>...
                      date: '2025-05-03T00:00:00.000000Z'
                      created_at: '2025-05-03T06:04:22.000000Z'
                      updated_at: '2025-05-03T06:07:05.000000Z'
                      deleted_at: null
                      tags:
                        - prayer
                      is_recurring: false
                      recurrence_end_date: null
                      version: 1
                      original_id: null
                    metadata:
                      is_recurring: false
                      next_available_date: null
                      has_past_devotionals: false
                    navigation:
                      previous_date: '2024-05-02'
                      next_date: '2024-05-04'
                paginated_list:
                  summary: Response when no X-Client-Date header is provided
                  value:
                    current_page: 1
                    data:
                      - id: 1
                        client_id: 2
                        thumbnail: >-
                          https://d2c58p2vdu8kb2.cloudfront.net/devotionals/NIh2IeZv2g1k4AoNVhkoQarVWAkSAAnQLrr4DF7j.jpg
                        title: We're Not Mere Humans
                        author: Chris Parker
                        content: <div class="wp-block-media-text alignwide">...</div>
                        bible_reading: >-
                          <p><strong><em>These things have I written unto
                          you...</em></strong></p>
                        confession: <p><strong>CONFESSION</strong></p>...
                        studies: <p><strong>FURTHER STUDY:</strong></p>...
                        date: '2025-05-03T00:00:00.000000Z'
                        created_at: '2025-05-03T06:04:22.000000Z'
                        updated_at: '2025-05-03T06:07:05.000000Z'
                        deleted_at: null
                        tags:
                          - prayer
                        is_recurring: false
                        recurrence_end_date: null
                        version: 1
                        original_id: null
                    first_page_url: https://api.thefaithapp.com/v1/devotionals?page=1
                    from: 1
                    last_page: 1
                    last_page_url: https://api.thefaithapp.com/v1/devotionals?page=1
                    links:
                      - url: null
                        label: '&laquo; Previous'
                        active: false
                      - url: https://api.thefaithapp.com/v1/devotionals?page=1
                        label: '1'
                        active: true
                      - url: null
                        label: Next &raquo;
                        active: false
                    next_page_url: null
                    path: https://api.thefaithapp.com/v1/devotionals
                    per_page: 30
                    prev_page_url: null
                    to: 1
                    total: 1
        '401':
          description: Unauthorized - Missing or invalid API key or member bearer token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error_message:
                    type: string
                    example: Unauthorized
        '404':
          description: User or devotional not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: User not found
        '422':
          description: Validation error - Invalid date format or timezone.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid date format. Expected YYYY-MM-DD
components:
  schemas:
    DevotionalResponse:
      type: object
      properties:
        devotional:
          $ref: '#/components/schemas/Devotional'
        metadata:
          type: object
          description: Additional information about the devotional and its context
          properties:
            is_recurring:
              type: boolean
              description: >-
                Indicates whether this devotional is set to recur annually on
                the same date
              example: false
            next_available_date:
              type:
                - string
                - 'null'
              format: date
              description: >-
                For recurring devotionals, shows the next date when this
                devotional will be available (one year from the current date).
                Null for non-recurring devotionals.
              example: '2025-05-03'
            has_past_devotionals:
              type: boolean
              description: >-
                Indicates whether there are any devotionals available for dates
                before the requested date
              example: false
        navigation:
          type: object
          description: Navigation links for moving between dates
          properties:
            previous_date:
              type: string
              format: date
              description: >-
                The date immediately before the requested date, formatted as
                YYYY-MM-DD
              example: '2024-05-02'
            next_date:
              type: string
              format: date
              description: >-
                The date immediately after the requested date, formatted as
                YYYY-MM-DD
              example: '2024-05-04'
    PaginatedDevotionalsResponse:
      type: object
      properties:
        current_page:
          type: integer
          description: Current page number of the result set.
          example: 1
        data:
          type: array
          description: List of devotional objects.
          items:
            $ref: '#/components/schemas/Devotional'
        first_page_url:
          type: string
          format: uri
          description: URL to the first page of results.
          example: https://api.thefaithapp.com/v1/devotionals?page=1
        from:
          type: integer
          description: Index of the first item returned.
          example: 1
        last_page:
          type: integer
          description: Last page number of the result set.
          example: 1
        last_page_url:
          type: string
          format: uri
          description: URL to the last page of results.
          example: https://api.thefaithapp.com/v1/devotionals?page=1
        links:
          type: array
          description: Pagination navigation links.
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
                format: uri
                description: URL for the page link, or null if not available.
                example: null
              label:
                type: string
                description: >-
                  Label for the page link (e.g., 'Next', 'Previous', or page
                  number).
                example: '&laquo; Previous'
              active:
                type: boolean
                description: Whether this page link is active.
                example: false
        next_page_url:
          type:
            - string
            - 'null'
          format: uri
          description: URL to the next page of results, or null if on the last page.
          example: null
        path:
          type: string
          format: uri
          description: Base path for the paginated results.
          example: https://api.thefaithapp.com/v1/devotionals
        per_page:
          type: integer
          description: Number of items per page.
          example: 30
        prev_page_url:
          type:
            - string
            - 'null'
          format: uri
          description: URL to the previous page of results, or null if on the first page.
          example: null
        to:
          type: integer
          description: Index of the last item returned.
          example: 1
        total:
          type: integer
          description: Total number of items available.
          example: 1
    Devotional:
      type: object
      properties:
        id:
          type: integer
          example: 21
        title:
          type: string
          example: Where Does Your Hope Lie?
        author:
          type:
            - string
            - 'null'
          example: Example Church
        content:
          type: string
        bible_reading:
          type:
            - string
            - 'null'
          example: Romans 5:1-5
        confession:
          type:
            - string
            - 'null'
        date:
          type: string
          format: date
        occurrence_date:
          type: string
          format: date
        is_recurring:
          type: boolean
        thumbnail:
          type:
            - string
            - 'null'
          format: uri
        tags:
          type: array
          items:
            type: string
        studies:
          type: array
          items:
            type: object
            additionalProperties: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Client API key copied from Developer Access in the TheFaithApp
        dashboard.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum
      description: Member access token returned by `POST /v1/auth/token`.

````