{"openapi":"3.1.0","info":{"title":"The Techno Optimist API","version":"1.0.0","description":"Public data API over the frontier knowledge base: frontiers → fields → programs → updates, with companies as context; plus glossary primers. Realtime at `/v1/stream`.\n\n**MCP server for AI assistants:** a free, public, read-only [Model Context Protocol](https://modelcontextprotocol.io) server at `https://api.technooptimist.io/mcp` (Streamable HTTP, no key). Tools: `search`, `get_program`, `get_frontier`, `latest_updates`, `get_company`. Add it as a custom connector in Claude or ChatGPT, or in Cursor's `mcp.json` as `{ \"technooptimist\": { \"url\": \"https://api.technooptimist.io/mcp\" } }`."},"servers":[{"url":"http://api.technooptimist.io"}],"tags":[{"name":"Frontiers","description":"Frontier → field → program → update. A frontier (Energy) holds fields (Geothermal)."},{"name":"Programs","description":"A program is the thing being built (Figure 03, Starship); its company is who runs it."},{"name":"Companies"},{"name":"Feed"},{"name":"Search"},{"name":"Realtime"},{"name":"Me","description":"Dev placeholder auth via `x-user-email`."},{"name":"Admin","description":"Write surface for routines."},{"name":"Meta"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (`to_live_…`) for reads; ADMIN_TOKEN or a key with the `write` scope for /v1/admin."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"FrontierTile":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"description":{"type":"string"},"sortOrder":{"type":"integer"},"companyCount":{"type":"integer"},"programCount":{"type":"integer"},"latest":{"type":["object","null"],"properties":{"headline":{"type":"string"},"company":{"type":"string"},"program":{"type":["string","null"]},"occurredAt":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["headline","company","program","occurredAt"]}},"required":["slug","name","description","sortOrder","companyCount","programCount","latest"]},"FrontierList":{"type":"object","properties":{"frontiers":{"type":"array","items":{"$ref":"#/components/schemas/FrontierTile"}}},"required":["frontiers"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"Field":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"blurb":{"type":["string","null"],"description":"One ELI5 line: what this field is."},"explainer":{"type":"array","items":{"type":"string"},"description":"\"How <field> works\": short ELI5 bullets (may be empty)."},"sortOrder":{"type":"integer"},"companyCount":{"type":"integer"},"programCount":{"type":"integer"}},"required":["slug","name","blurb","explainer","sortOrder","companyCount","programCount"]},"CompanyRow":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"keywords":{"type":"string"},"hq":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"valuationUsd":{"type":["number","null"]},"valuationKind":{"type":"string"},"employees":{"type":["number","null"]},"foundedYear":{"type":["number","null"]},"score":{"type":["number","null"]},"logoUrl":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}},"isPrimary":{"type":"boolean"},"programs":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"imageUrl":{"type":["string","null"]},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","stage","imageUrl","path"]}},"lastUpdateAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["slug","name","keywords","hq","status","valuationUsd","valuationKind","employees","foundedYear","score","logoUrl","fields","isPrimary","programs","lastUpdateAt"]},"LooseDate":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]}},"required":["date","precision"]},"ProgramRow":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"keywords":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"imageUrl":{"type":["string","null"]},"isFlagship":{"type":"boolean"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"},"field":{"type":["string","null"],"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"The program's own field, else its company's field in this frontier.","example":"helion"},"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"hq":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":["string","null"]}},"required":["slug","name","hq","logoUrl"]},"next":{"type":["object","null"],"properties":{"title":{"type":"string"},"status":{"type":"string","enum":["done","current","planned","missed"]},"date":{"$ref":"#/components/schemas/LooseDate"},"slipMonths":{"type":["number","null"]}},"required":["title","status","date","slipMonths"]},"lastUpdateAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"},"importance":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"Importance meter 1-5: how far the program pushes technology forward if it succeeds (null = not rated yet). Rows come most important first."},"breakdown":{"type":["object","null"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"dims":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"integer","minimum":0,"maximum":5},"weight":{"type":"number"}},"required":["key","value","weight"]}},"reason":{"type":["string","null"]},"pinned":{"type":"boolean"}},"required":["score","dims","reason","pinned"],"description":"Importance 0-100 with the five 0-5 ratings it is computed from (leap, reach, economy, lead, people; weight 0-1) and the one-line reason; pinned = set by the editors. null = not rated yet."}},"required":["slug","name","keywords","stage","imageUrl","isFlagship","path","field","company","next","lastUpdateAt","importance","breakdown"]},"FrontierPage":{"type":"object","properties":{"frontier":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"description":{"type":"string"},"explainer":{"type":"array","items":{"type":"string"},"description":"\"How <frontier> works\": short ELI5 bullets (may be empty)."}},"required":["slug","name","description","explainer"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"},"description":"The frontier's fields, in editorial order."},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyRow"}},"programs":{"type":"array","items":{"$ref":"#/components/schemas/ProgramRow"},"description":"Programs in this frontier, including ones cross-listed from companies based elsewhere."},"stats":{"type":"object","properties":{"companies":{"type":"integer"},"programs":{"type":"integer"},"updatesThisWeek":{"type":"integer"}},"required":["companies","programs","updatesThisWeek"]}},"required":["frontier","fields","companies","programs","stats"]},"FeedItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"occurredAt":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"headline":{"type":"string"},"kind":{"type":"string","enum":["test","hardware","software","manufacturing","regulatory","funding","hiring","commercial","research","partnership","people","other"]},"importance":{"type":"string","enum":["major","minor"]},"rank":{"type":"integer"},"sourceType":{"type":"string","enum":["x","blog","filing","press","livestream","paper","job","regulator","interview","other"]},"sourceUrl":{"type":["string","null"],"format":"uri","description":"Link to the original story (article, press release, filing, video). Null when unknown."},"summary":{"type":["string","null"],"description":"The story in our words: 2–4 sentences on what happened and why it matters, written from the source. Null when not written yet."},"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"program":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","frontier","path"]},"frontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}},"createdAt":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["id","occurredAt","precision","headline","kind","importance","rank","sourceType","sourceUrl","summary","company","program","frontiers","createdAt"]},"ProgramEvent":{"type":"object","properties":{"title":{"type":"string"},"date":{"allOf":[{"$ref":"#/components/schemas/LooseDate"},{"type":"object"}]},"source":{"type":"string","enum":["catalyst","milestone","update"]},"status":{"type":["string","null"],"enum":["done","current","planned","missed"],"description":"Milestones only."},"originalTarget":{"allOf":[{"$ref":"#/components/schemas/LooseDate"},{"description":"Milestones only: the original target when the date slipped."}]},"slipMonths":{"type":["integer","null"]},"kind":{"type":["string","null"],"description":"Catalyst kind or update kind."},"update":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"headline":{"type":"string"},"sourceType":{"type":"string","enum":["x","blog","filing","press","livestream","paper","job","regulator","interview","other"]},"sourceUrl":{"type":["string","null"]}},"required":["id","headline","sourceType","sourceUrl"],"description":"The story behind the event (updates, and milestones matched to the update that reported them)."}},"required":["title","date","source","status","originalTarget","slipMonths","kind","update"]},"ProgramPage":{"type":"object","properties":{"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"hq":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":["string","null"]},"keywords":{"type":"string"},"description":{"type":"string"},"brief":{"type":"array","items":{"type":"string"}},"foundedYear":{"type":["number","null"]},"status":{"type":"string"},"parent":{"type":["string","null"]},"employees":{"type":["number","null"]},"valuationUsd":{"type":["number","null"]},"valuationKind":{"type":"string","enum":["market_cap","private_valuation","deal_value","none"]},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["name","role","url"]}},"checkedAt":{"type":["string","null"],"format":"date-time","description":"When we last verified these facts (null = never stamped).","example":"2025-07-30T12:00:00.000Z"}},"required":["slug","name","hq","logoUrl","keywords","description","brief","foundedYear","status","parent","employees","valuationUsd","valuationKind","people","checkedAt"]},"program":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"keywords":{"type":"string"},"description":{"type":"string"},"goal":{"type":["string","null"],"description":"What the program is trying to achieve and why it matters."},"statusLine":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"isFlagship":{"type":"boolean"},"previousGeneration":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"frontier":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"field":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"lastUpdateAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"},"checkedAt":{"type":["string","null"],"format":"date-time","description":"When we last verified these facts (null = never stamped).","example":"2025-07-30T12:00:00.000Z"}},"required":["slug","name","keywords","description","goal","statusLine","stage","isFlagship","previousGeneration","imageUrl","frontier","field","lastUpdateAt","path","checkedAt"]},"milestones":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string","enum":["done","current","planned","missed"]},"date":{"$ref":"#/components/schemas/LooseDate"},"originalTarget":{"$ref":"#/components/schemas/LooseDate"},"note":{"type":["string","null"]}},"required":["title","status","date","originalTarget","note"]}},"specs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"numeric":{"type":["number","null"]},"unit":{"type":["string","null"]},"previous":{"type":["string","null"]},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["key","label","value","numeric","unit","previous","provenance"]}},"howItWorks":{"type":"array","items":{"type":"object","properties":{"label":{"type":["string","null"]},"title":{"type":"string"},"body":{"type":"string"}},"required":["label","title","body"]}},"obstacles":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"status":{"type":["string","null"],"enum":["open","active_research","partially_solved","solved"]}},"required":["title","body","status"]},"description":"The program's own current obstacles."},"limits":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"}},"required":["title","body"]},"description":"Fundamental physics/technology limits of this kind of technology: why it can't simply be made better."},"important":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"recentOnly":{"type":"boolean","description":"True when every item is from the last 3 months; false when older items were added to reach at least 5."}},"required":["items","recentOnly"],"description":"Most important updates: the top-ranked of the last 3 months, topped up with the most important older ones to at least 5."},"events":{"type":"object","properties":{"upcoming":{"type":"array","items":{"$ref":"#/components/schemas/ProgramEvent"},"description":"Catalysts and planned/current milestones with a date, soonest first."},"past":{"type":"array","items":{"$ref":"#/components/schemas/ProgramEvent"},"description":"Done/missed milestones and major updates, newest first. A milestone and the update reporting it appear once."}},"required":["upcoming","past"],"description":"Important events (at most 20 per list)."},"catalysts":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"kind":{"type":["string","null"]}},"required":["title","date","precision","kind"]}},"research":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"kind":{"type":"string","enum":["paper","blog","demo","talk","dataset","code"]},"title":{"type":"string"},"why":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["date","precision","kind","title","why","url"]}},"siblings":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","stage","frontier","path"]}},"peers":{"type":"array","items":{"type":"object","properties":{"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"},"specs":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["value","provenance"]}}},"required":["company","slug","name","stage","path","specs"]}}},"required":["company","program","milestones","specs","howItWorks","obstacles","limits","important","events","catalysts","research","siblings","peers"]},"CompanyPage":{"type":"object","properties":{"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"keywords":{"type":"string"},"description":{"type":"string"},"website":{"type":["string","null"]},"hq":{"type":"array","items":{"type":"string"}},"foundedYear":{"type":["number","null"]},"status":{"type":"string"},"parent":{"type":["string","null"]},"ticker":{"type":["string","null"]},"exchange":{"type":["string","null"]},"employees":{"type":["number","null"]},"employeesAsOf":{"type":["string","null"],"format":"date","example":"2025-07-01"},"valuationUsd":{"type":["number","null"]},"valuationKind":{"type":"string","enum":["market_cap","private_valuation","deal_value","none"]},"valuationAsOf":{"type":["string","null"],"format":"date","example":"2025-07-01"},"valuationProvenance":{"type":["string","null"],"enum":["reported","estimated","sample"]},"score":{"type":["number","null"]},"logoUrl":{"type":["string","null"]},"brief":{"type":"array","items":{"type":"string"}},"lastUpdateAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"},"checkedAt":{"type":["string","null"],"format":"date-time","description":"When we last verified these facts (null = never stamped).","example":"2025-07-30T12:00:00.000Z"}},"required":["slug","name","keywords","description","website","hq","foundedYear","status","parent","ticker","exchange","employees","employeesAsOf","valuationUsd","valuationKind","valuationAsOf","valuationProvenance","score","logoUrl","brief","lastUpdateAt","checkedAt"]},"frontiers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"field":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"isPrimary":{"type":"boolean"}},"required":["slug","name","field","isPrimary"]}},"programs":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"keywords":{"type":"string"},"description":{"type":"string"},"statusLine":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"isFlagship":{"type":"boolean"},"imageUrl":{"type":["string","null"]},"frontier":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"},"milestones":{"type":"object","properties":{"done":{"type":"integer"},"total":{"type":"integer"}},"required":["done","total"]},"next":{"type":["object","null"],"properties":{"title":{"type":"string"},"status":{"type":"string","enum":["done","current","planned","missed"]},"date":{"$ref":"#/components/schemas/LooseDate"},"slipMonths":{"type":["number","null"]}},"required":["title","status","date","slipMonths"]},"lastUpdateAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["slug","name","keywords","description","statusLine","stage","isFlagship","imageUrl","frontier","path","milestones","next","lastUpdateAt"]}},"approach":{"type":"array","items":{"type":"object","properties":{"label":{"type":["string","null"]},"title":{"type":"string"},"body":{"type":"string"}},"required":["label","title","body"]}},"problems":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"status":{"type":["string","null"],"enum":["open","active_research","partially_solved","solved"]}},"required":["title","body","status"]}},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["name","role","url"]}},"funding":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"round":{"type":"string"},"amountUsd":{"type":["number","null"]},"postMoneyUsd":{"type":["number","null"]},"leads":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["date","precision","round","amountUsd","postMoneyUsd","leads","provenance"]}},"relationships":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["customer","investor","supplier","partner","acquirer"]},"note":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"companySlug":{"type":["string","null"],"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}},"required":["name","kind","note","url","companySlug"]}},"research":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"kind":{"type":"string","enum":["paper","blog","demo","talk","dataset","code"]},"title":{"type":"string"},"why":{"type":"string"},"url":{"type":["string","null"],"format":"uri"},"program":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","frontier","path"]}},"required":["date","precision","kind","title","why","url","program"]}},"catalysts":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"date":{"type":"string","format":"date","example":"2025-07-01"},"precision":{"type":"string","enum":["day","month","quarter","year"]},"kind":{"type":["string","null"]},"program":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","frontier","path"]}},"required":["title","date","precision","kind","program"]}},"instruments":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"kind":{"type":"string","enum":["stock","preipo_perp"]},"price":{"type":["number","null"]},"changePct":{"type":["number","null"]}},"required":["symbol","kind","price","changePct"]}},"peers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"hq":{"type":"array","items":{"type":"string"}},"valuationUsd":{"type":["number","null"]},"valuationKind":{"type":"string"},"flagship":{"type":["object","null"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]}},"required":["slug","name","stage"]}},"required":["slug","name","hq","valuationUsd","valuationKind","flagship"]}}},"required":["company","frontiers","programs","approach","problems","people","funding","relationships","research","catalysts","instruments","peers"]},"GlossaryIndex":{"type":"object","properties":{"terms":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"term":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"frontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}}},"required":["slug","term","aliases","frontiers"]}}},"required":["terms"]},"GlossaryTerm":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"term":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"short":{"type":"string"},"points":{"type":"array","items":{"type":"string"},"description":"2–5 short ELI5 bullets: what it is, how it works, why it matters."},"frontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}},"illustrationSvg":{"type":["string","null"],"description":"Ink illustration as SVG markup (off-white line art), or null until drawn."},"related":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"term":{"type":"string"}},"required":["slug","term"]}},"seeAlso":{"type":"array","items":{"type":"object","properties":{"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"}},"required":["slug","name"]},"program":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"path":{"type":"string","description":"Canonical site path. Programs live under their frontier.","example":"/robotics/figure-03"}},"required":["slug","name","frontier","path"]}},"required":["company","program"]}}},"required":["slug","term","aliases","short","points","frontiers","illustrationSvg","related","seeAlso"]},"Feed":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"window":{"type":"string","enum":["day","week","month","quarter","all"]},"fellBack":{"type":"boolean"},"total":{"type":"integer","description":"Total matches for the filter (ignoring the cursor window)."},"nextCursor":{"type":["string","null"],"description":"Pass as `before` to get the next page. Null when there are no more pages (or sort=top)."}},"required":["items","window","fellBack","total","nextCursor"]},"Story":{"allOf":[{"$ref":"#/components/schemas/FeedItem"},{"type":"object","properties":{"points":{"type":"array","items":{"type":"string"},"description":"2–5 bullets of the key facts (numbers, dates, who, what changes), from the source. Empty when not written yet."}},"required":["points"]}]},"SearchResults":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["frontier","company","program"]},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"name":{"type":"string"},"subtitle":{"type":"string"},"path":{"type":"string","description":"Canonical site path","example":"/energy/polaris"}},"required":["type","slug","name","subtitle","path"]}}},"required":["hits"]},"SearchIndex":{"type":"object","properties":{"frontiers":{"type":"array","items":{"type":"object","properties":{"n":{"type":"string","description":"name"},"s":{"type":"string","description":"subtitle"},"u":{"type":"string","description":"site path"},"a":{"type":"string","description":"aliases (ticker, alternative spelling)"},"k":{"type":"string","description":"keywords, field, frontier, company"},"d":{"type":"string","description":"compact description words"},"r":{"type":"integer","description":"number of stories (tie-break)"}},"required":["n","s","u"]}},"fields":{"type":"array","items":{"type":"object","properties":{"n":{"type":"string","description":"name"},"s":{"type":"string","description":"subtitle"},"u":{"type":"string","description":"site path"},"a":{"type":"string","description":"aliases (ticker, alternative spelling)"},"k":{"type":"string","description":"keywords, field, frontier, company"},"d":{"type":"string","description":"compact description words"},"r":{"type":"integer","description":"number of stories (tie-break)"}},"required":["n","s","u"]},"description":"fields; u = the frontier page filtered to the field"},"companies":{"type":"array","items":{"type":"object","properties":{"n":{"type":"string","description":"name"},"s":{"type":"string","description":"subtitle"},"u":{"type":"string","description":"site path"},"a":{"type":"string","description":"aliases (ticker, alternative spelling)"},"k":{"type":"string","description":"keywords, field, frontier, company"},"d":{"type":"string","description":"compact description words"},"r":{"type":"integer","description":"number of stories (tie-break)"}},"required":["n","s","u"]}},"programs":{"type":"array","items":{"type":"object","properties":{"n":{"type":"string","description":"name"},"s":{"type":"string","description":"subtitle"},"u":{"type":"string","description":"site path"},"a":{"type":"string","description":"aliases (ticker, alternative spelling)"},"k":{"type":"string","description":"keywords, field, frontier, company"},"d":{"type":"string","description":"compact description words"},"r":{"type":"integer","description":"number of stories (tie-break)"}},"required":["n","s","u"]}}},"required":["frontiers","fields","companies","programs"]},"Ticker":{"type":"object","properties":{"news":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"frontier":{"type":["string","null"]},"company":{"type":"string"},"companySlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"program":{"type":["string","null"]},"headline":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["id","frontier","company","companySlug","program","headline","occurredAt"]},"description":"Our own stories for the tape: recent, weighted to rank, rotated hourly."},"markets":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"coin":{"type":"string","description":"Hyperliquid coin (\"xyz:NVDA\", \"HYPE\")"},"dex":{"type":"string"},"kind":{"type":"string","enum":["stock","preipo","token"]},"company":{"type":"string"},"companySlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"price":{"type":["number","null"]},"impliedValuationUsd":{"type":["number","null"]},"changePct":{"type":"number","description":"Day change, percent"},"asOf":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"}},"required":["symbol","coin","dex","kind","company","companySlug","price","impliedValuationUsd","changePct","asOf"]},"description":"Live Hyperliquid moves: the scope company’s own instruments, then major moves of the day (|change| >= 3%, tokens 5%)."}},"required":["news","markets"]},"SiteStats":{"type":"object","properties":{"companies":{"type":"integer"},"programs":{"type":"integer"},"frontiers":{"type":"integer"},"updates24h":{"type":"integer"},"updates7d":{"type":"integer"},"updatesTotal":{"type":"integer"}},"required":["companies","programs","frontiers","updates24h","updates7d","updatesTotal"]},"Health":{"type":"object","properties":{"ok":{"type":"boolean"},"version":{"type":"string"},"uptimeSec":{"type":"number"},"db":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]}},"required":["ok","latencyMs"]},"realtime":{"type":"object","properties":{"listening":{"type":"boolean"},"clients":{"type":"integer"}},"required":["listening","clients"]},"deployment":{"type":["string","null"]}},"required":["ok","version","uptimeSec","db","realtime","deployment"]},"CreateUpdateResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created":{"type":"boolean","description":"false when an update with the same externalKey already existed (idempotent replay)."},"update":{"allOf":[{"$ref":"#/components/schemas/Story"},{"allOf":[{"$ref":"#/components/schemas/FeedItem"},{"type":["object","null"],"properties":{"points":{"type":"array","items":{"type":"string"},"description":"2–5 bullets of the key facts (numbers, dates, who, what changes), from the source. Empty when not written yet."}},"required":["points"]}]}]}},"required":["id","created","update"]},"ProgramWriteResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"program":{"$ref":"#/components/schemas/ProgramPage"}},"required":["ok","program"]},"CompanyWriteResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"company":{"$ref":"#/components/schemas/CompanyPage"}},"required":["ok","company"]},"FrontierWriteResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"fields":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}}},"required":["ok","slug","fields"]},"MediaWriteResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"logos":{"type":"integer"},"images":{"type":"integer"},"missing":{"type":"array","items":{"type":"string"}}},"required":["ok","logos","images","missing"]},"GlossaryWriteResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"slugs":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"}}},"required":["ok","slugs"]},"Ok":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]},"CreateApiKeyResult":{"type":"object","properties":{"key":{"type":"string","description":"The raw key. Shown ONCE; only its hash is stored."},"prefix":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["free","pro","enterprise","internal"]},"scopes":{"type":"array","items":{"type":"string"}}},"required":["key","prefix","name","tier","scopes"]},"CreateApiKeyInput":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80,"example":"news-routine"},"tier":{"type":"string","enum":["free","pro","enterprise","internal"],"default":"free"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","admin"]},"minItems":1,"default":["read"]}},"required":["name"]},"OpsEventInput":{"type":"object","properties":{"level":{"type":"string","enum":["debug","info","warn","error","fatal"]},"message":{"type":"string","minLength":1,"maxLength":2000},"data":{"type":"object","additionalProperties":{}},"path":{"type":"string","maxLength":500}},"required":["level","message"]},"Incident":{"type":"object","additionalProperties":{}},"InboundEmail":{"type":"object","properties":{"from":{"type":"string","maxLength":320},"to":{"type":"string","maxLength":320},"subject":{"type":"string","maxLength":500,"default":""},"text":{"type":"string","maxLength":50000,"default":""},"messageId":{"type":"string","maxLength":500}},"required":["from","to"]},"InboundEmailRow":{"type":"object","additionalProperties":{}},"FollowResult":{"type":"object","properties":{"following":{"type":"boolean"},"targetType":{"type":"string","enum":["frontier","company","program"]},"target":{"type":"string"}},"required":["following","targetType","target"]},"FollowInput":{"type":"object","properties":{"targetType":{"type":"string","enum":["frontier","company","program"]},"target":{"type":"string","pattern":"^[a-z0-9-]+(\\/[a-z0-9-]+)?$","description":"Frontier or company slug, or `company/program` for programs.","example":"helion/polaris"}},"required":["targetType","target"]},"Notifications":{"type":"object","properties":{"topic":{"type":"string","description":"Stream topic for this user's live notifications","example":"user:6f1c…"},"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"readAt":{"type":["string","null"],"format":"date-time","example":"2025-07-30T12:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","example":"2025-07-30T12:00:00.000Z"},"update":{"allOf":[{"$ref":"#/components/schemas/FeedItem"},{"type":["object","null"]}]}},"required":["id","title","readAt","createdAt","update"]}}},"required":["topic","notifications"]}},"parameters":{}},"paths":{"/v1/frontiers":{"get":{"tags":["Frontiers"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List frontiers","description":"All frontiers (AI, spaceflight, energy, …) with counts and the latest headline.","responses":{"200":{"description":"Frontier tiles, in display order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrontierList"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/frontiers/{frontier}":{"get":{"tags":["Frontiers"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get a frontier","description":"The frontier page model: the “how it works” explainer, its fields (blurb, explainer, counts), every program and company in it, and stats.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"energy"},"required":true,"name":"frontier","in":"path"}],"responses":{"200":{"description":"Frontier page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrontierPage"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/frontiers/{frontier}/programs/{program}":{"get":{"tags":["Programs"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get a program by its canonical address","description":"Programs are addressed by frontier + slug (the site URL is `/<frontier>/<program>`). Same model as `GET /companies/{company}/programs/{program}`.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"robotics"},"required":true,"name":"frontier","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"figure-03"},"required":true,"name":"program","in":"path"}],"responses":{"200":{"description":"Program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramPage"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/companies/{company}":{"get":{"tags":["Companies"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get a company","description":"The company page model: profile, frontiers, programs with next milestones, approach, people, funding, relationships, research, catalysts, instruments, peers.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"}],"responses":{"200":{"description":"Company page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPage"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/companies/{company}/programs/{program}":{"get":{"tags":["Programs"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get a program","description":"The program page model: live state, milestones, most important updates, important events (upcoming and past), specs, how it works, current obstacles, physics limits, catalysts, research, siblings and peer comparison.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"}],"responses":{"200":{"description":"Program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramPage"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/glossary":{"get":{"tags":["Glossary"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List glossary terms","description":"Every primer's slug, display term, aliases and frontiers. Small and cacheable; use it to auto-link terms in text.","responses":{"200":{"description":"Glossary index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlossaryIndex"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/glossary/{slug}":{"get":{"tags":["Glossary"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get a glossary term","description":"A primer: short line, 2–5 ELI5 points, the ink illustration (SVG markup, nullable), related terms, and programs where it matters.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"actuator"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Glossary term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlossaryTerm"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feed":{"get":{"tags":["Feed"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Query the news feed","description":"Updates (news) across the knowledge base, filterable by frontier, field, company, program, or an explicit list of companies/programs.\n\nPagination: with `sort=latest`, pass the response's `nextCursor` as `before` to get the next page.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":false,"name":"frontier","in":"query"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":false,"name":"field","in":"query"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":false,"name":"company","in":"query"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Requires `company`.","example":"helion"},"required":false,"name":"program","in":"query"},{"schema":{"type":"string","enum":["day","week","month","quarter","all"],"description":"Default `week`."},"required":false,"name":"window","in":"query"},{"schema":{"type":"string","enum":["top","latest"],"description":"Default `top`. Cursor pagination is only stable with `latest`."},"required":false,"name":"sort","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"majorOnly","in":"query"},{"schema":{"type":"string","description":"Comma-separated company slugs (e.g. a followed list).","example":"helion,oklo"},"required":false,"name":"companies","in":"query"},{"schema":{"type":"string","description":"Comma-separated `company/program` pairs.","example":"helion/polaris"},"required":false,"name":"programs","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"ISO timestamp or `nextCursor` from the previous page."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"If the window is empty, return the most recent items instead (`fellBack: true`)."},"required":false,"name":"fallback","in":"query"}],"responses":{"200":{"description":"A page of feed items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/updates/{id}":{"get":{"tags":["Feed"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Get one update (the story)","description":"The feed item plus `points`, the bullets under the summary.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The story","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Story"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"tags":["Search"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Search frontiers, companies and programs","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"example":"fusion"},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":25},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Matches, grouped frontier → company → program","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search/index":{"get":{"tags":["Search"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Compact index for client-side instant search","description":"Every frontier, company and program as `{ n: name, s: subtitle, u: path }`. Small; cache it.","responses":{"200":{"description":"Search index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchIndex"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ticker":{"get":{"tags":["Feed"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Ticker: rotating headlines and live market moves","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":false,"name":"frontier","in":"query"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":false,"name":"company","in":"query"}],"responses":{"200":{"description":"Ticker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticker"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"tags":["Meta"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Site-wide counts","responses":{"200":{"description":"Counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStats"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/health":{"get":{"tags":["Meta"],"summary":"Health check (no auth)","description":"Checks the database with `select 1` and reports the realtime listener. 503 when the DB is unreachable.","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/admin/updates":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Create an update (story)","description":"Idempotent when `externalKey` is given: replaying the same key returns the existing update with `created: false` (200) instead of 201. Emits `update.created` on the stream.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"occurredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}]},"headline":{"type":"string","minLength":8,"maxLength":160},"body":{"type":"string","maxLength":4000},"points":{"type":"array","items":{"type":"string","minLength":3,"maxLength":220},"maxItems":5},"kind":{"type":"string","enum":["test","hardware","software","manufacturing","regulatory","funding","hiring","commercial","research","partnership","people","other"]},"importance":{"type":"string","enum":["major","minor"]},"rank":{"type":"integer","minimum":0,"maximum":100},"sourceType":{"type":"string","enum":["x","blog","filing","press","livestream","paper","job","regulator","interview","other"]},"sourceUrl":{"type":"string","maxLength":2000,"format":"uri"},"alsoFrontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"maxItems":5,"default":[]},"verified":{"type":"boolean","default":false},"externalKey":{"type":"string","minLength":6,"maxLength":200}},"required":["company","occurredAt","headline","kind","importance","sourceType"]}}}},"responses":{"200":{"description":"Already existed (same externalKey)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUpdateResult"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUpdateResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/updates/story":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Write a story's summary and bullets, or correct its headline","description":"Replaces the summary (2–4 sentences) and bullets (2–5 key facts) of one update, by `id` or `externalKey`, and/or its `headline` (8–160 chars). Send `summary` and `points` together, or `headline` alone. Write from the original source; it is what readers see instead of the source.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalKey":{"type":"string","minLength":6,"maxLength":200},"headline":{"type":"string","minLength":8,"maxLength":160},"summary":{"type":"string","minLength":40,"maxLength":700},"points":{"type":"array","items":{"type":"string","minLength":3,"maxLength":220},"minItems":2,"maxItems":5}}}}}},"responses":{"200":{"description":"Written","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/updates/time":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Give a date-only story its exact publish time","description":"Sets the publisher's publish time (from the article page) on a story stored with only a date, by `id` or `externalKey`, so feeds say \"1d 10h ago\". The time must fall within 36 h of the story's date (409 otherwise); a story that already has a time is left as it is (`changed: false`).","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalKey":{"type":"string","minLength":6,"maxLength":200},"publishedAt":{"type":"string","format":"date-time"}},"required":["publishedAt"]}}}},"responses":{"200":{"description":"Written (or already timed)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changed":{"type":"boolean"}},"required":["id","changed"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/updates/date":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Correct a story's date","description":"Moves one update, by `id` or `externalKey`, to the day its source gives (`date` YYYY-MM-DD, stored date-only). `sources`: the pages showing that date (kept in the audit log). Unchanged → `changed: false`.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalKey":{"type":"string","minLength":6,"maxLength":200},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"sources":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5}},"required":["date","sources"]}}}},"responses":{"200":{"description":"Written (or already that day)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changed":{"type":"boolean"}},"required":["id","changed"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/updates/company":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Re-file a story under the right company/program","description":"Moves one update, by `id` or `externalKey`, to `company` (and `program`, or null for the company alone) when it was attached to the wrong one. The default frontier follows the new program (else the company's primary); extra frontiers stay. `reason` goes to the audit log. Unchanged → `changed: false`.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalKey":{"type":"string","minLength":6,"maxLength":200},"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":["string","null"],"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"reason":{"type":"string","minLength":8,"maxLength":500}},"required":["company","reason"]}}}},"responses":{"200":{"description":"Moved (or already there)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changed":{"type":"boolean"}},"required":["id","changed"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/{company}/{program}":{"patch":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Patch a program's live state","description":"Only provided fields change (`name` renames the program; its slug and URL stay). A stage/statusLine change emits `program.changed`.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"statusLine":{"type":"string","minLength":4,"maxLength":140},"description":{"type":"string","minLength":4,"maxLength":420},"goal":{"type":"string","minLength":20,"maxLength":240},"keywords":{"type":"string","minLength":2,"maxLength":60},"imageUrl":{"type":["string","null"],"format":"uri"}}}}}},"responses":{"200":{"description":"Updated program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/{company}/{program}/milestones":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Upsert milestone(s)","description":"Body is one milestone or an array. Matched by title (case-insensitive) within the program; `previousTitle` renames an existing milestone; new ones are inserted at `position` or appended. Setting `current` demotes the previous current milestone to `planned`. Each item is its own transaction.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":90},"status":{"type":"string","enum":["done","current","planned","missed"]},"date":{"type":["string","null"],"pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"originalTarget":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"note":{"type":"string","maxLength":240},"previousTitle":{"type":"string","minLength":2,"maxLength":90},"position":{"type":"integer","minimum":0},"sources":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5}},"required":["title","status"]},{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":90},"status":{"type":"string","enum":["done","current","planned","missed"]},"date":{"type":["string","null"],"pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"originalTarget":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"note":{"type":"string","maxLength":240},"previousTitle":{"type":"string","minLength":2,"maxLength":90},"position":{"type":"integer","minimum":0},"sources":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5}},"required":["title","status"]},"minItems":1,"maxItems":100}]}}}},"responses":{"200":{"description":"Updated program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/{company}/{program}/specs":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Upsert spec(s)","description":"Body is one spec or an array, keyed by `key` within the program.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","minLength":1,"maxLength":60},"numeric":{"type":"number","minimum":-3e+38,"maximum":3e+38},"unit":{"type":"string","maxLength":16},"previous":{"type":"string","maxLength":60},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["key","label","value","provenance"]},{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","minLength":1,"maxLength":60},"numeric":{"type":"number","minimum":-3e+38,"maximum":3e+38},"unit":{"type":"string","maxLength":16},"previous":{"type":"string","maxLength":60},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["key","label","value","provenance"]},"minItems":1,"maxItems":100}]}}}},"responses":{"200":{"description":"Updated program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Create or fully replace a program","description":"Same shape as seed files. Replaces the program's milestones, specs, technical blocks and catalysts. `?onlyNew=1` (routines that add programs): 409 and nothing written when the company already has a program with this slug.","parameters":[{"schema":{"type":"string","enum":["1","true"],"description":"Create only: 409 if it already exists"},"required":false,"name":"onlyNew","in":"query"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":60},"keywords":{"type":"string","minLength":1,"maxLength":60},"statusLine":{"type":"string","minLength":1,"maxLength":110},"description":{"type":"string","minLength":1,"maxLength":220},"goal":{"type":"string","minLength":1,"maxLength":240},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"isFlagship":{"type":"boolean","default":false},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"field":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"previousGeneration":{"type":"string","minLength":1,"maxLength":60},"milestones":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"status":{"type":"string","enum":["done","current","planned","missed"]},"originalTarget":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"note":{"type":"string","minLength":1,"maxLength":120}},"required":["title","status"]},"maxItems":12,"default":[]},"specs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","minLength":1,"maxLength":60},"numeric":{"type":"number","minimum":-3e+38,"maximum":3e+38},"unit":{"type":"string","minLength":1,"maxLength":16},"previous":{"type":"string","minLength":1,"maxLength":60},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["key","label","value","provenance"]},"maxItems":14,"default":[]},"howItWorks":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":30},"title":{"type":"string","minLength":1,"maxLength":60},"body":{"type":"string","minLength":1,"maxLength":160}},"required":["label","title","body"]},"maxItems":4,"default":[]},"obstacles":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":160},"status":{"type":"string","enum":["open","active_research","partially_solved","solved"],"default":"active_research"}},"required":["title","body"]},"maxItems":3,"default":[]},"limits":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":220}},"required":["title","body"]},"maxItems":3,"default":[]},"catalysts":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"kind":{"type":"string","minLength":1,"maxLength":30}},"required":["title","date"]},"maxItems":8,"default":[]},"checkedAt":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}},"required":["slug","name","keywords","statusLine","description","goal","stage"]}},"required":["company","program"]}}}},"responses":{"200":{"description":"Program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/{company}/{program}/checked":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Mark a program as checked","description":"Stamps the program's `checkedAt` (\"last checked\") without changing anything else: call it after re-verifying a program page when nothing changed. Body: `at` (ISO datetime or YYYY-MM-DD) defaults to now; `sources` (the pages checked) is required from routines. Program writes (patch, milestones, specs, full upsert) stamp it themselves.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}]},"sources":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5}}}}}},"responses":{"200":{"description":"Updated program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/worklist":{"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Program tracker worklist","description":"Programs due a check, most in need first. Tracked programs (top 20 per frontier by importance, or 60+) are due daily and at once when a story arrived after their last check; the rest when a milestone is overdue or monthly. `reason`: news | overdue | due soon | daily | monthly.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":2000},"required":false,"name":"max","in":"query"}],"responses":{"200":{"description":"Worklist","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"tracked":{"type":"integer"},"due":{"type":"integer"},"dueTracked":{"type":"integer"},"programs":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["total","tracked","due","dueTracked","programs"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/importance":{"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Importance worklist / review list","description":"`due=1`: programs the importance scorer must (re)score, grouped by frontier and field: never scored, older rubric version, stage changed since scoring, or scored over 90 days ago. Without it: every program, highest score first (the owner's review, incl. `dims.doubtful` flags). `max` limits the list.","parameters":[{"schema":{"type":"string","enum":["1","true"]},"required":false,"name":"due","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2000},"required":false,"name":"max","in":"query"}],"responses":{"200":{"description":"List","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"},"total":{"type":"integer"},"due":{"type":"integer"},"programs":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["version","total","due","programs"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Score program importance","description":"One score or an array (≤100). The five 0–5 dimensions (leap, reach, economy, lead, people) + `reason` (+ `doubtful` for the owner's cut list); the 0–100 score is computed server-side. `version` must equal the current rubric version (409 otherwise). `override` (pin a 0–100 score, null clears) is for admins, not routines. `?dry=1` computes without writing (calibration).","parameters":[{"schema":{"type":"string","enum":["1","true"],"description":"Calibration: validate and compute the scores, write nothing"},"required":false,"name":"dry","in":"query"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"company":{"type":"string","minLength":1,"maxLength":80},"program":{"type":"string","minLength":1,"maxLength":80},"dims":{"type":"object","properties":{"leap":{"type":"integer","minimum":0,"maximum":5},"reach":{"type":"integer","minimum":0,"maximum":5},"economy":{"type":"integer","minimum":0,"maximum":5},"lead":{"type":"integer","minimum":0,"maximum":5},"people":{"type":"integer","minimum":0,"maximum":5}},"required":["leap","reach","economy","lead","people"]},"reason":{"type":"string","minLength":10,"maxLength":300},"doubtful":{"type":"string","minLength":10,"maxLength":300},"version":{"type":"integer","minimum":1},"override":{"type":["integer","null"],"minimum":0,"maximum":100}},"required":["company","program","dims","reason","version"]},{"type":"array","items":{"type":"object","properties":{"company":{"type":"string","minLength":1,"maxLength":80},"program":{"type":"string","minLength":1,"maxLength":80},"dims":{"type":"object","properties":{"leap":{"type":"integer","minimum":0,"maximum":5},"reach":{"type":"integer","minimum":0,"maximum":5},"economy":{"type":"integer","minimum":0,"maximum":5},"lead":{"type":"integer","minimum":0,"maximum":5},"people":{"type":"integer","minimum":0,"maximum":5}},"required":["leap","reach","economy","lead","people"]},"reason":{"type":"string","minLength":10,"maxLength":300},"doubtful":{"type":"string","minLength":10,"maxLength":300},"version":{"type":"integer","minimum":1},"override":{"type":["integer","null"],"minimum":0,"maximum":100}},"required":["company","program","dims","reason","version"]},"minItems":1,"maxItems":100}]}}}},"responses":{"200":{"description":"Scored","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"results":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["ok","results"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/importance/clear":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Clear importance scores","description":"Admin only. Removes the routine's scores from the listed programs (or from every program when `programs` is omitted), e.g. after a bad run. Owner overrides stay.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"programs":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string"},"program":{"type":"string"}},"required":["company","program"]},"maxItems":2000}}}}}},"responses":{"200":{"description":"Cleared","content":{"application/json":{"schema":{"type":"object","properties":{"cleared":{"type":"integer"}},"required":["cleared"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/companies/{company}/checked":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Mark a company as checked","description":"Stamps the company's `checkedAt` (\"last checked\") without changing anything else: call it after re-verifying a company's facts when nothing changed. Body optional: `at` (ISO datetime or YYYY-MM-DD) defaults to now. A full company upsert stamps the company and all its programs itself.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}]},"sources":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5}}}}}},"responses":{"200":{"description":"Company page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/companies/{company}":{"patch":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Patch single company facts","description":"Only provided fields change (name (a rename; slug and URL stay), description, keywords, website, status, parent, ticker, exchange, employees + employeesAsOf, valuation, brief); nothing else is removed, `valuation: null` clears the valuation. Stamps `checkedAt`. Use this instead of the full replace (PUT /admin/companies) to keep a company current.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"description":{"type":"string","minLength":1,"maxLength":300},"keywords":{"type":"string","minLength":1,"maxLength":70},"website":{"type":"string","format":"uri"},"status":{"type":"string","enum":["private","public","subsidiary","acquired","defunct","government","nonprofit"]},"parent":{"type":"string","minLength":1,"maxLength":60},"ticker":{"type":"string","minLength":1,"maxLength":16},"exchange":{"type":"string","minLength":1,"maxLength":16},"employees":{"type":"integer","exclusiveMinimum":0},"employeesAsOf":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"valuation":{"type":["object","null"],"properties":{"usd":{"type":"number","exclusiveMinimum":0},"kind":{"type":"string","enum":["market_cap","private_valuation","deal_value","none"]},"asOf":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["usd","kind","asOf","provenance"]},"brief":{"type":"array","items":{"type":"string","minLength":4,"maxLength":140},"minItems":1,"maxItems":3}}}}}},"responses":{"200":{"description":"Company page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/companies/{company}/items":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Add, update or remove one person, funding round, relationship, approach block or open problem","description":"`kind`: person (matched by name) | funding (round name + year) | relationship (counterparty name) | approach (technical-approach block, by title) | problem (open problem, by title), case-insensitive. A match is updated, otherwise added; `remove: true` deletes the match (404 when none). Stamps `checkedAt`.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"remove":{"type":"boolean"},"item":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"role":{"type":"string","minLength":1,"maxLength":60},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["name","role"]}},"required":["kind","item"]},{"type":"object","properties":{"kind":{"type":"string","enum":["funding"]},"remove":{"type":"boolean"},"item":{"type":"object","properties":{"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"round":{"type":"string","minLength":1,"maxLength":40},"amountUsd":{"type":"number","exclusiveMinimum":0},"postMoneyUsd":{"type":"number","exclusiveMinimum":0},"leads":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":4,"default":[]},"provenance":{"type":"string","enum":["reported","estimated","sample"],"default":"reported"}},"required":["date","round"]}},"required":["kind","item"]},{"type":"object","properties":{"kind":{"type":"string","enum":["relationship"]},"remove":{"type":"boolean"},"item":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["customer","investor","supplier","partner","acquirer"]},"note":{"type":"string","minLength":1,"maxLength":160},"companySlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["name","kind"]}},"required":["kind","item"]},{"type":"object","properties":{"kind":{"type":"string","enum":["approach"]},"remove":{"type":"boolean"},"item":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":30},"title":{"type":"string","minLength":1,"maxLength":60},"body":{"type":"string","minLength":1,"maxLength":160}},"required":["label","title","body"]}},"required":["kind","item"]},{"type":"object","properties":{"kind":{"type":"string","enum":["problem"]},"remove":{"type":"boolean"},"item":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":160},"status":{"type":"string","enum":["open","active_research","partially_solved","solved"],"default":"active_research"}},"required":["title","body"]}},"required":["kind","item"]}]}}}},"responses":{"200":{"description":"Company page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/companies":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Create or fully replace a company","description":"Full upsert from a SeedCompany (same shape as seed files). Everything under the company is replaced, except existing updates (news is append-only). Programs missing from the payload are deleted. `?onlyNew=1` (routines that add companies): 409 and nothing written when the company exists; keep existing ones current with PATCH /admin/companies/{company} and PUT …/items.","parameters":[{"schema":{"type":"string","enum":["1","true"],"description":"Create only: 409 if it already exists"},"required":false,"name":"onlyNew","in":"query"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"company":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":60},"keywords":{"type":"string","minLength":1,"maxLength":70},"description":{"type":"string","minLength":1,"maxLength":300},"website":{"type":"string","format":"uri"},"hq":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"minItems":1,"maxItems":3},"founded":{"type":"integer","minimum":1800,"maximum":2100},"status":{"type":"string","enum":["private","public","subsidiary","acquired","defunct","government","nonprofit"]},"parent":{"type":"string","minLength":1,"maxLength":60},"ticker":{"type":"string","minLength":1,"maxLength":16},"exchange":{"type":"string","minLength":1,"maxLength":16},"employees":{"type":"integer","exclusiveMinimum":0},"employeesAsOf":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"valuation":{"type":"object","properties":{"usd":{"type":"number","exclusiveMinimum":0},"kind":{"type":"string","enum":["market_cap","private_valuation","deal_value","none"]},"asOf":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["usd","kind","asOf","provenance"]},"fields":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"minItems":1},"alsoFrontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"default":[]},"brief":{"type":"array","items":{"type":"string","minLength":1,"maxLength":140},"maxItems":3,"default":[]},"technicalApproach":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":30},"title":{"type":"string","minLength":1,"maxLength":60},"body":{"type":"string","minLength":1,"maxLength":160}},"required":["label","title","body"]},"maxItems":4,"default":[]},"openProblems":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":160},"status":{"type":"string","enum":["open","active_research","partially_solved","solved"],"default":"active_research"}},"required":["title","body"]},"maxItems":3,"default":[]},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"role":{"type":"string","minLength":1,"maxLength":60},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["name","role"]},"maxItems":6,"default":[]},"funding":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"round":{"type":"string","minLength":1,"maxLength":40},"amountUsd":{"type":"number","exclusiveMinimum":0},"postMoneyUsd":{"type":"number","exclusiveMinimum":0},"leads":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":4,"default":[]},"provenance":{"type":"string","enum":["reported","estimated","sample"],"default":"reported"}},"required":["date","round"]},"maxItems":10,"default":[]},"relationships":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["customer","investor","supplier","partner","acquirer"]},"note":{"type":"string","minLength":1,"maxLength":160},"companySlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["name","kind"]},"maxItems":10,"default":[]},"research":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"kind":{"type":"string","enum":["paper","blog","demo","talk","dataset","code"]},"title":{"type":"string","minLength":1,"maxLength":120},"why":{"type":"string","minLength":1,"maxLength":140},"programSlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["date","kind","title","why"]},"maxItems":8,"default":[]},"instruments":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string","minLength":1,"maxLength":16},"kind":{"type":"string","enum":["stock","preipo_perp"]}},"required":["symbol","kind"]},"maxItems":3,"default":[]},"programs":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":60},"keywords":{"type":"string","minLength":1,"maxLength":60},"statusLine":{"type":"string","minLength":1,"maxLength":110},"description":{"type":"string","minLength":1,"maxLength":220},"goal":{"type":"string","minLength":1,"maxLength":240},"stage":{"type":"string","enum":["research","proto","pilot","deploy","scaling"]},"isFlagship":{"type":"boolean","default":false},"frontier":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"field":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"previousGeneration":{"type":"string","minLength":1,"maxLength":60},"milestones":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"status":{"type":"string","enum":["done","current","planned","missed"]},"originalTarget":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"note":{"type":"string","minLength":1,"maxLength":120}},"required":["title","status"]},"maxItems":12,"default":[]},"specs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","minLength":1,"maxLength":60},"numeric":{"type":"number","minimum":-3e+38,"maximum":3e+38},"unit":{"type":"string","minLength":1,"maxLength":16},"previous":{"type":"string","minLength":1,"maxLength":60},"provenance":{"type":"string","enum":["reported","estimated","sample"]}},"required":["key","label","value","provenance"]},"maxItems":14,"default":[]},"howItWorks":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":30},"title":{"type":"string","minLength":1,"maxLength":60},"body":{"type":"string","minLength":1,"maxLength":160}},"required":["label","title","body"]},"maxItems":4,"default":[]},"obstacles":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":160},"status":{"type":"string","enum":["open","active_research","partially_solved","solved"],"default":"active_research"}},"required":["title","body"]},"maxItems":3,"default":[]},"limits":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":70},"body":{"type":"string","minLength":1,"maxLength":220}},"required":["title","body"]},"maxItems":3,"default":[]},"catalysts":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"kind":{"type":"string","minLength":1,"maxLength":30}},"required":["title","date"]},"maxItems":8,"default":[]},"checkedAt":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}},"required":["slug","name","keywords","statusLine","description","goal","stage"]},"minItems":1,"maxItems":24},"updates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"headline":{"type":"string","minLength":1,"maxLength":160},"programSlug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"kind":{"type":"string","enum":["test","hardware","software","manufacturing","regulatory","funding","hiring","commercial","research","partnership","people","other"]},"importance":{"type":"string","enum":["major","minor"]},"sourceType":{"type":"string","enum":["x","blog","filing","press","livestream","paper","job","regulator","interview","other"]},"sourceUrl":{"type":"string","maxLength":2000,"format":"uri"},"summary":{"type":"string","minLength":1,"maxLength":700},"points":{"type":"array","items":{"type":"string","minLength":1,"maxLength":220},"maxItems":5,"default":[]},"alsoFrontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"default":[]},"verified":{"type":"boolean","default":false}},"required":["date","headline","kind","importance","sourceType"]},"maxItems":80,"default":[]},"checkedAt":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}},"required":["slug","name","keywords","description","hq","status","fields","programs"]}},"required":["frontier","company"]}}}},"responses":{"200":{"description":"Company page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/frontiers":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Create or update a frontier and its fields","description":"Same shape as a seed file's `frontier` + `fields`. Fields are upserted by slug in the given order (that order is the radial order); fields left out are kept.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"frontier":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":40},"description":{"type":"string","minLength":1,"maxLength":160},"sortOrder":{"type":"integer"},"explainer":{"type":"array","items":{"type":"string","minLength":1,"maxLength":220},"minItems":3,"maxItems":6},"checkedAt":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"}},"required":["slug","name","description","sortOrder","explainer"]},"fields":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":32},"blurb":{"type":"string","minLength":1,"maxLength":90},"explainer":{"type":"array","items":{"type":"string","minLength":1,"maxLength":220},"minItems":3,"maxItems":5}},"required":["slug","name","blurb","explainer"]},"minItems":3,"maxItems":16}},"required":["frontier","fields"]}}}},"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrontierWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/media":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Point companies and programs at their self-hosted logos and photos","description":"One `SeedMediaFile` (packages/db/seed/media/<frontier>.json). Sets companies.logo_url and programs.image_url to the listed files; ship the files with the web app first. Unknown companies/programs are reported in `missing`.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"logos":{"type":"object","additionalProperties":{"type":"object","properties":{"file":{"type":"string","pattern":"^media\\/(logos|programs|mechanisms)\\/[a-z0-9-]+(--[a-z0-9-]+)?\\.(svg|webp)$"},"source":{"type":"string","minLength":1,"maxLength":30},"license":{"type":"string","enum":["public-domain","cc0","cc-by","cc-by-sa","trademark","press-kit","pixabay","unsplash","pexels"]},"licenseLabel":{"type":"string","minLength":1,"maxLength":40},"author":{"type":"string","minLength":1,"maxLength":120},"page":{"type":"string","format":"uri"},"note":{"type":"string","minLength":1,"maxLength":160},"terms":{"type":"string","minLength":1,"maxLength":300}},"required":["file","source","license","page"]},"default":{}},"programs":{"type":"object","additionalProperties":{"type":"object","properties":{"file":{"type":"string","pattern":"^media\\/(logos|programs|mechanisms)\\/[a-z0-9-]+(--[a-z0-9-]+)?\\.(svg|webp)$"},"source":{"type":"string","minLength":1,"maxLength":30},"license":{"type":"string","enum":["public-domain","cc0","cc-by","cc-by-sa","trademark","press-kit","pixabay","unsplash","pexels"]},"licenseLabel":{"type":"string","minLength":1,"maxLength":40},"author":{"type":"string","minLength":1,"maxLength":120},"page":{"type":"string","format":"uri"},"note":{"type":"string","minLength":1,"maxLength":160},"terms":{"type":"string","minLength":1,"maxLength":300}},"required":["file","source","license","page"]},"default":{}},"mechanisms":{"type":"object","additionalProperties":{"allOf":[{"type":"object","properties":{"file":{"type":"string","pattern":"^media\\/(logos|programs|mechanisms)\\/[a-z0-9-]+(--[a-z0-9-]+)?\\.(svg|webp)$"},"source":{"type":"string","minLength":1,"maxLength":30},"license":{"type":"string","enum":["public-domain","cc0","cc-by","cc-by-sa","trademark","press-kit","pixabay","unsplash","pexels"]},"licenseLabel":{"type":"string","minLength":1,"maxLength":40},"author":{"type":"string","minLength":1,"maxLength":120},"page":{"type":"string","format":"uri"},"note":{"type":"string","minLength":1,"maxLength":160},"terms":{"type":"string","minLength":1,"maxLength":300}},"required":["file","source","license","page"]},{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":160},"standIn":{"type":"boolean","default":false}},"required":["note"]}]},"default":{}}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/glossary":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Upsert glossary terms (primers)","description":"One `SeedGlossaryTerm` or an array, upserted by slug. Illustrations are not set here: they come from the ink pipeline (packages/ink/out/glossary) via the seed loader, and an upsert keeps the stored drawing.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"term":{"type":"string","minLength":1,"maxLength":60},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":12,"default":[]},"short":{"type":"string","minLength":1,"maxLength":140},"points":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":2,"maxItems":5},"frontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"minItems":1,"maxItems":6},"related":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"maxItems":8,"default":[]},"seeAlso":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"required":["company","program"]},"maxItems":4,"default":[]}},"required":["slug","term","short","points","frontiers"]},{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"term":{"type":"string","minLength":1,"maxLength":60},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":12,"default":[]},"short":{"type":"string","minLength":1,"maxLength":140},"points":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":2,"maxItems":5},"frontiers":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"minItems":1,"maxItems":6},"related":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"maxItems":8,"default":[]},"seeAlso":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"required":["company","program"]},"maxItems":4,"default":[]}},"required":["slug","term","short","points","frontiers"]},"minItems":1,"maxItems":100}]}}}},"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlossaryWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/quotes":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Record the latest market quote for an instrument","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","minLength":1,"maxLength":16},"kind":{"type":"string","enum":["stock","preipo_perp"]},"price":{"type":"number"},"impliedValuationUsd":{"type":"number"},"changePct":{"type":"number"},"asOf":{"type":"string","format":"date-time"},"isSample":{"type":"boolean","default":false}},"required":["symbol","kind","asOf"]}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/comp":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Give an email a plan for free, forever","description":"Requires the ADMIN_TOKEN. `plan: null` takes it away. Works before the person signs up (linked by email on first sign-in); takes effect at once, no deploy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"plan":{"type":["string","null"],"enum":["site","api","api_commercial"]}},"required":["email","plan"]}}}},"responses":{"200":{"description":"Set","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"email":{"type":"string"},"plan":{"type":["string","null"]},"userId":{"type":"string"},"signedUp":{"type":"boolean"}},"required":["ok","email","plan","userId","signedUp"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/api-keys":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Create an API key","description":"Requires the ADMIN_TOKEN (or a key with the `admin` scope). The raw key is returned ONCE; only its hash is stored.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/ops":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Report to the operations log","description":"Routines and scripts report what they did and every failure here (one event or up to 100). Stored with service `routine:<x-routine-name>` and shown on the owner's dashboard.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OpsEventInput"},{"type":"array","items":{"$ref":"#/components/schemas/OpsEventInput"},"minItems":1,"maxItems":100}]}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Read the operations log","description":"Newest first. `level` = minimum level; `service` accepts a trailing `*` (e.g. `routine:*`); `sinceId` returns only rows after that id.","parameters":[{"schema":{"type":"string","enum":["debug","info","warn","error","fatal"]},"required":false,"name":"level","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"service","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"sinceId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Rows","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["items"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/incidents":{"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"List incidents (production problems and their fix status)","description":"Synced from the operations log on every call: each distinct warning/error and each inbound email is one incident. Open ones first. `status` is comma-separated; `noIssue=1` = no GitHub issue yet.","parameters":[{"schema":{"type":"string","maxLength":100},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"noIssue","in":"query"},{"schema":{"type":"string","enum":["tech","content"]},"required":false,"name":"lane","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Incidents","content":{"application/json":{"schema":{"type":"object","properties":{"incidents":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}},"required":["incidents"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/incidents/{id}":{"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"One incident with its latest log samples","parameters":[{"schema":{"type":"integer","exclusiveMinimum":0},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Incident","content":{"application/json":{"schema":{"type":"object","properties":{"incident":{"$ref":"#/components/schemas/Incident"},"samples":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}},"required":["incident","samples"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Update an incident's status","description":"`in_progress` when work starts; `fixed` only after the fix is deployed and verified (with a one-sentence `summary` and `commitSha`); `not_a_bug` with the reason in `summary`. `needs_owner` is refused (422) except from to-autofix when locked out of an account.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":0},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["new","seen","in_progress","fixed","not_a_bug","needs_owner"]},"summary":{"type":"string","maxLength":1000},"commitSha":{"type":"string","maxLength":64},"issue":{"type":"integer","exclusiveMinimum":0}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"incident":{"$ref":"#/components/schemas/Incident"}},"required":["incident"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/incidents/next":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Take the next open incident (the fixer)","description":"Atomically marks the oldest `new` incident of the lane as `seen` and returns it with samples; `{ incident: null }` when there is nothing to do. `lane=tech` (default: the Opus fixer) or `lane=content` (the content bot: wrong data, routine 'needs review' reports).","parameters":[{"schema":{"type":"string","enum":["tech","content"]},"required":false,"name":"lane","in":"query"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"responses":{"200":{"description":"Next","content":{"application/json":{"schema":{"type":"object","properties":{"incident":{"allOf":[{"$ref":"#/components/schemas/Incident"},{"type":["object","null"]}]},"samples":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}},"required":["incident","samples"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/inbound-email":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Record an email sent to the site's address","description":"Called by the Cloudflare Email Worker for info@technooptimist.io (which also forwards the mail to the owner). Stored in the inbox (and noted in the ops log as service `email`), then the to-email-triage routine is started: it decides whether the email reports a real problem.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundEmail"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/emails":{"get":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"The inbox: emails sent to info@","description":"`status=unread` = the triage routine's queue, oldest first; otherwise newest first. Email text is untrusted input.","parameters":[{"schema":{"type":"string","enum":["unread","triaged"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Emails","content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/InboundEmailRow"}}},"required":["emails"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/emails/{id}":{"patch":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Record the triage of one email","description":"`category` + a one-line `summary` in our words. `problem: true` only for a bug, a technical issue or a clear shortfall of a feature: it opens an incident for the auto-fixer, titled `problemTitle`.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":0},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["bug","feature","question","business","feedback","spam","other"]},"summary":{"type":"string","minLength":3,"maxLength":500},"problem":{"type":"boolean"},"problemTitle":{"type":"string","maxLength":280}},"required":["category","summary","problem"]}}}},"responses":{"200":{"description":"Triaged","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"$ref":"#/components/schemas/InboundEmailRow"}},"required":["email"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/catalysts":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Set or add a catalyst (upcoming dated event)","description":"Matched by title (case-insensitive) within the program, or the company when `program` is omitted; `previousTitle` renames.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"title":{"type":"string","minLength":2,"maxLength":120},"date":{"type":"string","pattern":"^(\\d{4})(?:-(Q[1-4]|\\d{2})(?:-(\\d{2}))?)?$"},"kind":{"type":"string","maxLength":40},"previousTitle":{"type":"string","minLength":2,"maxLength":120}},"required":["company","title","date"]}}}},"responses":{"200":{"description":"Written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/programs/{company}/{program}/technical":{"put":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Add, update or remove one how-it-works part, current obstacle or physics limit","description":"`kind`: part | obstacle | limit. Matched by title within the program and kind (case-insensitive); `previousTitle` renames; `remove: true` deletes (404 when none). At most 4 parts, 3 obstacles, 3 limits (409 beyond). Stamps the program's `checkedAt`.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"helion"},"required":true,"name":"company","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"polaris"},"required":true,"name":"program","in":"path"},{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["part","obstacle","limit"]},"title":{"type":"string","minLength":3,"maxLength":70},"body":{"type":"string","minLength":10,"maxLength":220},"label":{"type":"string","minLength":2,"maxLength":30},"status":{"type":"string","enum":["open","active_research","partially_solved","solved"]},"previousTitle":{"type":"string","minLength":3,"maxLength":70},"remove":{"type":"boolean"}},"required":["kind","title"]}}}},"responses":{"200":{"description":"Updated program page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramWriteResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/admin/remove":{"post":{"tags":["Admin"],"security":[{"bearerAuth":[]}],"summary":"Remove one catalyst, milestone, spec or technical item","description":"Deletes a single item without replacing the program: catalyst/milestone/part/obstacle/limit by `title`, spec by `key`. `reason` is stored in the audit log. 404 when nothing matches.","parameters":[{"schema":{"type":"string","description":"Name of the routine making the write; recorded as `routine:<name>` in the audit log.","example":"news-scan"},"required":false,"name":"x-routine-name","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"program":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"kind":{"type":"string","enum":["catalyst","milestone","spec","part","obstacle","limit"]},"title":{"type":"string","minLength":2,"maxLength":120},"key":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"reason":{"type":"string","minLength":3,"maxLength":300}},"required":["company","kind","reason"]}}}},"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"removed":{"type":"number"}},"required":["ok","removed"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/follows":{"post":{"tags":["Me"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Follow a frontier, company or program","parameters":[{"schema":{"type":"string","format":"email","description":"DEV PLACEHOLDER for real user auth: identifies the user.","example":"you@example.com"},"required":false,"name":"x-user-email","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowInput"}}}},"responses":{"200":{"description":"Following","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Me"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Unfollow a frontier, company or program","parameters":[{"schema":{"type":"string","format":"email","description":"DEV PLACEHOLDER for real user auth: identifies the user.","example":"you@example.com"},"required":false,"name":"x-user-email","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowInput"}}}},"responses":{"200":{"description":"Not following","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowResult"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/notifications":{"get":{"tags":["Me"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Recent notifications for the user","description":"Created when an update lands on a followed company or program. Live delivery: subscribe to `user:<id>` on the stream.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"email","description":"DEV PLACEHOLDER for real user auth: identifies the user.","example":"you@example.com"},"required":false,"name":"x-user-email","in":"header"}],"responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notifications"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stream":{"get":{"tags":["Realtime"],"security":[{"apiKeyQuery":[]}],"summary":"Realtime stream (WebSocket)","description":"Upgrade to a WebSocket. Authenticate with `?api_key=` (browsers cannot set headers).\n\nClient → server: `{\"type\":\"subscribe\",\"topics\":[\"all\"]}`, `{\"type\":\"unsubscribe\",\"topics\":[…]}`, `{\"type\":\"ping\"}`.\n\nServer → client: `hello`, `subscribed`, `unsubscribed`, `pong`, `heartbeat` (every 25 s), `error`, and events\n\n(`update.created` with `data` = FeedItem, `program.changed`, `notification`).\n\nTopics: `all`, `frontier:<slug>`, `company:<slug>`, `program:<company>/<program>`, `user:<id>` (dev: requires matching `x-user-email`/`user_email`).","responses":{"101":{"description":"Switching protocols"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stream/sse":{"get":{"tags":["Realtime"],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Realtime stream (Server-Sent Events fallback)","description":"Same events as the WebSocket, as SSE (`event:` = message type, `data:` = JSON). Choose topics with `?topics=all,company:helion`.","responses":{"200":{"description":"text/event-stream","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}}},"webhooks":{}}