{"openapi":"3.1.0","info":{"title":"Craque API","version":"0.1.0","description":"Brazilian football (Cartola FC) reference: market status, clubs, player search and stats, club squads, top players, value picks, fixtures, round schedule, and a budget lineup builder.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://craque.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/craque/docs"},"termsOfService":"https://connectorbay.com/craque/terms"},"servers":[{"url":"https://craque.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/craque/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/market_status":{"post":{"operationId":"market_status","summary":"Current round number, whether the Cartola FC transfer market is open or closed, when it closes, and the","description":"Current round number, whether the Cartola FC transfer market is open or closed, when it closes, and the\n    position/status code reference. Use for \"is the market open\", \"what round are we in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"market_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/clubs":{"post":{"operationId":"clubs","summary":"Every club in the current Cartola FC season, with shield images. Use for \"list the clubs\", to get a club id","description":"Every club in the current Cartola FC season, with shield images. Use for \"list the clubs\", to get a club id\n    for other tools.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"clubsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/player_search":{"post":{"operationId":"player_search","summary":"Search players by name. Optionally filter by position or club. Use for \"find Pedro\", \"midfielders named","description":"Search players by name. Optionally filter by position or club. Use for \"find Pedro\", \"midfielders named\n    Gabriel at Palmeiras\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Name or nickname substring.","examples":["pedro","gerson","veiga"],"minLength":2,"title":"Query","type":"string"},"position":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: goleiro, lateral, zagueiro, meia, atacante, técnico.","title":"Position"},"club":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by club name/abbreviation.","title":"Club"},"limit":{"default":15,"maximum":50,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"player_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/player_info":{"post":{"operationId":"player_info","summary":"Full detail for one player: club, position, price, season average, last round's points, price variation,","description":"Full detail for one player: club, position, price, season average, last round's points, price variation,\n    status and this round's scout (tackles, shots, fouls, etc). Use for \"how is Gerson doing\", \"what does player\n    12345 cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Cartola atleta_id, if known.","title":"Player Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Exact or near-exact name/nickname, if id unknown.","title":"Name"}},"title":"player_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/club_squad":{"post":{"operationId":"club_squad","summary":"A club's full squad currently in the market, with price/average/status, optionally filtered by position. Use","description":"A club's full squad currently in the market, with price/average/status, optionally filtered by position. Use\n    for \"Palmeiras squad\", \"Flamengo's midfielders\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"club":{"description":"Club name or abbreviation.","examples":["Flamengo","PAL","São Paulo"],"title":"Club","type":"string"},"position":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: goleiro, lateral, zagueiro, meia, atacante, técnico.","title":"Position"}},"required":["club"],"title":"club_squadArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/top_players":{"post":{"operationId":"top_players","summary":"The best players by season average points or by last round's points, optionally filtered by position or club.","description":"The best players by season average points or by last round's points, optionally filtered by position or club.\n    Use for \"top scorers this season\", \"best forwards last round\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"position":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"goleiro, lateral, zagueiro, meia, atacante, técnico — omit for all.","title":"Position"},"club":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by club.","title":"Club"},"sort_by":{"default":"season_average","description":"season_average | last_round","title":"Sort By","type":"string"},"limit":{"default":10,"maximum":50,"minimum":1,"title":"Limit","type":"integer"}},"title":"top_playersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/value_picks":{"post":{"operationId":"value_picks","summary":"Best price-performance players — season average points divided by price in cartoletas — the \"who's a bargain","description":"Best price-performance players — season average points divided by price in cartoletas — the \"who's a bargain\n    right now\" scouting tool. Use for \"best value midfielders under 10 cartoletas\", \"cheap defenders worth\n    starting\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"position":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"goleiro, lateral, zagueiro, meia, atacante, técnico — omit for all.","title":"Position"},"max_price":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Cartoletas ceiling.","title":"Max Price"},"min_games":{"default":3,"maximum":38,"minimum":0,"title":"Min Games","type":"integer"},"safe_only":{"default":true,"description":"Exclude dúvida/suspenso/contundido players.","title":"Safe Only","type":"boolean"},"limit":{"default":15,"maximum":50,"minimum":1,"title":"Limit","type":"integer"}},"title":"value_picksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/round_matches":{"post":{"operationId":"round_matches","summary":"Fixtures for a round: home/away clubs, kickoff time, venue, and the official score once the match is final.","description":"Fixtures for a round: home/away clubs, kickoff time, venue, and the official score once the match is final.\n    Use for \"who's playing this round\", \"results from round 5\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"round_number":{"anyOf":[{"maximum":38,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Omit for the current round.","title":"Round Number"}},"title":"round_matchesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/rounds_schedule":{"post":{"operationId":"rounds_schedule","summary":"The full season's round-by-round schedule with start/end datetimes. Use for \"when does round 20 start\",","description":"The full season's round-by-round schedule with start/end datetimes. Use for \"when does round 20 start\",\n    \"how many rounds are left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"rounds_scheduleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/lineup_builder":{"post":{"operationId":"lineup_builder","summary":"Suggest a starting lineup for a formation and cartoletas budget: greedily picks the highest season-average","description":"Suggest a starting lineup for a formation and cartoletas budget: greedily picks the highest season-average\n    player available at each position slot (goalkeeper, defence, midfield, attack, coach) without exceeding the\n    budget. A heuristic scouting suggestion, not a guaranteed-optimal combination. Use for \"build me a 4-3-3 with\n    100 cartoletas\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"formation":{"default":"4-3-3","description":"One of: 3-4-3, 3-5-2, 4-3-3, 4-4-2, 4-5-1, 5-3-2, 5-4-1","examples":["4-3-3","3-5-2"],"title":"Formation","type":"string"},"budget":{"default":100.0,"description":"Cartoletas available (Cartola starts everyone at 100).","exclusiveMinimum":0,"maximum":300,"title":"Budget","type":"number"},"safe_only":{"default":true,"description":"Exclude dúvida/suspenso/contundido players.","title":"Safe Only","type":"boolean"}},"title":"lineup_builderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}