remem-me Collections API

openapi: 3.2.0
info:
  title: Remem Me Collections API
  version: 1.0.0 (v1)
  contact:
    email: info@remem.me
  license:
    name: MIT License
  description: 'Operations tagged collections across 2 of this provider''s published API definitions: remem-me-openapi.json, remem-me-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Collections
  description: Public browsable verse collections (no auth required)
paths:
  /v1/collections/:
    get:
      operationId: collections_list
      description: Browse published verse collections. No authentication required. Unlisted collections are left out.
      parameters:
      - in: query
        name: language
        schema:
          type: string
        description: Filter by language code prefix (e.g. "en", "de", "ja").
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: search
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCollectionListList'
          description: ''
      summary: Collections list
      x-summary-source: derived
  /v1/collections/{id}/:
    get:
      operationId: collections_retrieve
      description: Get a single collection with all verses and subscriber count.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDetail'
          description: ''
      summary: Collections retrieve
      x-summary-source: derived
  /v1/collections/{tag}/metrics/:
    get:
      operationId: collections_metrics_retrieve
      description: 'Get aggregate metrics for a published collection.


        Returns HTTP 204 No Content if the collection has no subscribers.

        Otherwise returns campaign metrics (flat structure).


        Response Format:

        {

        "progress_v1": {

        "percentage": 72.0,

        "words_memorized": 1450,

        "total_words": 2013

        }

        }


        Performance:

        - Early return pattern: checks subscriber count first

        - Caching: 15-minute TTL for metrics calculations (may be up to 15 min stale)

        - Query optimization: ~4 database queries total (optimized with aggregation)


        Notes:

        - subscriber_count removed from response (now in collection detail endpoint)

        - Flat structure - metrics at top level, no wrapper'
      parameters:
      - in: path
        name: tag
        schema:
          type: integer
          maximum: 9223372036854775807
          minimum: -9223372036854775808
          format: int64
          title: Label
        description: A unique value identifying this collection.
        required: true
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
          description: ''
      summary: Collections metrics retrieve
      x-summary-source: derived
  /v1/collections/{var}feed.xml:
    get:
      operationId: collections_feed.xml_list
      description: RSS/Atom feed of collections, optionally filtered by locale.
      parameters:
      - in: path
        name: var
        schema:
          type: string
        required: true
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionFeed'
          description: ''
      summary: Collections feed xml list
      x-summary-source: derived
  /v1/collections/metadata/:
    post:
      operationId: collections_metadata_create
      description: Batch check collection metadata. Accepts up to 100 deck IDs and returns the latest modification timestamp for each published collection.
      tags:
      - Collections
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                deck_ids:
                  type: array
                  items:
                    type: integer
                  description: List of deck IDs (max 100).
              required:
              - deck_ids
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          description: Map of deck_id to metadata (modified timestamp).
        '400':
          description: Invalid deck_ids parameter.
      summary: Collections metadata create
      x-summary-source: derived
  /v1/collections/sitemap.xml:
    get:
      operationId: collections_sitemap.xml_list
      description: XML sitemap of all published collections.
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionUrl'
          description: ''
      summary: Collections sitemap xml list
      x-summary-source: derived
  /v1/share/{id}/:
    get:
      operationId: share_retrieve
      description: Get a shared verse by ID.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
          maximum: 9223372036854775807
          minimum: -9223372036854775808
          format: int64
        description: A unique value identifying this verse.
        required: true
      tags:
      - Collections
      security:
      - cookieAuth: []
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
          description: ''
      summary: Share retrieve
      x-summary-source: derived
components:
  schemas:
    PaginatedCollectionListList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/CollectionList'
    CollectionList:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        label:
          type: string
          readOnly: true
        name:
          type: string
          maxLength: 500
        description:
          type: string
          maxLength: 5000
        website:
          type:
          - string
          - 'null'
          maxLength: 500
        created:
          type: string
          format: date-time
        modified:
          type: integer
          readOnly: true
        size:
          type: integer
          readOnly: true
        downloads:
          type: integer
          readOnly: true
        publisher:
          $ref: '#/components/schemas/Publisher'
        safe_image:
          type: string
          readOnly: true
        listed:
          type: boolean
      required:
      - created
      - description
      - downloads
      - id
      - label
      - modified
      - name
      - publisher
      - safe_image
      - size
    CollectionFeed:
      type: object
      properties:
        link:
          type: string
          readOnly: true
        pubDate:
          type: string
          readOnly: true
        title:
          type: string
          readOnly: true
        description:
          type: string
          maxLength: 5000
        enclosure:
          type: string
          readOnly: true
      required:
      - description
      - enclosure
      - link
      - pubDate
      - title
    Publisher:
      type: object
      properties:
        id:
          type: integer
          maximum: 9223372036854775807
          minimum: -9223372036854775808
          format: int64
        name:
          type: string
          maxLength: 200
        language:
          type: string
          maxLength: 15
        lang_ref:
          type: string
          title: Reference language
          maxLength: 15
        reference_included:
          type: boolean
        topic_preferred:
          type: boolean
        canon:
          allOf:
          - $ref: '#/components/schemas/CanonEnum'
          minimum: -2147483648
          maximum: 2147483647
        font_type:
          allOf:
          - $ref: '#/components/schemas/FontTypeEnum'
          minimum: -2147483648
          maximum: 2147483647
      required:
      - id
      - name
    CollectionUrl:
      type: object
      properties:
        loc:
          type: string
          format: uri
        lastmod:
          type: string
          format: date-time
      required:
      - lastmod
      - loc
    Share:
      type: object
      properties:
        id:
          type: integer
          maximum: 9223372036854775807
          minimum: -9223372036854775808
          format: int64
        reference:
          type: string
          maxLength: 500
        source:
          type:
          - string
          - 'null'
          maxLength: 250
        topic:
          type:
          - string
          - 'null'
          maxLength: 1000
        passage:
          type: string
          maxLength: 100000
        safe_image:
          type: string
          readOnly: true
        publisher:
          allOf:
          - $ref: '#/components/schemas/Publisher'
          readOnly: true
      required:
      - id
      - passage
      - publisher
      - reference
      - safe_image
    CollectionDetail:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        label:
          type: string
          readOnly: true
        name:
          type: string
          maxLength: 500
        description:
          type: string
          maxLength: 5000
        website:
          type:
          - string
          - 'null'
          maxLength: 500
        created:
          type: string
          format: date-time
        modified:
          type: integer
          readOnly: true
        size:
          type: integer
          readOnly: true
        downloads:
          type: integer
          readOnly: true
        subscriber_count:
          type: integer
          readOnly: true
        publisher:
          $ref: '#/components/schemas/Publisher'
        safe_image:
          type: string
          readOnly: true
        listed:
          type: boolean
        verses:
          type: array
          items:
            $ref: '#/components/schemas/CollectionVerse'
          readOnly: true
      required:
      - created
      - description
      - downloads
      - id
      - label
      - modified
      - name
      - publisher
      - safe_image
      - size
      - subscriber_count
      - verses
    MetricsResponse:
      type: object
      description: "Serializer for collection metrics endpoint (flat structure).\n\nResponse Format:\n    {\n      \"progress_v1\": {\n        \"percentage\": 72.0,\n        \"words_memorized\": 1450,\n        \"total_words\": 2013\n      },\n      \"stability_v1\": {\n        \"mastered\": 23,\n        \"in_progress\": 19,\n        \"pending\": 8\n      },\n      \"difficult_verses_v1\": [\n        {\n          \"verse_id\": 274544358678112,\n          \"reference\": \"Romans 8:28\",\n          \"passage_preview\": \"And we know that in all things God works for...\",\n          \"difficulty_score\": 0.82\n        }\n      ],\n      \"activity_v1\": {\n        \"avg_daily_words\": 3250,\n        \"participation_rate\": 0.685,\n        \"period_days\": 7\n      }\n    }\n\nNotes:\n    - Returns HTTP 204 when subscriber_count == 0 (handled in view)\n    - subscriber_count removed (now in collection detail endpoint)\n    - Flat structure - metrics at top level, no wrapper\n    - Metrics are versioned (progress_v1, stability_v1, etc.) for future schema evolution\n    - Uses SerializerMethodField to defer expensive calculations\n    - Each metric field is independently nullable (can be None on error)"
      properties:
        progress_v1:
          type: object
          additionalProperties: {}
          description: "Get progress metric for this collection.\n\nArgs:\n    obj: Deck instance\n\nReturns:\n    Dict with percentage, words_memorized, total_words"
          readOnly: true
        stability_v1:
          type: object
          additionalProperties: {}
          description: "Get stability metric for this collection.\n\nArgs:\n    obj: Deck instance\n\nReturns:\n    Dict with mastered, in_progress, new counts"
          readOnly: true
        difficult_verses_v1:
          type: array
          items: {}
          description: "Get difficult verses metric for this collection.\n\nArgs:\n    obj: Deck instance\n\nReturns:\n    List of dicts with verse_id, reference, passage_preview, difficulty_score"
          readOnly: true
        activity_v1:
          type: object
          additionalProperties: {}
          description: "Get activity metric for this collection.\n\nArgs:\n    obj: Deck instance\n\nReturns:\n    Dict with avg_daily_words, participation_rate, period_days"
          readOnly: true
      required:
      - activity_v1
      - difficult_verses_v1
      - progress_v1
      - stability_v1
    CanonEnum:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      type: integer
      description: '* `0` - Protestant

        * `1` - Lutheran

        * `2` - Roman

        * `3` - Eastern

        * `4` - Oriental

        * `5` - Jewish'
    FontTypeEnum:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: '* `0` - Sans

        * `1` - Serif

        * `2` - Mono'
    CollectionVerse:
      type: object
      properties:
        id:
          type: integer
          maximum: 9223372036854775807
          minimum: -9223372036854775808
          format: int64
        modified:
          type: integer
          readOnly: true
        reference:
          type: string
          maxLength: 500
        source:
          type:
          - string
          - 'null'
          maxLength: 250
        topic:
          type:
          - string
          - 'null'
          maxLength: 1000
        passage:
          type: string
          maxLength: 100000
        safe_image:
          type: string
          readOnly: true
      required:
      - id
      - modified
      - passage
      - reference
      - safe_image
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- remem-me-openapi.json
- remem-me-openapi.yml