openapi: 3.0.3

info:
  title: One Stoic Quote API
  version: 1.1.0
  summary: A free JSON API for the daily Stoic quote.
  description: |
    A free, no-authentication JSON API serving a daily Stoic philosophy quote
    from Marcus Aurelius, Epictetus, Seneca, and other philosophers.

    The quote is selected deterministically by day-of-year within a
    `tradition` pool (default `stoic`), so the response is stable for the
    whole UTC day. A given calendar date does not always return the same
    quote over time, since the pool changes as quotes are added, merged, or
    reclassified — treat dated responses as cacheable for about an hour, not
    forever.

    No API key is required and CORS is open (`Access-Control-Allow-Origin: *`),
    so the API can be called directly from a browser or from a server.

    `/api` is accepted as an alias for `/api/quote` and behaves identically.
  contact:
    name: One Stoic Quote
    url: https://www.onestoicquote.com/docs
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-logo:
    url: https://www.onestoicquote.com/favicon.svg
    backgroundColor: '#FFFFFF'
    altText: One Stoic Quote logo — a chess pawn

externalDocs:
  description: Human-readable API documentation
  url: https://www.onestoicquote.com/docs

servers:
  - url: https://www.onestoicquote.com
    description: Production

tags:
  - name: Quotes
    description: Retrieve Stoic quotes.

paths:
  /api/quote:
    get:
      tags:
        - Quotes
      operationId: getQuote
      summary: Get the Stoic quote of the day
      description: |
        Returns a quote from the requested `tradition` pool for the current
        UTC day, or for an explicit calendar date when `date` is supplied.
      parameters:
        - name: date
          in: query
          required: false
          description: >-
            Calendar date in `YYYY-MM-DD` format. When omitted, the current
            UTC date is used.
          schema:
            type: string
            format: date
            pattern: '^\d{4}-\d{2}-\d{2}$'
          example: '2026-01-01'
        - name: tradition
          in: query
          required: false
          description: |
            Restricts selection to a philosophical tradition:
              * `stoic` — the Stoic school itself (Marcus Aurelius, Seneca, Epictetus, and others). This is the default.
              * `adjacent` — Greco-Roman figures who shaped or argued with Stoicism (Socrates, Aristotle, Cicero, and others), but were not Stoics.
              * `other` — voices from outside the Greco-Roman tradition, included for reflection but not Stoic in origin.
              * `all` — draw from the entire collection regardless of tradition.
          schema:
            type: string
            enum: [stoic, adjacent, other, all]
            default: stoic
          example: stoic
      responses:
        '200':
          description: The quote for the requested day and tradition.
          headers:
            Access-Control-Allow-Origin:
              description: Always `*`.
              schema:
                type: string
            Cache-Control:
              description: 's-maxage=3600, stale-while-revalidate'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
              examples:
                seneca:
                  summary: A verified quote by Seneca
                  value:
                    quote: We suffer more often in imagination than in reality.
                    author: Seneca
                    id: q0002
                    authorSlug: seneca
                    tradition: stoic
                    url: https://www.onestoicquote.com/quotes/seneca-we-suffer-more-often-in-imagination-than-in
                    source:
                      status: verified
                      work: Moral Letters to Lucilius
                      reference: Letter 13
                      translator: Richard Mott Gummere
                      translationYear: 1917
                      originalLanguage: Latin
                      sourceUrl: https://en.wikisource.org/wiki/Moral_letters_to_Lucilius/Letter_13
                      note: null
                      actualAuthor: null
                unverified:
                  summary: A quote not yet traced to a specific passage
                  value:
                    quote: The only thing in our power is our own thoughts.
                    author: Marcus Aurelius
                    id: q0001
                    authorSlug: marcus-aurelius
                    tradition: stoic
                    url: https://www.onestoicquote.com/quotes/marcus-aurelius-the-only-thing-in-our-power-is-our
                    source:
                      status: unverified
                      work: null
                      reference: null
                      translator: null
                      translationYear: null
                      originalLanguage: null
                      sourceUrl: null
                      note: null
                      actualAuthor: null
        '400':
          description: The `date` or `tradition` parameter was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                badDateFormat:
                  summary: Malformed date
                  value:
                    error: Invalid date format, expected YYYY-MM-DD
                notADate:
                  summary: Well-formed but not a real date
                  value:
                    error: Invalid date
                badTradition:
                  summary: Unknown tradition value
                  value:
                    error: 'Invalid tradition, expected one of: stoic, adjacent, other, all'
        '404':
          description: No quotes exist for the requested tradition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Quote:
      type: object
      title: Quote
      description: A single quote, its attribution, and its citation status.
      required:
        - quote
        - author
        - id
        - authorSlug
        - tradition
        - url
        - source
      properties:
        quote:
          type: string
          description: The text of the quote.
          example: We suffer more often in imagination than in reality.
        author:
          type: string
          description: The name the quote is attributed to.
          example: Seneca
        id:
          type: string
          description: A stable, opaque identifier for this quote.
          example: q0002
        authorSlug:
          type: string
          description: URL-safe slug for this author, used at /authors/{authorSlug}.
          example: seneca
        tradition:
          type: string
          enum: [stoic, adjacent, other]
          description: >-
            The author's philosophical tradition. Only `stoic` authors are
            ever returned unless `tradition` was set to something else in
            the request.
          example: stoic
        url:
          type: string
          format: uri
          description: Permanent, citable URL for this exact quote.
          example: https://www.onestoicquote.com/quotes/seneca-we-suffer-more-often-in-imagination-than-in
        source:
          $ref: '#/components/schemas/Source'

    Source:
      type: object
      title: Source
      description: >-
        Citation status for this quote. Every quote carries this object, even
        when nothing has been traced yet — check `status` before treating a
        quote as a verified historical citation.
      required:
        - status
      properties:
        status:
          type: string
          enum: [verified, unverified, disputed, misattributed]
          description: |
            * `verified` — traced to a specific passage in a public-domain translation; `work`, `reference`, `translator`, and `sourceUrl` are populated.
            * `unverified` — plausible but not yet traced. The default for most quotes.
            * `disputed` — the attribution is contested; see `note`.
            * `misattributed` — the named author demonstrably did not say this; see `note` and, where known, `actualAuthor`.
        work:
          type: string
          nullable: true
          description: Title of the source work.
          example: Moral Letters to Lucilius
        reference:
          type: string
          nullable: true
          description: Location within the work (e.g. a letter, book, or chapter number).
          example: Letter 13
        translator:
          type: string
          nullable: true
          example: Richard Mott Gummere
        translationYear:
          type: integer
          nullable: true
          example: 1917
        originalLanguage:
          type: string
          nullable: true
          example: Latin
        sourceUrl:
          type: string
          format: uri
          nullable: true
          description: Link to the passage in a public-domain edition.
        note:
          type: string
          nullable: true
          description: Explanation, present when status is disputed or misattributed.
        actualAuthor:
          type: string
          nullable: true
          description: For misattributed quotes, who actually said it, where known.

    Error:
      type: object
      title: Error
      description: Returned when the request could not be processed.
      required:
        - error
      properties:
        error:
          type: string
          description: A human-readable description of what went wrong.
          example: Invalid date format, expected YYYY-MM-DD