{ "openapi": "3.1.0", "info": { "title": "NuttyRefs API", "version": "1.6.0", "description": "College and NFL officiating controversies, cited evidence and fan opinions. Public reads require no authentication. Unknown facts are null. External agents submit leads with scoped credentials; NuttyRefs independently researches and gates publication. Register at /developers. Automated provenance is explicit. Developing incidents may establish discussion before independent reporting. Agents submit leads, not verdicts. Fan Verdict voting requires a neutral debate_question, not final_ruling. No-call debates can accept votes while final_ruling is null. Sources can be empty for Developing incidents; safe discussion and structured-play provenance remain available." }, "servers": [ { "url": "https://www.nuttyrefs.com" } ], "paths": { "/api/v1/games": { "get": { "operationId": "listGames", "summary": "Read game data", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "season", "in": "query", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "week", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 30 } }, { "name": "team_id", "in": "query", "schema": { "type": "string" } }, { "name": "league", "in": "query", "schema": { "type": "string", "enum": [ "college", "nfl" ] } }, { "name": "season_type", "in": "query", "schema": { "type": "string", "enum": [ "preseason", "regular", "postseason", "unknown" ] } }, { "name": "from", "in": "query", "description": "Inclusive UTC kickoff date or timestamp.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive UTC kickoff date or timestamp.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "upcoming", "live", "final", "postponed", "canceled" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "kickoff", "recent" ] } } ], "responses": { "200": { "description": "Public resource(s). Unknown facts are null. No candidates or private ballot identities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Game" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/games/{id}": { "get": { "operationId": "getGame", "summary": "Read game data", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public resource(s). Unknown facts are null. No candidates or private ballot identities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Game" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/incidents": { "get": { "operationId": "listIncidents", "summary": "Recent football debates and Fan Verdict results", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "season", "in": "query", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "week", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 30 } }, { "name": "team_id", "in": "query", "schema": { "type": "string" } }, { "name": "game_id", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "enum": [ "penalty", "replay", "clock", "spot", "targeting", "other", "no_call", "catch" ] } }, { "name": "league", "in": "query", "schema": { "type": "string", "enum": [ "college", "nfl" ] } }, { "name": "season_type", "in": "query", "schema": { "type": "string", "enum": [ "preseason", "regular", "postseason", "unknown" ] } }, { "name": "from", "in": "query", "description": "Inclusive UTC publication date or timestamp.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive UTC publication date or timestamp.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "developing", "corroborated", "explained", "resolved" ], "description": "Evidence maturity, not a correctness verdict. Developing may have no independent article or final ruling. Resolved is a legacy editorial status." } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent" ] } }, { "name": "has_verdict", "in": "query", "schema": { "type": "boolean" }, "description": "true returns incidents with a Fan Verdict question, newest first. Final ruling is not required." } ], "responses": { "200": { "description": "Public resource(s). Unknown facts are null. No candidates or private ballot identities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/incidents/{id}": { "get": { "operationId": "getIncident", "summary": "Read published incidents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public resource(s). Unknown facts are null. No candidates or private ballot identities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IncidentDetail" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "308": { "description": "A formerly public duplicate redirects to the surviving published incident." } } } }, "/api/agents/v1/scout": { "post": { "operationId": "scoutCheckpoint", "summary": "Private Scout run checkpoint and shadow/candidate intake", "description": "begin claims a bounded run; reserve reserves X reads or model micro-USD before a call; finish records observations and proposed evaluations. Server computes scoring/deduplication. Candidate creation is disabled by default and controlled only by the server. No publication, voting, comments, private incident listing, or browser authentication. Completed runs accept only the identical serialized JSON payload on retry. Responses are no-store.", "security": [ { "ScoutCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "status", "begin", "reserve", "finish" ] }, "key": { "type": "string", "maxLength": 100 }, "runId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "x", "model" ] }, "units": { "type": "integer", "minimum": 1 }, "signals": { "type": "array", "maxItems": 500, "items": { "type": "object" } }, "evaluations": { "type": "object" }, "checkpoints": { "type": "object" }, "report": { "type": "object" } } } } } }, "responses": { "200": { "description": "Run receipt or skip; never private incident details" }, "400": { "description": "Invalid request" }, "403": { "description": "Missing, revoked, expired or unscoped credential" }, "409": { "description": "Idempotency conflict" }, "503": { "description": "Unavailable" } } } }, "/api/v1/agent-leads": { "post": { "operationId": "submitAgentLead", "summary": "Submit a lead for independent research", "description": "3/minute and 20/rolling day per agent; global 200/day. Retry unchanged payload with the same key. External assertions do not establish facts.", "security": [ { "AgentKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLead" } } } }, "responses": { "202": { "description": "Accepted for validation. data contains id, status=accepted_for_validation, and links.self.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "links" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "accepted_for_validation" }, "links": { "type": "object", "properties": { "self": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid lead or unsupported fields" }, "403": { "description": "Invalid, expired, revoked or banned credential" }, "409": { "description": "Idempotency conflict" }, "429": { "description": "Quota reached" }, "503": { "description": "Temporarily unavailable" } } } }, "/api/v1/agent-leads/{id}": { "get": { "operationId": "getAgentLead", "summary": "Read your own lead validation status", "security": [ { "AgentKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "data contains id, game_id, created_at, status (pending/running/rejected/published/duplicate/failed), updatedAt and incidentId (null unless public)." }, "400": { "description": "Invalid ID" }, "403": { "description": "Invalid credential" }, "404": { "description": "Lead not found or owned by another agent" }, "503": { "description": "Temporarily unavailable" } } } }, "/incidents/feed.xml": { "get": { "summary": "Latest published debates as RSS", "responses": { "200": { "description": "RSS 2.0 with canonical URLs, league, matchup, debate question, maturity, context and publication/update times", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Pagination": { "type": "object", "required": [ "limit", "offset", "nextOffset" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 }, "nextOffset": { "type": [ "integer", "null" ] } } }, "Team": { "type": "object", "required": [ "id", "name", "abbreviation", "logoUrl", "conference" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "conference": { "type": [ "string", "null" ] }, "league": { "type": [ "string", "null" ], "enum": [ "college", "nfl", null ] }, "division": { "type": [ "string", "null" ] }, "shortName": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "aliases": { "type": "array", "items": { "type": "string" } } } }, "Game": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque identifier; may include a provider namespace." }, "homeTeam": { "$ref": "#/components/schemas/Team" }, "awayTeam": { "$ref": "#/components/schemas/Team" }, "homeScore": { "type": [ "integer", "null" ] }, "awayScore": { "type": [ "integer", "null" ] }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "kickoffTbd": { "type": "boolean" }, "period": { "type": [ "integer", "null" ] }, "clock": { "type": [ "string", "null" ] }, "status": { "enum": [ "upcoming", "live", "final", "postponed", "delayed", "canceled", "unknown" ] }, "season": { "type": "integer" }, "week": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "incidents": { "type": "string", "format": "uri" } } }, "league": { "type": "string", "enum": [ "college", "nfl" ] }, "seasonType": { "type": "string", "enum": [ "preseason", "regular", "postseason", "unknown" ] }, "stageLabel": { "type": [ "string", "null" ], "description": "Provider stage/round label when known. Super Bowl is postseason, round 4." } }, "required": [ "id", "homeTeam", "awayTeam", "homeScore", "awayScore", "startsAt", "kickoffTbd", "period", "clock", "status", "season", "week", "createdAt", "updatedAt", "url", "links" ] }, "Incident": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "game_id": { "type": "string" }, "title": { "type": "string" }, "play_description": { "type": "string" }, "neutral_summary": { "type": [ "string", "null" ] }, "category": { "enum": [ "penalty", "replay", "clock", "spot", "targeting", "other", "no_call", "catch" ] }, "period": { "type": [ "integer", "null" ] }, "clock": { "type": [ "string", "null" ] }, "original_ruling": { "type": [ "string", "null" ] }, "final_ruling": { "type": [ "string", "null" ] }, "replay_involved": { "type": [ "boolean", "null" ] }, "consequence": { "type": [ "string", "null" ] }, "publication_status": { "const": "published" }, "status": { "enum": [ "developing", "corroborated", "explained", "resolved" ], "description": "Evidence maturity, not a correctness verdict. Developing may have no independent article or final ruling. Resolved is a legacy editorial status." }, "origin_kind": { "enum": [ "human", "agent", "migration" ] }, "provenance": { "type": "object", "description": "Server-assigned workflow attribution; no credentials." }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "published_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "duplicate_of": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "game": { "type": "string", "format": "uri" }, "gamePage": { "type": "string", "format": "uri" } } }, "league": { "type": "string", "enum": [ "college", "nfl" ] }, "seasonType": { "type": "string", "enum": [ "preseason", "regular", "postseason", "unknown" ] }, "ruling_version": { "type": "integer", "minimum": 1, "description": "Compatibility alias for the current question version. Question/label/context changes archive ballots; old ballots are never reinterpreted." }, "debate_question": { "anyOf": [ { "$ref": "#/components/schemas/DebateQuestion" }, { "type": "null" } ] }, "penalty_called": { "type": [ "boolean", "null" ], "description": "Supported factual flag status; null means unknown. Not inferred from a no-call question." }, "votes": { "$ref": "#/components/schemas/Votes", "description": "Current-question aggregates include authenticated and anonymous browser ballots. Anonymous identity hashes are private; anonymous ballots have no rooting declaration. Informal fan opinion, not verified-person surveys." }, "comment_count": { "type": "integer", "minimum": 0 }, "matchup": { "type": "string" }, "slug": { "type": [ "string", "null" ], "description": "Stable descriptive human-page slug; does not change with headlines." }, "public_url": { "type": "string", "format": "uri", "description": "Canonical human-page URL. API identity remains the immutable UUID." }, "display_question": { "type": "string", "description": "Contextual human presentation of the debate. The canonical debate_question and question_version determine ballot meaning." } }, "required": [ "id", "game_id", "title", "play_description", "neutral_summary", "category", "period", "clock", "original_ruling", "final_ruling", "replay_involved", "consequence", "publication_status", "status", "origin_kind", "provenance", "reviewed_at", "published_at", "created_at", "updated_at", "duplicate_of", "url", "links" ] }, "Source": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "publisher": { "type": [ "string", "null" ] }, "source_kind": { "enum": [ "report", "video", "image", "official_statement", "rule", "other" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "added_at": { "type": "string", "format": "date-time" }, "supports": { "type": "string" }, "added_by": { "type": [ "string", "null" ], "format": "uuid", "description": "Contributor ID, null if no longer available; no private account data." } }, "required": [ "id", "url", "title", "publisher", "source_kind", "published_at", "added_at", "supports", "added_by" ] }, "Choices": { "type": "object", "required": [ "correct", "incorrect", "unsure" ], "properties": { "correct": { "type": "number", "minimum": 0 }, "incorrect": { "type": "number", "minimum": 0 }, "unsure": { "type": "number", "minimum": 0 } } }, "Votes": { "type": "object", "properties": { "total": { "type": "integer" }, "counts": { "$ref": "#/components/schemas/Choices" }, "percentages": { "$ref": "#/components/schemas/Choices" }, "rooting": { "type": "object", "properties": { "home": { "$ref": "#/components/schemas/Choices" }, "away": { "$ref": "#/components/schemas/Choices" }, "neutral": { "$ref": "#/components/schemas/Choices" }, "undisclosed": { "$ref": "#/components/schemas/Choices" }, "unspecified": { "$ref": "#/components/schemas/Choices" } } } }, "required": [ "total", "counts", "percentages", "rooting" ], "description": "Fan opinions on the current question version. correct maps to option_a_label, incorrect to option_b_label, unsure to unsure_label. Percentages are raw arithmetic, not a representative survey. Display counts below 20 votes in the displayed population. Rooting counts are self-declared: hide all rooting breakdowns below 50 total votes and subgroup results below 10 ballots, show counts at 10\u201319, and percentages at 20+. Read source supports notes; a gamebook reference may establish game context without verifying the disputed act." }, "IncidentDetail": { "allOf": [ { "$ref": "#/components/schemas/Incident" }, { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "votes": { "$ref": "#/components/schemas/Votes" }, "question_history": { "type": "array", "description": "Preserved question and factual snapshots, in version order. No individual ballots or voter identities.", "items": { "type": "object", "properties": { "question_version": { "type": "integer" }, "question": { "type": "object" }, "factual_context": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "superseded_at": { "type": [ "string", "null" ], "format": "date-time" }, "presented_question": { "anyOf": [ { "$ref": "#/components/schemas/DebateQuestion" }, { "type": "null" } ], "description": "Human/API label presentation of this historical question; question remains the original stored snapshot." } } } } } } ] }, "AgentLead": { "type": "object", "additionalProperties": false, "required": [ "game_id", "description", "source_urls" ], "properties": { "game_id": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "minLength": 10, "maxLength": 5000 }, "source_urls": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "uri" } }, "period": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 }, "clock": { "type": [ "string", "null" ], "pattern": "^([0-9]|1[0-5]):[0-5][0-9]$" }, "category": { "type": [ "string", "null" ], "enum": [ "penalty", "replay", "clock", "spot", "targeting", "other", null ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Submitter opinion only; not publication confidence." } } }, "DebateQuestion": { "type": "object", "properties": { "question_type": { "type": "string" }, "question_text": { "type": "string" }, "option_a_label": { "type": "string" }, "option_b_label": { "type": "string" }, "unsure_label": { "type": "string" }, "question_version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "label_presentation_version": { "type": "integer", "enum": [ 1 ], "description": "Human label mapping revision; separate from the ballot question version." }, "stored_option_labels": { "type": "object", "required": [ "option_a_label", "option_b_label", "unsure_label" ], "properties": { "option_a_label": { "type": "string" }, "option_b_label": { "type": "string" }, "unsure_label": { "type": "string" } }, "description": "Original stored labels for compatibility and historical interpretation." } }, "required": [ "question_type", "question_text", "option_a_label", "option_b_label", "unsure_label", "question_version", "created_at" ], "description": "Versioned Fan Verdict question. Option labels match human presentation without changing A/B ballot meaning. stored_option_labels retains the database snapshot; label_presentation_version identifies the presentation mapping. question_version remains unchanged by synonymous label clarification." } }, "securitySchemes": { "ScoutCredential": { "type": "http", "scheme": "bearer", "description": "Revocable NuttyRefs candidate-only agent credential. Not a human JWT or Supabase key." }, "AgentKey": { "type": "http", "scheme": "bearer", "description": "nrlead_ credential from /developers; submit_lead only; expires after 90 days." } } }, "externalDocs": { "url": "https://www.nuttyrefs.com/developers", "description": "Self-service registration, examples, authentication and attribution" } }