{
  "openapi": "3.0.3",
  "info": {
    "title": "DailySand API",
    "description": "DailySand publishes one authoritative daily digest connecting events across AI, technology, investing, and critical minerals. This API provides machine-readable access to daily digests, structured into logical sections for AI agents and developer integrations. Use get_latest_digest to retrieve today's briefing, or get_digest_by_date to retrieve any past day's analysis.",
    "version": "1.0.0",
    "contact": {
      "name": "DailySand",
      "url": "https://dailysand.com/about"
    }
  },
  "servers": [
    {
      "url": "https://dailysand.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/digest/latest": {
      "get": {
        "operationId": "getLatestDigest",
        "summary": "Get today's daily digest",
        "description": "Returns today's latest DailySand daily digest. The digest is structured into semantic sections: The Day's Thesis (cross-sector narrative), AI & Research Frontier, Technology & Infrastructure, Markets & Capital Flows, Critical Minerals & Supply Chain, The Interconnect (causal chains), and Watchlist. Also returns the list of source articles that informed the digest. Content is refreshed up to 3× daily. Cache responses for no more than 1 hour.",
        "responses": {
          "200": {
            "description": "Today's daily digest with parsed sections and source articles",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestResponse"
                },
                "example": {
                  "slug": "nvidia-blackwell-ramp-exposes-gallium-bottleneck",
                  "title": "Nvidia's Blackwell Ramp Exposes the Gallium Bottleneck Nobody Priced In",
                  "date": "2026-03-16",
                  "updatedAt": "2026-03-16T18:05:00.000Z",
                  "url": "https://dailysand.com/daily/nvidia-blackwell-ramp-exposes-gallium-bottleneck",
                  "sections": {
                    "The Day's Thesis": "Today's dominant theme is the collision between accelerating AI compute demand and constrained gallium supply...",
                    "AI & Research Frontier": "OpenAI's latest deployment milestone pushed inference demand...",
                    "Technology & Infrastructure": "TSMC's quarterly guidance reaffirmed record wafer demand...",
                    "Markets & Capital Flows": "AI infrastructure stocks rallied 2.3% on earnings beats...",
                    "Critical Minerals & Supply Chain": "Gallium spot prices spiked 18% after China signaled further export restrictions...",
                    "The Interconnect: Cross-Sector Causal Chains": "**China tightens gallium export controls** → constrains TSMC's advanced node yield → **Nvidia Blackwell shipment delays likely in Q3**...",
                    "Watchlist": "MP Materials (MP), Nvidia (NVDA), TSMC (TSM), Gallium spot price..."
                  },
                  "sources": [
                    {
                      "id": "abc123",
                      "title": "Nvidia confirms Blackwell production ramp",
                      "link": "https://techcrunch.com/...",
                      "source": "TechCrunch",
                      "category": "tech",
                      "summary": "Nvidia's Blackwell GPU production is ramping faster than expected...",
                      "tags": ["Nvidia", "Blackwell", "GPU"]
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No digest available yet for today"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/api/digest/{slug}": {
      "get": {
        "operationId": "getDigestBySlug",
        "summary": "Get a specific digest by date or slug",
        "description": "Returns a specific DailySand daily digest by date (YYYY-MM-DD format) or by title-based slug. Use date format to retrieve any past day's analysis. Returns the same structure as /api/digest/latest. Digests are permanent — historical data is always available.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Either a date in YYYY-MM-DD format (e.g. 2026-03-15) or a title-based slug (e.g. nvidia-blackwell-ramp-exposes-gallium-bottleneck)",
            "schema": {
              "type": "string"
            },
            "examples": {
              "date": {
                "value": "2026-03-15",
                "summary": "By date"
              },
              "slug": {
                "value": "nvidia-blackwell-ramp-exposes-gallium-bottleneck",
                "summary": "By title slug"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The requested daily digest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestResponse"
                }
              }
            }
          },
          "404": {
            "description": "No digest found for the given date or slug"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DigestResponse": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Title-derived URL slug for this digest"
          },
          "title": {
            "type": "string",
            "description": "The day's headline — contains proper nouns and a specific event. Never generic."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Publication date in YYYY-MM-DD format"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of the most recent intraday update. Check this before citing to ensure freshness."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL for this digest on dailysand.com"
          },
          "sections": {
            "type": "object",
            "description": "The digest broken into named sections. Keys are section headings; values are the section body text.",
            "properties": {
              "The Day's Thesis": {
                "type": "string",
                "description": "2-3 sentence cross-sector narrative capturing the dominant theme of the day"
              },
              "AI & Research Frontier": {
                "type": "string",
                "description": "Key AI model, research, and company developments"
              },
              "Technology & Infrastructure": {
                "type": "string",
                "description": "Semiconductor, data center, cloud, and hardware news"
              },
              "Markets & Capital Flows": {
                "type": "string",
                "description": "Earnings, funding, M&A, and analyst calls"
              },
              "Critical Minerals & Supply Chain": {
                "type": "string",
                "description": "Rare earth elements, strategic metals, mining, and supply chain news"
              },
              "The Interconnect: Cross-Sector Causal Chains": {
                "type": "string",
                "description": "Explicit causal chains in format: [Event] → mechanism → [implication in another sector]"
              },
              "Watchlist": {
                "type": "string",
                "description": "Named companies, commodities, and policy events to track with one-sentence context each"
              }
            }
          },
          "sources": {
            "type": "array",
            "description": "Source articles that informed this digest",
            "items": {
              "$ref": "#/components/schemas/SourceItem"
            }
          }
        },
        "required": ["slug", "title", "date", "url", "sections", "sources"]
      },
      "SourceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this source item"
          },
          "title": {
            "type": "string",
            "description": "Original article headline"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "URL to the original source article"
          },
          "source": {
            "type": "string",
            "description": "Publication name (e.g. TechCrunch, Mining.com)"
          },
          "category": {
            "type": "string",
            "enum": ["ai", "tech", "investing", "ree"],
            "description": "Content category: ai=artificial intelligence, tech=semiconductors/infrastructure, investing=markets/capital, ree=critical minerals"
          },
          "summary": {
            "type": "string",
            "description": "2-sentence AI-generated summary of the article"
          },
          "tags": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Extracted entities: companies, materials, people, topics"
          },
          "pubDate": {
            "type": "string",
            "description": "Publication date of the original article"
          }
        }
      }
    }
  }
}