openapi: 3.0.3
info:
  title: DreyX Read-Only API
  description: |
    Read-only API for AI agents and integrators to consume DreyX's AI news feed,
    daily Intelligence Brief, tools directory, and topic-filtered RSS.

    No API key required. No rate limits beyond standard CDN protection.
    All endpoints are public and safe to call from agents, plugins, and GPT Actions.

    Full agent integration guide: https://dreyx.com/AGENTS.md
  version: "1.0.0"
  license:
    name: Free for any use with attribution
    url: https://dreyx.com/pricing.md
  contact:
    name: DreyX
    url: https://dreyx.com/

servers:
  - url: https://dreyx.com
    description: Production

paths:
  /digest/today:
    get:
      operationId: getTodaysBrief
      summary: Today's AI Intelligence Brief (auto-redirect)
      description: |
        302 redirect to `/digest/{YYYY-MM-DD}` for the most recent published digest.
        Stable URL — safe to recommend to users from any LLM. Always returns today's
        brief without needing date arithmetic.
      responses:
        "302":
          description: Redirect to the latest digest
          headers:
            Location:
              schema: { type: string, example: "https://dreyx.com/digest/2026-05-05" }

  /api/dailyDigest:
    get:
      operationId: getDigest
      summary: Get a specific daily digest
      parameters:
        - in: query
          name: slug
          schema: { type: string, pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
          description: Digest date in YYYY-MM-DD. Returns the persisted record.
        - in: query
          name: date
          schema: { type: string, pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
          description: |
            Digest date in YYYY-MM-DD. Returns a freshly rebuilt digest computed from
            current feed state. Prefer `slug=` for cite-able stable content.
      responses:
        "200":
          description: Digest payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  digests:
                    type: array
                    items: { $ref: "#/components/schemas/Digest" }

  /api/getLatestFeed:
    get:
      operationId: getLatestFeed
      summary: Get the current public AI news feed
      description: |
        Returns the live curated feed plus the prebuilt feed snapshot. Pending,
        rejected, and deleted arrays require admin auth and are stripped from the
        public response.
      responses:
        "200":
          description: Public feed snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  prebuiltFeed:    { $ref: "#/components/schemas/Feed" }
                  globalFeedData:
                    type: object
                    properties:
                      manualPosts: { type: array, items: { $ref: "#/components/schemas/Article" } }

  /rss:
    get:
      operationId: getRealtimeRss
      summary: Real-time AI news as RSS 2.0
      description: Rebuilds every 2 hours. AI-only, taste-filtered.
      responses:
        "200":
          description: RSS 2.0 XML
          content: { application/rss+xml: { schema: { type: string } } }

  /digest/rss:
    get:
      operationId: getDigestRss
      summary: Daily AI Intelligence Brief as RSS 2.0
      description: One item per day, published at 06:00 UTC.
      responses:
        "200":
          description: RSS 2.0 XML
          content: { application/rss+xml: { schema: { type: string } } }

  /api/topicRss:
    get:
      operationId: getTopicRss
      summary: Topic-filtered RSS feed
      parameters:
        - in: query
          name: topic
          required: true
          schema:
            type: string
            enum: [anthropic, openai, google-ai, coding-agents, safety-and-policy, model-releases]
      responses:
        "200":
          description: RSS 2.0 XML for that topic
          content: { application/rss+xml: { schema: { type: string } } }

  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Full XML sitemap (with Google News extensions)
      responses:
        "200":
          description: Sitemap XML
          content: { application/xml: { schema: { type: string } } }

components:
  schemas:
    Article:
      type: object
      properties:
        url:         { type: string, format: uri }
        title:       { type: string }
        source:      { type: string }
        description: { type: string }
        timestamp:   { type: integer, description: "ms since epoch" }
        publishedAt: { type: integer, description: "ms since epoch" }

    Feed:
      type: object
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/Article" }

    Digest:
      type: object
      properties:
        date:           { type: string, pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
        slug:           { type: string }
        title:          { type: string }
        description:    { type: string }
        articleCount:   { type: integer }
        sourceCount:    { type: integer }
        articles:
          type: array
          items: { $ref: "#/components/schemas/Article" }
        editorial:
          type: object
          properties:
            headline:   { type: string }
            intro:      { type: string }
            bullets:
              type: array
              items: { type: string }
            shouldKnow:
              type: array
              items: { type: string }
