{"openapi":"3.1.0","info":{"title":"Shark Snip Entity Research API","version":"1.1.0","description":"Read-only roster, stored PPR projections, dated game actuals and sourced media context. Values can be stale, absent or unavailable. No wager execution. The master discovery contract is /api/v1/openapi.json. Research endpoints add source-built weekly summaries. GPTwork may select existing evidence IDs; this document grants no write or scheduling authority."},"servers":[{"url":"/"}],"paths":{"/api/v1/entities/nfl/players":{"get":{"operationId":"listNflEntityPlayers","summary":"List rostered fantasy players without a historical-feature-store cutoff.","security":[],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"description":"Rows per page."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque next_cursor. A changed identity population returns 409."},{"name":"team","in":"query","required":false,"schema":{"type":"string"},"description":"Known NFL abbreviation, alias or canonical team slug."},{"name":"position","in":"query","required":false,"schema":{"enum":["QB","RB","FB","WR","TE","K"]},"description":"Fantasy position."},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Case-insensitive name substring. Never used as SQL."}],"responses":{"200":{"description":"Dated public data. Check partial and each module state before using a value.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryResponse"}}}},"304":{"description":"Unchanged public representation; no response body."},"400":{"description":"Invalid or unsupported query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown or unsupported entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The directory changed (restart pagination), or a player name is ambiguous (use directory search and a canonical id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required source could not be read. Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate-limit or transport policy may refuse the request."}}}},"/api/v1/entities/nfl/players/{player}":{"get":{"operationId":"getNflPlayerOutlook","summary":"Read one player using a GSIS ID, canonical slug or unique roster name.","security":[],"parameters":[{"name":"player","in":"path","required":true,"schema":{"type":"string"},"description":"nfl-prefixed or bare GSIS ID, optional __name suffix, exact normalized roster name, or props name@kickoff-minute. URL-encode names. Ambiguous names return 409; studio: model references return 400."}],"responses":{"200":{"description":"Dated public data. Check partial and each module state before using a value.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerResponse"}}}},"304":{"description":"Unchanged public representation; no response body."},"400":{"description":"Invalid or unsupported query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown or unsupported entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The directory changed (restart pagination), or a player name is ambiguous (use directory search and a canonical id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required source could not be read. Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate-limit or transport policy may refuse the request."}}}},"/api/v1/entities/nfl/teams":{"get":{"operationId":"listNflEntityTeams","summary":"List the existing NFL team registry and canonical page paths.","security":[],"parameters":[],"responses":{"200":{"description":"Dated public data. Check partial and each module state before using a value.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamsResponse"}}}},"304":{"description":"Unchanged public representation; no response body."},"400":{"description":"Invalid or unsupported query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown or unsupported entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The directory changed (restart pagination), or a player name is ambiguous (use directory search and a canonical id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required source could not be read. Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate-limit or transport policy may refuse the request."}}}},"/api/v1/entities/nfl/teams/{team}":{"get":{"operationId":"getNflTeamOutlook","summary":"Read a team roster, stored projections, season schedule and cited buzz.","security":[],"parameters":[{"name":"team","in":"path","required":true,"schema":{"type":"string"},"description":"Known abbreviation, alias or canonical team slug."}],"responses":{"200":{"description":"Dated public data. Check partial and each module state before using a value.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamResponse"}}}},"304":{"description":"Unchanged public representation; no response body."},"400":{"description":"Invalid or unsupported query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown or unsupported entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The directory changed (restart pagination), or a player name is ambiguous (use directory search and a canonical id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required source could not be read. Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate-limit or transport policy may refuse the request."}}}},"/api/v1/entities/nfl/players/{player}/research":{"get":{"operationId":"getNflPlayerResearch","summary":"Read source-backed weekly outlook, matchup, usage, roster and availability context.","security":[],"parameters":[{"name":"player","in":"path","required":true,"schema":{"type":"string"},"description":"GSIS id, canonical slug, unique roster name or props name@kickoff-minute; URL-encode the reference."}],"responses":{"200":{"description":"Read each module state; historical usage is not a projection. No-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"}}}},"400":{"description":"Unsupported query or identity reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ambiguous player name; use directory search and a canonical id."},"503":{"description":"Required source unavailable; retry after 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate or transport gate."}}}},"/api/v1/entities/nfl/teams/{team}/research":{"get":{"operationId":"getNflTeamResearch","summary":"Read source-backed weekly outlook, matchup, usage, roster and availability context.","security":[],"parameters":[{"name":"team","in":"path","required":true,"schema":{"type":"string"},"description":"NFL team abbreviation or slug."}],"responses":{"200":{"description":"Read each module state; historical usage is not a projection. No-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"}}}},"400":{"description":"Unsupported query or identity reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verified unknown entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ambiguous player name; use directory search and a canonical id."},"503":{"description":"Required source unavailable; retry after 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Existing platform compliance, rate or transport gate."}}}}},"components":{"schemas":{"Period":{"type":"object","additionalProperties":false,"properties":{"season":{"type":"integer"},"week":{"type":"integer"}},"required":["season","week"]},"Team":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"wireKey":{"type":"string"},"name":{"type":"string"},"path":{"type":"string"}},"required":["code","wireKey","name","path"]},"Player":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"gsisId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"path":{"type":"string"},"position":{"enum":["QB","RB","FB","WR","TE","K"]},"team":{"anyOf":[{"$ref":"#/components/schemas/Team"},{"type":"null"}]},"rosterStatus":{"type":"string"},"rosterSeason":{"type":["integer","null"]},"rosterWeek":{"type":["integer","null"]},"observedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","gsisId","name","slug","path","position","team","rosterStatus","rosterSeason","rosterWeek","observedAt"]},"Coverage":{"type":"object","additionalProperties":false,"properties":{"sourceRows":{"type":"integer","minimum":0},"eligiblePlayers":{"type":"integer","minimum":0},"teams":{"type":"integer","minimum":0},"invalidRows":{"type":"integer","minimum":0},"conflictedPlayers":{"type":"integer","minimum":0},"unrecognizedTeams":{"type":"integer","minimum":0},"missingObservationTimes":{"type":"integer","minimum":0}},"required":["sourceRows","eligiblePlayers","teams","invalidRows","conflictedPlayers","unrecognizedTeams","missingObservationTimes"]},"Projection":{"type":"object","additionalProperties":false,"properties":{"points":{"type":"number"},"scoring":{"const":"ppr"},"kind":{"enum":["house","espn-fallback"]},"source":{"enum":["house","espn"]},"season":{"type":"integer"},"week":{"type":"integer"},"positionRank":{"type":["integer","null"]},"positionTotal":{"type":"integer"}},"required":["points","scoring","kind","source","season","week","positionRank","positionTotal"]},"GameStats":{"type":"object","additionalProperties":false,"properties":{"season":{"type":"integer"},"week":{"type":"integer"},"gameId":{"type":["string","null"]},"opponent":{"type":["string","null"]},"pprPoints":{"type":["number","null"]},"passingYards":{"type":["number","null"]},"rushingYards":{"type":["number","null"]},"receivingYards":{"type":["number","null"]},"targets":{"type":["number","null"]},"receptions":{"type":["number","null"]},"carries":{"type":["number","null"]}},"required":["season","week","gameId","opponent","pprPoints","passingYards","rushingYards","receivingYards","targets","receptions","carries"]},"Injury":{"type":"object","additionalProperties":false,"properties":{"reportStatus":{"type":["string","null"]},"practiceStatus":{"type":["string","null"]},"injury":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]}},"required":["reportStatus","practiceStatus","injury","sourceUrl"]},"Buzz":{"type":"object","additionalProperties":false,"properties":{"mentions":{"type":["integer","null"]},"velocity":{"type":["number","null"]},"quotes":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"},"source":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"}},"required":["text","source","title","url","publishedAt"]}},"news":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"headline":{"type":"string"},"url":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"}},"required":["headline","url","publishedAt"]}}},"required":["mentions","velocity","quotes","news"]},"TeamGame":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"season":{"type":"integer"},"week":{"type":"integer"},"date":{"type":"string","format":"date"},"opponent":{"anyOf":[{"$ref":"#/components/schemas/Team"},{"type":"null"}]},"home":{"type":"boolean"},"venue":{"type":["string","null"]},"final":{"type":"boolean"},"pointsFor":{"type":["number","null"]},"pointsAgainst":{"type":["number","null"]},"spread":{"type":["number","null"]},"total":{"type":["number","null"]},"moneyline":{"type":["number","null"]},"oddsAsOf":{"type":["string","null"],"format":"date-time"},"oddsState":{"enum":["ready","stale","unavailable"]}},"required":["id","season","week","date","opponent","home","venue","final","pointsFor","pointsAgainst","spread","total","moneyline","oddsAsOf","oddsState"]},"PlayerHub":{"type":"object","additionalProperties":false,"properties":{"schemaVersion":{"const":1},"player":{"$ref":"#/components/schemas/Player"},"period":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"roster":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"projection":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Projection"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"projectionLabel":{"type":"string"},"history":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/GameStats"}},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"injury":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Injury"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"buzz":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Buzz"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"indexable":{"type":"boolean"}},"required":["schemaVersion","player","period","roster","projection","projectionLabel","history","injury","buzz","indexable"]},"TeamHub":{"type":"object","additionalProperties":false,"properties":{"schemaVersion":{"const":1},"team":{"$ref":"#/components/schemas/Team"},"season":{"type":["integer","null"]},"roster":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"period":{"$ref":"#/components/schemas/Period"},"coverage":{"$ref":"#/components/schemas/Coverage"}},"required":["period","coverage"]},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"players":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"player":{"$ref":"#/components/schemas/Player"},"projection":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Projection"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]}},"required":["player","projection"]}},"games":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/TeamGame"}},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"buzz":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Buzz"},{"type":"null"}]},"asOf":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]}},"required":["schemaVersion","team","season","roster","players","games","buzz"]},"PlayerResponse":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"sport":{"const":"nfl"},"partial":{"type":"boolean"},"hub":{"$ref":"#/components/schemas/PlayerHub"},"links":{"type":"object","additionalProperties":false,"properties":{"canonical":{"type":"string"},"documentation":{"type":"string"}},"required":["canonical","documentation"]}},"required":["schema_version","sport","partial","hub","links"]},"TeamResponse":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"sport":{"const":"nfl"},"partial":{"type":"boolean"},"hub":{"$ref":"#/components/schemas/TeamHub"},"links":{"type":"object","additionalProperties":false,"properties":{"canonical":{"type":"string"},"documentation":{"type":"string"}},"required":["canonical","documentation"]}},"required":["schema_version","sport","partial","hub","links"]},"DirectoryResponse":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"sport":{"const":"nfl"},"period":{"$ref":"#/components/schemas/Period"},"state":{"enum":["ready","stale","empty","unavailable"]},"as_of":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]},"coverage":{"$ref":"#/components/schemas/Coverage"},"total":{"type":"integer"},"players":{"type":"array","items":{"$ref":"#/components/schemas/Player"}},"next_cursor":{"type":["string","null"]},"links":{"type":"object","additionalProperties":false,"properties":{"directory":{"type":"string"},"documentation":{"type":"string"}},"required":["directory","documentation"]}},"required":["schema_version","sport","period","state","as_of","reason","coverage","total","players","next_cursor","links"]},"TeamsResponse":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"sport":{"const":"nfl"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/Team"}},"documentation":{"type":"string"}},"required":["schema_version","sport","teams","documentation"]},"Error":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"error":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string"}},"required":["reason"]},"documentation":{"type":"string"}},"required":["schema_version","error","documentation"]},"ResearchIdentity":{"type":"object","additionalProperties":false,"properties":{"kind":{"enum":["team","player"]},"id":{"type":"string"},"name":{"type":"string"},"path":{"type":"string"}},"required":["kind","id","name","path"]},"ResearchMatchup":{"type":"object","additionalProperties":false,"properties":{"gameId":{"type":"string"},"period":{"$ref":"#/components/schemas/Period"},"opponent":{"$ref":"#/components/schemas/Team"},"home":{"type":"boolean"},"kickoffAt":{"type":"string"},"kickoffSource":{"type":"string"},"phase":{"enum":["scheduled","kickoff-reached"]}},"required":["gameId","period","opponent","home","kickoffAt","kickoffSource","phase"]},"ResearchDepth":{"type":"object","additionalProperties":false,"properties":{"playerId":{"type":"string"},"name":{"type":"string"},"formation":{"type":"string"},"position":{"type":"string"},"depthSlot":{"type":"string"},"observedAt":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]}},"required":["playerId","name","formation","position","depthSlot","observedAt","sourceUrl"]},"ResearchDepthSnapshot":{"type":"object","additionalProperties":false,"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ResearchDepth"}},"coverage":{"type":"object","additionalProperties":false,"properties":{"sourceRows":{"type":"integer"},"fantasyRows":{"type":"integer"},"quarantinedRows":{"type":"integer"},"conflictedGroups":{"type":"integer"}},"required":["sourceRows","fantasyRows","quarantinedRows","conflictedGroups"]}},"required":["rows","coverage"]},"ResearchAvailability":{"type":"object","additionalProperties":false,"properties":{"playerId":{"type":"string"},"name":{"type":"string"},"position":{"type":["string","null"]},"reportStatus":{"type":["string","null"]},"practiceStatus":{"type":["string","null"]},"injury":{"type":["string","null"]},"observedAt":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"path":{"type":["string","null"]}},"required":["playerId","name","position","reportStatus","practiceStatus","injury","observedAt","sourceUrl","path"]},"ResearchPeer":{"type":"object","additionalProperties":false,"properties":{"player":{"$ref":"#/components/schemas/Player"},"projection":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/Projection"},{"type":"null"}]},"asOf":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]}},"required":["player","projection"]},"UsageWindow":{"type":"object","additionalProperties":false,"properties":{"season":{"type":"integer"},"weeks":{"type":"array","items":{"type":"integer"}},"observations":{"type":"integer"},"value":{"type":["number","null"]}},"required":["season","weeks","observations","value"]},"UsageMetric":{"type":"object","additionalProperties":false,"properties":{"key":{"enum":["targets","carries","receptions","passingYards","rushingYards","receivingYards","pprPoints"]},"label":{"type":"string"},"unit":{"type":"string"},"recent":{"$ref":"#/components/schemas/UsageWindow"},"previous":{"$ref":"#/components/schemas/UsageWindow"},"difference":{"type":["number","null"]},"series":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"season":{"type":"integer"},"week":{"type":"integer"},"value":{"type":["number","null"]}},"required":["season","week","value"]}}},"required":["key","label","unit","recent","previous","difference","series"]},"WeeklyFact":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"text":{"type":"string"},"category":{"enum":["matchup","projection","usage","availability","depth","discussion"]},"sourceLabel":{"type":"string"},"sourcePath":{"type":"string"},"asOf":{"type":["string","null"]},"state":{"enum":["ready","stale","historical"]}},"required":["id","text","category","sourceLabel","sourcePath","asOf","state"]},"WeeklyWatch":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"text":{"type":"string"},"sourcePath":{"type":"string"}},"required":["id","text","sourcePath"]},"WeeklyPacket":{"type":"object","additionalProperties":false,"properties":{"schemaVersion":{"const":1},"entity":{"$ref":"#/components/schemas/ResearchIdentity"},"period":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"evidenceVersion":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sourceAsOf":{"type":["string","null"]},"preparedAt":{"type":"string"},"validUntil":{"type":"string"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyFact"}},"requiredFactIds":{"type":"array","items":{"type":"string"}},"watch":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyWatch"}},"editorialEligible":{"type":"boolean"}},"required":["schemaVersion","entity","period","evidenceVersion","sourceAsOf","preparedAt","validUntil","facts","requiredFactIds","watch","editorialEligible"]},"WeeklyBrief":{"type":"object","additionalProperties":false,"properties":{"mode":{"enum":["automatic","gptwork-curated"]},"state":{"enum":["current","needs-refresh"]},"reason":{"type":["string","null"]},"period":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"updatedAt":{"type":["string","null"]},"expiresAt":{"type":"string"},"paragraphs":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyFact"}}},"required":["text","facts"]}},"watch":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyWatch"}}},"required":["mode","state","reason","period","updatedAt","expiresAt","paragraphs","watch"]},"WeeklySelection":{"type":"object","additionalProperties":false,"properties":{"schemaVersion":{"const":1},"entityId":{"type":"string"},"evidenceVersion":{"type":"string"},"period":{"$ref":"#/components/schemas/Period"},"paragraphs":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string"}}},"watchIds":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string"}}},"required":["schemaVersion","entityId","evidenceVersion","period","paragraphs","watchIds"]},"EntityResearch":{"type":"object","additionalProperties":false,"properties":{"schemaVersion":{"const":1},"entity":{"$ref":"#/components/schemas/ResearchIdentity"},"period":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"evaluatedAt":{"type":"string"},"matchup":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/ResearchMatchup"},{"type":"null"}]},"asOf":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"depth":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"$ref":"#/components/schemas/ResearchDepthSnapshot"},{"type":"null"}]},"asOf":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"availability":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ResearchAvailability"}},{"type":"null"}]},"asOf":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"peers":{"type":"object","additionalProperties":false,"properties":{"state":{"enum":["ready","stale","empty","unavailable"]},"value":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ResearchPeer"}},{"type":"null"}]},"asOf":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["state","value","asOf","reason"]},"usage":{"type":"array","items":{"$ref":"#/components/schemas/UsageMetric"}},"weekly":{"type":"object","additionalProperties":false,"properties":{"packet":{"$ref":"#/components/schemas/WeeklyPacket"},"brief":{"$ref":"#/components/schemas/WeeklyBrief"},"publicationState":{"enum":["ready","empty","unavailable"]}},"required":["packet","brief","publicationState"]}},"required":["schemaVersion","entity","period","evaluatedAt","matchup","depth","availability","peers","usage","weekly"]},"ResearchResponse":{"type":"object","additionalProperties":false,"properties":{"schema_version":{"const":1},"research":{"$ref":"#/components/schemas/EntityResearch"},"documentation":{"type":"string"}},"required":["schema_version","research","documentation"]}}}}