{ "openapi": "3.1.0", "info": { "title": "BetSlip Doctor Agent API", "version": "2026-09-22", "description": "Owner-scoped API for reading, grading, and tracking sports betslips. No endpoint places wagers or accesses sportsbook credentials." }, "servers": [{ "url": "https://api.betslipdoctor.ai" }], "security": [{ "oauth2": [] }], "paths": { "/api/v1/slips": { "get": { "summary": "Read tracked slips", "operationId": "getTrackedSlips", "security": [{ "oauth2": ["slips.read"] }], "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" } } }, "post": { "summary": "Create or revise a tracked slip", "operationId": "trackSlip", "security": [{ "oauth2": ["slips.track"] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackSlipRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/grade": { "post": { "summary": "Quote, start or cancel a durable Grade job for a confirmed ticket", "operationId": "gradeSlip", "security": [ { "oauth2": [ "slips.grade" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GradeSlipRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/OAuthError" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/OAuthError" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/history": { "get": { "summary": "Read the owner's betting-history summary", "operationId": "getHistorySummary", "security": [{ "oauth2": ["history.read"] }], "parameters": [{ "name": "recent", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20, "default": 5 } }], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" } } } }, "/api/v1/reports": { "get": { "summary": "Read durable Grade jobs, progress, reports and library; unversioned legacy saved reports remain readable", "operationId": "getSavedReports", "security": [ { "oauth2": [ "reports.read" ] } ], "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string", "const": "bsd-agent-grade-v1" } }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "list", "job", "progress", "report" ] } }, { "name": "jobId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum 20 for list, 100 for progress, 25 for unversioned legacy reads." } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "report_id", "in": "query", "schema": { "type": "string", "description": "Unversioned legacy saved reports only." } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Versioned query fields must match AgentReportsRequest exactly. Duplicate and unknown fields are rejected." } }, "/api/v1/board": { "get": { "summary": "Read the current main-market board", "operationId": "getBoard", "security": [{ "oauth2": ["odds.read"] }], "parameters": [ { "name": "league", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" } } } }, "/api/v1/price-shop": { "post": { "summary": "Compare posted prices for slip legs", "operationId": "priceShopSlip", "security": [{ "oauth2": ["odds.read"] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["legs"], "properties": { "legs": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string" }, "odds": { "type": "number" }, "book": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/OAuthError" }, "403": { "$ref": "#/components/responses/OAuthError" } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization code with PKCE. Access tokens expire in 15 minutes.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.betslipdoctor.ai/api/oauth/authorize", "tokenUrl": "https://api.betslipdoctor.ai/api/oauth/token", "scopes": { "slips.read": "Read the owner's tracked slips", "slips.grade": "Grade slips for the owner", "slips.track": "Create and revise the owner's tracked slips", "history.read": "Read the owner's imported betting history", "reports.read": "Read the owner's saved reports", "odds.read": "Read and compare posted odds" } } } } }, "schemas": { "CapturedStatus": { "type": "object", "required": ["raw", "token"], "properties": { "raw": { "type": ["string", "null"] }, "token": { "type": ["string", "null"], "enum": ["Won", "Lost", "Open", "Voided", "Cancelled", "Cashed Out", "Settled", "Early Exit", "Early Exit Win", "Ghost Win", "Push", "Unknown", null] } }, "additionalProperties": false }, "TicketChild": { "type": "object", "required": ["node_id", "printed_terms", "market_family", "price", "status", "participant"], "properties": { "node_id": { "type": "string" }, "printed_terms": { "type": "string" }, "market_family": { "type": ["string", "null"] }, "price": { "type": ["string", "null"] }, "status": { "$ref": "#/components/schemas/CapturedStatus" }, "participant": { "type": ["string", "null"] } }, "additionalProperties": false }, "TicketOuterPick": { "type": "object", "required": ["node_id", "kind", "event_id", "printed_terms", "sport", "league", "market_family", "phase", "price", "status", "children", "modifiers"], "properties": { "node_id": { "type": "string" }, "kind": { "type": "string", "enum": ["single", "sgp"] }, "event_id": { "type": ["string", "null"] }, "printed_terms": { "type": "string" }, "sport": { "type": ["string", "null"] }, "league": { "type": ["string", "null"] }, "market_family": { "type": ["string", "null"] }, "phase": { "type": "string", "enum": ["pre_live", "live", "unknown"] }, "price": { "type": ["string", "null"] }, "status": { "$ref": "#/components/schemas/CapturedStatus" }, "children": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/TicketChild" } }, "modifiers": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "BetTicket": { "type": "object", "required": ["ticket_id", "sportsbook", "source", "captured_at", "placed_at", "jurisdiction", "phase", "product", "stake", "currency", "displayed_odds", "displayed_payout", "pay_table", "raw_slip_text", "outer_picks"], "properties": { "ticket_id": { "type": ["string", "null"] }, "sportsbook": { "type": ["string", "null"] }, "source": { "type": "object", "required": ["kind", "artifact_id", "parser_version"], "properties": { "kind": { "type": "string", "enum": ["screenshot", "manual", "provider"] }, "artifact_id": { "type": ["string", "null"] }, "parser_version": { "type": "string" } }, "additionalProperties": false }, "captured_at": { "type": "string", "format": "date-time" }, "placed_at": { "type": ["string", "null"] }, "jurisdiction": { "type": ["string", "null"] }, "phase": { "type": "string", "enum": ["pre_live", "live", "unknown"] }, "product": { "type": "string", "enum": ["single", "parlay", "sgp", "sgpx", "teaser", "progressive_parlay", "round_robin", "each_way", "unknown"] }, "stake": { "type": ["number", "null"], "minimum": 0 }, "currency": { "type": ["string", "null"] }, "displayed_odds": { "type": ["string", "null"] }, "displayed_payout": { "type": ["number", "null"], "minimum": 0 }, "pay_table": { "type": ["object", "null"], "additionalProperties": { "type": "number", "minimum": 0 } }, "raw_slip_text": { "type": "string" }, "outer_picks": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/TicketOuterPick" } } }, "additionalProperties": false }, "GradeSlipRequest": { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "quote" }, "commandKey": { "type": "string", "minLength": 16, "maxLength": 120, "pattern": "^[a-zA-Z0-9_-]+$" }, "depth": { "type": "string", "enum": [ "fast", "smart", "deep", "elite" ] }, "funding": { "default": "auto", "type": "string", "enum": [ "auto", "weekly", "bug_bounty" ] }, "ticketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "version", "action", "commandKey", "depth", "ticketId" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "quote" }, "commandKey": { "type": "string", "minLength": 16, "maxLength": 120, "pattern": "^[a-zA-Z0-9_-]+$" }, "depth": { "type": "string", "enum": [ "fast", "smart", "deep", "elite" ] }, "funding": { "default": "auto", "type": "string", "enum": [ "auto", "weekly", "bug_bounty" ] }, "ticket": { "type": "object", "properties": { "clientSlipId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "clientRevision": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "parentTicketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "source": { "type": "string", "const": "manual" }, "intent": { "type": "string", "enum": [ "singles", "parlay" ] }, "bookId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "bookLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "stakeMinor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "selections": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "entityId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "provider": { "type": "string", "const": "manual" }, "sport": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "league": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, { "type": "null" } ] }, "market": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, { "type": "null" } ] }, "side": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "line": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,8}(\\.\\d{1,4})?$" }, { "type": "null" } ] }, "label": { "type": "string", "minLength": 1, "maxLength": 300 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "future": { "type": "boolean", "const": true }, "bookId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 32 }, "oddsAmerican": { "type": "integer", "minimum": -1000000, "maximum": 1000000 }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "quoteVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, { "type": "null" } ] } }, "required": [ "id", "eventId", "entityId", "provider", "sport", "league", "market", "period", "side", "line", "label", "startsAt", "bookId", "jurisdiction", "oddsAmerican", "observedAt", "quoteVersion" ], "additionalProperties": false } }, "confirmation": { "type": "string", "const": "exact_fields_confirmed" }, "offeredReturnMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] }, "acceptedReturnMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] }, "settlementTerms": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "provider", "book_document", "user_reported", "unknown" ] }, "cashParlay": { "type": "string", "const": "normal_win_loss" }, "cashSingle": { "type": "string", "const": "win_loss_refund" }, "reference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_.:@/-]+$" }, { "type": "null" } ] }, "pushes": { "type": "string", "enum": [ "refund", "reprice", "lose", "unknown" ] }, "voids": { "type": "string", "enum": [ "refund", "reprice", "unknown" ] } }, "required": [ "source", "reference", "version", "pushes", "voids" ], "additionalProperties": false } }, "required": [ "clientSlipId", "clientRevision", "source", "intent", "bookId", "currency", "stakeMinor", "selections", "confirmation", "offeredReturnMinor", "acceptedReturnMinor", "settlementTerms" ], "additionalProperties": false } }, "required": [ "version", "action", "commandKey", "depth", "ticket" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "start" }, "commandKey": { "type": "string", "minLength": 16, "maxLength": 120, "pattern": "^[a-zA-Z0-9_-]+$" }, "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "version", "action", "commandKey", "quoteId" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "cancel" }, "commandKey": { "type": "string", "minLength": 16, "maxLength": 120, "pattern": "^[a-zA-Z0-9_-]+$" }, "jobId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "version", "action", "commandKey", "jobId" ], "additionalProperties": false } ] }, "AgentReportsRequest": { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "list" }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 20 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "version", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "job" }, "jobId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "version", "action", "jobId" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "report" }, "jobId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "version", "action", "jobId" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "string", "const": "bsd-agent-grade-v1" }, "action": { "type": "string", "const": "progress" }, "jobId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "after": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000000 }, "limit": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "version", "action", "jobId" ], "additionalProperties": false } ] }, "TrackSlipRequest": { "type": "object", "required": ["client_mutation_id", "ticket"], "properties": { "client_mutation_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticket_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1 }, "ticket": { "$ref": "#/components/schemas/BetTicket" } }, "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "Success": { "description": "Owner-scoped result", "content": { "application/json": { "schema": { "type": "object" } } } }, "Error": { "description": "Request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "OAuthError": { "description": "OAuth token, scope, or live entitlement failure", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }