{"openapi":"3.1.0","info":{"title":"Pickpockt Publisher API","version":"1.0.0","summary":"Record model predictions against upcoming events. Private by default; published when the account is approved as a capper.","description":"Any account can create a key and record predictions immediately; they are visible only to the owner until the account is approved as a capper, at which point the whole record is published. Predictions are permanent either way: they cannot be edited or deleted through this API or through Capper Studio, so never record test data to a real account.\n\nFull integration guide for coding agents: https://pickpockt.com/developers/llms.txt"},"servers":[{"url":"https://pickpockt.com/api/publisher/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key created in Capper Studio, of the form ppk_ followed by 43 URL-safe base64 characters. Supply it from the environment; never hardcode or log it."}},"schemas":{"Pick":{"type":"object","additionalProperties":false,"required":["externalId","eventId","market","selection","predictedPrice"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Your stable identifier for this prediction; the idempotency key. Must be deterministic — derive it from the prediction's identity, never from a run id or timestamp."},"eventId":{"type":"string","format":"uuid","description":"Event id from GET /events. Never construct or guess one."},"market":{"type":"string","enum":["moneyline","spread","total","total_rounds","total_sets","total_games","goes_the_distance"],"description":"Must appear in the target event's allowedMarkets, which vary by sport."},"selection":{"type":"string","enum":["home","away","over","under","yes","no"],"description":"moneyline/spread use home|away; totals use over|under; goes_the_distance uses yes|no."},"predictedPrice":{"type":"integer","minimum":-1000000,"maximum":1000000,"description":"The model's fair American odds, not a sportsbook price. Absolute value must be at least 100."},"line":{"type":["number","null"],"minimum":-1000,"maximum":1000,"description":"Required for spread, total, total_rounds, total_sets, total_games. Must be null/omitted for moneyline and goes_the_distance. Totals must be positive."},"competitorId":{"type":["string","null"],"format":"uuid","description":"Required only for total_games; must be one of the event's competitors. Omit for all other markets."},"confidence":{"type":["integer","null"],"minimum":0,"maximum":100},"isPick":{"type":"boolean","default":true,"description":"Whether to feature this prediction as a pick."}}}}},"paths":{"/me":{"get":{"operationId":"getAccount","summary":"Confirm the key, and see whether this account's record is private or public.","responses":{"200":{"description":"Account and granted scopes","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"predictorId":{"type":"string","format":"uuid"},"slug":{"type":["string","null"],"description":"Null while the record is private; there is no public page yet."},"displayName":{"type":"string"},"visibility":{"type":"string","enum":["private","public"],"description":"private: recorded and immutable, owner-only. public: also shown on the profile."},"profileUrl":{"type":["string","null"],"description":"The public profile, or null while private. Do not construct this yourself."}}},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"Publishable events: scheduled status, starting in the future.","parameters":[{"name":"sport","in":"query","schema":{"type":"string","enum":["nfl","nba","mlb","cfb","ufc","atp","wta"]}},{"name":"from","in":"query","description":"Inclusive ISO 8601 timestamp with offset.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Exclusive ISO 8601 timestamp with offset.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of events. Follow nextOffset until it is null.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalRef":{"type":"string"},"name":{"type":["string","null"],"description":"Upstream display text with an inconsistent shape across feeds. Show it to a human; do not parse it to identify sides. Use homeCompetitor/awayCompetitor instead."},"sport":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"homeCompetitorId":{"type":["string","null"],"format":"uuid"},"awayCompetitorId":{"type":["string","null"],"format":"uuid"},"homeCompetitor":{"type":["object","null"],"description":"Resolved home side, for matching your pipeline's output to this event.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"shortName":{"type":["string","null"]},"abbreviation":{"type":["string","null"]}}},"awayCompetitor":{"type":["object","null"],"description":"Resolved away side.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"shortName":{"type":["string","null"]},"abbreviation":{"type":["string","null"]}}},"allowedMarkets":{"type":"array","items":{"type":"string"},"description":"Authoritative list of markets this event accepts."}}}},"nextOffset":{"type":["integer","null"]}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}}}}},"/picks":{"get":{"operationId":"listPicks","summary":"Predictions this account published through the API.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of published picks"},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}}}},"post":{"operationId":"publishPicks","summary":"Publish 1-100 predictions atomically.","description":"One transaction: if any pick fails, none of the new picks are published — fix the payload and resend the whole batch with the same external ids. An identical retry returns the original receipts with status \"existing\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["picks"],"properties":{"picks":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/Pick"}}}}}}},"responses":{"200":{"description":"Every prediction already existed; nothing created"},"201":{"description":"At least one prediction was created","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"predictionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","existing"]},"publishedAt":{"type":["string","null"],"format":"date-time"}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"415":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","description":"Present on VALIDATION_ERROR; Zod issues.","items":{"type":"object"}}}}}}}}}}}}}}