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

# Tag breakdown

> Returns tags with article counts, sorted by count descending.



## OpenAPI

````yaml get /v1/reading/tags
openapi: 3.1.0
info:
  title: Rewind API
  version: 1.0.0
  description: >-
    Personal data aggregation API. Syncs and serves data from Last.fm, Apple
    Music, Strava, Plex, Letterboxd, Discogs, Trakt, Instapaper, Google
    Calendar, and Gmail.


    ## Domains


    | Domain | Source | Description |

    |--------|--------|-------------|

    | **Listening** | Last.fm, Apple Music | Scrobbles, top
    artists/albums/tracks, streaks, stats |

    | **Running** | Strava | Activities, splits, gear, personal records, year
    summaries |

    | **Watching** | Plex, Letterboxd | Movies, TV shows, watch history,
    ratings, reviews |

    | **Collecting** | Discogs, Trakt | Vinyl/CD collection, physical media,
    wantlist |

    | **Reading** | Instapaper | Articles, highlights, reading progress, word
    count |

    | **Attending** | Google Calendar, Gmail | Live events, tickets, sports
    games, concerts, venues |


    ## Authentication


    All endpoints require a Bearer token. There are two key types:


    - **Read keys** (`rw_live_...`) — access all GET endpoints

    - **Admin keys** (`rw_admin_...`) — access all endpoints including sync
    triggers and data management


    Pass your key in the Authorization header: `Authorization: Bearer
    rw_live_...`


    ## Pagination


    List endpoints return paginated responses:


    ```json

    {
      "data": [...],
      "pagination": { "page": 1, "limit": 20, "total": 150, "total_pages": 8 }
    }

    ```


    The activity feed uses cursor-based pagination instead.


    ## Quick Start


    ```bash

    # Check the API is up

    curl https://api.rewind.rest/v1/health


    # Fetch recent scrobbles (requires read key)

    curl -H "Authorization: Bearer rw_live_..." \
      https://api.rewind.rest/v1/listening/recent

    # Fetch running stats

    curl -H "Authorization: Bearer rw_live_..." \
      https://api.rewind.rest/v1/running/stats
    ```


    ## Errors


    All errors follow the same envelope:


    ```json

    { "error": "Not found", "status": 404 }

    ```


    Common status codes: 400 (bad request), 401 (unauthorized), 404 (not found),
    500 (server error).
  contact:
    url: https://github.com/pdugan20/rewind
servers:
  - url: https://api.rewind.rest
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Listening
    description: Last.fm scrobbles, top charts, streaks, and stats.
  - name: Running
    description: Strava activities, splits, gear, records, and year summaries.
  - name: Watching
    description: >-
      Movies, TV shows, watch history, ratings, and reviews from Plex and
      Letterboxd.
  - name: Collecting
    description: Vinyl/CD collection from Discogs and physical media from Trakt.
  - name: Reading
    description: Articles, highlights, and reading stats from Instapaper.
  - name: Attending
    description: >-
      Live events you bought tickets for — sports games, concerts, theater.
      Sourced from Google Calendar and ticket-vendor email.
  - name: Feed
    description: Cross-domain activity feed with cursor-based pagination.
  - name: Search
    description: Full-text search across all domains.
  - name: Images
    description: Image proxy with on-the-fly transforms via Cloudflare Images.
  - name: System
    description: Health checks and sync status.
  - name: Admin
    description: >-
      API key management, sync triggers, and data administration. Requires admin
      key.
  - name: Webhooks
    description: Inbound webhook receivers for Strava and Plex. No auth required.
paths:
  /v1/reading/tags:
    get:
      tags:
        - Reading
      summary: Tag breakdown
      description: Returns tags with article counts, sorted by count descending.
      operationId: listReadingTags
      responses:
        '200':
          description: Tag list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        tag:
                          type: string
                        count:
                          type: number
                      required:
                        - tag
                        - count
                required:
                  - data
              example:
                data:
                  - tag: technology
                    count: 312
                  - tag: culture
                    count: 187
                  - tag: science
                    count: 145
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Not found
        status:
          type: integer
          example: 404
      required:
        - error
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key. Read keys (rw_live_...) access GET endpoints. Admin keys
        (rw_admin_...) access all endpoints.

````