{ "openapi": "3.1.1", "info": { "title": "Yac.Api | v1", "version": "1.0.0" }, "servers": [ { "url": "https://yacdb.fyi/" } ], "paths": { "/api/v1/schema": { "get": { "tags": [ "Yac.Api" ], "summary": "Get the query schema", "description": "Datasets, columns, grains, keywords, and aggregate functions available to YACQL. Additive over time (new datasets/columns/keywords); send If-None-Match to get a 304 instead of the body.", "operationId": "GetSchemaV1", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/api/v1/meta": { "get": { "tags": [ "Yac.Api" ], "summary": "Get data freshness", "description": "completedSeason/completedWeek is the latest season/week with a played (scored) game — that's \"data through\". scheduledSeason > completedSeason means next season's schedule has loaded but no games have been played yet.", "operationId": "GetMetaV1", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaDto" } } } } } } }, "/api/v1/players": { "get": { "tags": [ "Yac.Api" ], "summary": "Search players by name", "description": "Fuzzy name search over the player index (exact match, then prefix, then substring; ties broken by career games). `name` on each result is the canonical value to use in YACQL filters; `slug` is the stable identifier for /players/{slug} and yacdb.fyi/player/{slug} links.", "operationId": "SearchPlayersV1", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayersSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } } } }, "/api/v1/players/{slug}": { "get": { "tags": [ "Yac.Api" ], "summary": "Resolve a player by slug", "operationId": "GetPlayerV1", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerIdentityDto" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } } } }, "/api/v1/teams": { "get": { "tags": [ "Yac.Api" ], "summary": "List all teams", "operationId": "GetTeamsV1", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamIdentityDto" } } } } } } } }, "/api/v1/teams/{slug}": { "get": { "tags": [ "Yac.Api" ], "summary": "Resolve a team by slug", "operationId": "GetTeamV1", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamIdentityDto" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } } } }, "/api/v1/query": { "post": { "tags": [ "Yac.Api" ], "summary": "Execute a YACQL query", "description": "Compiles and executes YACQL. Results are capped at 1,000 rows and 10 seconds. No authentication is required. Add ?format=csv for a CSV response instead of JSON (row count/elapsed/truncated move to X-Row-Count/X-Elapsed-Ms/X-Truncated headers).", "operationId": "ExecuteYacqlV1", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } } } }, "/api/v1/nl": { "post": { "tags": [ "Yac.Api" ], "summary": "Translate English to YACQL and execute it", "description": "Deterministic (no LLM, no cost) English -> YACQL translation, then the same execution path as /api/v1/query. yacql/data/meta are present together on success; clarification is set instead when the question is ambiguous — that's a 200, not an error.", "operationId": "TranslateAndExecuteNlV1", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicNlRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicNlResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } } } } }, "components": { "schemas": { "ClarificationDto": { "required": [ "question", "options" ], "type": "object", "properties": { "question": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } }, "ColumnDto": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "ConfidenceDto": { "required": [ "score", "threshold", "reasons" ], "type": "object", "properties": { "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "threshold": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "MetaDto": { "required": [ "completedSeason", "completedWeek", "scheduledSeason", "lastGameDate", "lastCompletedGameDate" ], "type": "object", "properties": { "completedSeason": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "completedWeek": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "scheduledSeason": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "lastGameDate": { "type": [ "null", "string" ], "format": "date" }, "lastCompletedGameDate": { "type": [ "null", "string" ], "format": "date" } } }, "PlayerIdentityDto": { "required": [ "slug", "name", "playerId", "position", "latestTeam", "teams", "seasons", "headshotUrl", "games" ], "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "playerId": { "type": "string" }, "position": { "type": [ "null", "string" ] }, "latestTeam": { "type": [ "null", "string" ] }, "teams": { "type": "array", "items": { "type": "string" } }, "seasons": { "type": "array", "items": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, "headshotUrl": { "type": [ "null", "string" ] }, "games": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PlayersSearchResponse": { "required": [ "players" ], "type": "object", "properties": { "players": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerIdentityDto" } } } }, "PublicApiError": { "required": [ "code", "message", "requestId" ], "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicErrorLocation" } ] }, "retryAfterSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "PublicErrorLocation": { "required": [ "line", "column", "start", "length" ], "type": "object", "properties": { "line": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "column": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "start": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PublicErrorResponse": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/PublicApiError" } } }, "PublicNlRequest": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": [ "null", "string" ] } } }, "PublicNlResponse": { "required": [ "yacql", "data", "meta", "clarification", "confidence" ], "type": "object", "properties": { "yacql": { "type": [ "null", "string" ] }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicQueryData" } ] }, "meta": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicQueryMeta" } ] }, "clarification": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClarificationDto" } ] }, "confidence": { "$ref": "#/components/schemas/ConfidenceDto" } } }, "PublicQueryData": { "required": [ "columns", "rows" ], "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnDto" } }, "rows": { "type": "array", "items": { "type": "array" } } } }, "PublicQueryMeta": { "required": [ "rowCount", "elapsedMs", "truncated" ], "type": "object", "properties": { "rowCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "elapsedMs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "truncated": { "type": "boolean" } } }, "PublicQueryRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "type": [ "null", "string" ] } } }, "PublicQueryResponse": { "required": [ "data", "meta" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicQueryData" }, "meta": { "$ref": "#/components/schemas/PublicQueryMeta" } } }, "SchemaColumnDto": { "required": [ "name", "type", "measure" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "measure": { "type": "boolean" } } }, "SchemaDatasetDto": { "required": [ "name", "columns", "defaultShow" ], "type": "object", "properties": { "name": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaColumnDto" } }, "defaultShow": { "type": "array", "items": { "type": "string" } } } }, "SchemaResponse": { "required": [ "datasets", "grains", "keywords", "functions" ], "type": "object", "properties": { "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaDatasetDto" } }, "grains": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "functions": { "type": "array", "items": { "type": "string" } } } }, "TeamIdentityDto": { "required": [ "slug", "abbr", "name", "division", "conference", "color", "historicalAbbrs" ], "type": "object", "properties": { "slug": { "type": "string" }, "abbr": { "type": "string" }, "name": { "type": "string" }, "division": { "type": "string" }, "conference": { "type": "string" }, "color": { "type": "string" }, "historicalAbbrs": { "type": "array", "items": { "type": "string" } } } } } }, "tags": [ { "name": "Yac.Api" } ] }