Partner API · v1

API Documentation

Everything an approved partner needs to show our picks, results and track record on their own site or app. JSON over HTTPS, one API key, four endpoints.

Jump to

Overview

The Picks API gives approved partners our picks, graded results and track record, so you can present them under your own brand. Responses carry no YourSwami branding.

Base URL	`https://yourswami.com/api/v1`
Format	JSON over HTTPS. All times are UTC ISO 8601; dates are YYYY-MM-DD.
Authentication	Your API key in a request header.
Endpoints	`GET /picks` `GET /results` `GET /record` `GET /me`
Versioning	Within v1 we only add fields; we never remove or rename one. A breaking change would come as /v2, with notice.

Quick start

Get today's picks in one request. Replace YOUR_API_KEY with the key you were issued.

cURL

curl "https://yourswami.com/api/v1/picks?date=2026-09-19" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

Send your key with every request, in either header:

Headers

Authorization: Bearer YOUR_API_KEY

# or
X-API-Key: YOUR_API_KEY

Keep the key on your server. A key placed in a web page or a mobile app can be copied by anyone who looks. If a key may have leaked, contact us: we revoke it at once and issue a new one.

GET /picks

GET/api/v1/picks

Picks in your agreement. With a date, every pick whose game is on that day, graded ones included. Without a date, what is current right now: picks announced but not yet dropped, and dropped picks until a few hours after the game starts.

Parameter	Example	Description
`date`	`2026-09-19`	Optional. The Eastern-time game day.
`league`	`MLB`	Optional. One league in your agreement.

Request

curl "https://yourswami.com/api/v1/picks?date=2026-09-19" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "date": "2026-09-19",
  "picks": [ { ...pick object... } ],
  "generated_at": "2026-09-19T18:00:00.000Z"
}

GET /results

GET/api/v1/results

Graded picks and how they came through, with a won-lost summary. The results for a day are exactly the picks /picks lists for that day.

Parameter	Example	Description
`date`	`2026-09-18`	One day. Defaults to today (Eastern time).
`from, to`	`2026-09-01`	A range of up to 31 days, used instead of date. Send both.
`league`	`NFL`	Optional. One league in your agreement.

Request

curl "https://yourswami.com/api/v1/results?date=2026-09-18" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "from": "2026-09-18",
  "to": "2026-09-18",
  "summary": {
    "record": "1-1", "wins": 1, "losses": 1, "pushes": 0,
    "win_pct": 50, "units": -0.27, "roi": -4.5, "streak": "W1"
  },
  "picks": [
    {
      "matchup": "Houston Cougars @ Texas Tech Red Raiders",
      "game_date": "2026-09-18",
      "status": "won",
      "play": { "team": "Houston Cougars", "selection": "Over 52.5", "market": "Total", "odds": "-110" },
      "...": "every other pick object field"
    },
    {
      "matchup": "Houston Cougars @ Texas Tech Red Raiders",
      "game_date": "2026-09-18",
      "status": "lost",
      "play": { "team": "Texas Tech Red Raiders", "selection": "Texas Tech Red Raiders -7.5 (-115)", "market": "Spread", "odds": "-115" },
      "...": "every other pick object field"
    }
  ]
}

GET /record

GET/api/v1/record

The won-lost-push record and current streak over the picks in your agreement, overall and per league. Units are net units at the posted price (a pick posted without a price is counted at -110).

Parameter	Example	Description
`league`	`NFL`	Optional. One league in your agreement.

Request

curl "https://yourswami.com/api/v1/record" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "overall": {
    "record": "212-98-1", "wins": 212, "losses": 98, "pushes": 1,
    "win_pct": 68.4, "units": 301.5, "roi": 32.1, "streak": "W3"
  },
  "by_league": [
    { "league": "MLB", "league_name": "MLB", "record": "190-86", "...": "same fields as overall" },
    { "league": "NFL", "league_name": "NFL", "record": "3-2-1", "...": "same fields as overall" }
  ],
  "since": "2026-04-01",
  "generated_at": "2026-09-19T18:00:00.000Z"
}

GET /me

GET/api/v1/me

Your account and what your key unlocks. Useful for checking a new integration and your access end date.

Request

curl "https://yourswami.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "partner": { "id": "7a2c...", "name": "Your Company" },
  "access": {
    "sports": ["baseball", "football", "basketball", "hockey"],
    "leagues": ["MLB", "NFL", "NCAAF", "NBA", "NCAAB", "NHL"],
    "lock_of_the_day": true,
    "analysis": true,
    "delay_minutes": 0,
    "rate_limit_per_minute": 60,
    "access_ends_at": "2027-09-19T23:59:00.000Z"
  },
  "key": { "prefix": "ysk_live_Ab3x", "expires_at": null }
}

The pick object

Every endpoint that returns picks returns them in this shape.

An open pick with its play

{
  "id": "0b1f6c2e-7d4a-4f1e-9c3b-5a8e2d1f4c90",
  "league": "NCAAF",
  "league_name": "College Football",
  "matchup": "Kansas Jayhawks @ Arizona State Sun Devils",
  "away_team": "Kansas Jayhawks",
  "home_team": "Arizona State Sun Devils",
  "game_starts_at": "2026-09-19T16:00:00+00:00",
  "game_date": "2026-09-19",
  "drops_at": "2026-09-19T13:05:00.000Z",
  "status": "open",
  "is_lock": false,
  "confidence": 90,
  "units": 3,
  "locked": false,
  "play_available_at": "2026-09-19T13:05:40.000Z",
  "play": {
    "team": "Kansas Jayhawks",
    "selection": "Kansas Jayhawks +5.5 (-112)",
    "market": "Spread",
    "odds": "-112"
  },
  "analysis": "Written reasoning for the pick (only if your agreement includes analysis)."
}

A pick whose play is not released yet

{
  "id": "5c7e0a13-2b8f-4d6a-a1e4-9f3c7b2d8e61",
  "league": "MLB",
  "league_name": "MLB",
  "matchup": "Chicago Cubs @ Arizona Diamondbacks",
  "away_team": "Chicago Cubs",
  "home_team": "Arizona Diamondbacks",
  "game_starts_at": "2026-09-19T23:40:00+00:00",
  "game_date": "2026-09-19",
  "drops_at": "2026-09-19T20:00:00.000Z",
  "status": "upcoming",
  "is_lock": false,
  "confidence": 88,
  "units": 3,
  "locked": true,
  "play_available_at": null,
  "play": null
}

Field	Meaning
`id`	Stable identifier. Use it to de-duplicate and to match a pick with its result later.
`league / league_name`	NFL, NCAAF, NBA, NCAAB, MLB or NHL, and its display name.
`matchup`	Full team names as "Away @ Home".
`away_team / home_team`	Full team names, null if they cannot be read from the matchup.
`game_starts_at`	Kickoff or first pitch (UTC), null when unknown.
`game_date`	The Eastern-time day of the game. This is what ?date= matches.
`drops_at`	When the pick is released. Before this time the pick is a preview.
`status`	upcoming (not dropped yet), open (dropped, not graded), won, lost or push.
`is_lock`	True for the Lock of the Day (only in agreements that include it).
`confidence / units`	Confidence percentage and suggested units.
`locked`	True while the play is not yet released to you. play is then null.
`play_available_at`	When the play unlocks for you, once that is known.
`play.team`	The team the pick is on (for totals, the team as posted).
`play.selection`	The pick exactly as posted, line and price included, for example "Chicago Cubs RL +1.5 (-140)". Never reformatted.
`play.market`	ML (moneyline), RL (run line), Spread, Total (over/under), F5 (first 5 innings) or Prop.
`play.odds`	American odds as posted, for example "-112". Null when none was posted.
`analysis`	Written reasoning. Present only if your agreement includes analysis; null while locked.

When a play unlocks

A pick can be announced before its play is released. Until the play is released to you, the pick comes back with locked: true and play: null, carrying the matchup, game time, confidence and units, so you can show a preview.

The play unlocks when our members are alerted, plus any delay set in your agreement. play_available_at tells you when, once that is known. Graded picks are always unlocked. Poll /picks about once a minute around drop times to pick plays up promptly.

Dates and leagues

A pick's date is the Eastern-time day its game is played, returned as game_date. A pick posted on Thursday for a Saturday game is listed under Saturday. Picks stored without a game time use the day they were released.

Leagues: NFL NCAAF NBA NCAAB MLB NHL. The league parameter is not case sensitive.

Errors

Errors use standard HTTP status codes and always have this body:

Error body

{
  "error": {
    "code": "invalid_key",
    "message": "This API key is not valid."
  }
}

Status	Code	Meaning
400	`invalid_date`	A date is not YYYY-MM-DD, or a /results range is wrong (from after to, over 31 days, or date mixed with from/to).
400	`invalid_league`	Unknown league, or a league your agreement does not include.
401	`missing_key`	No API key was sent, or it is not in the expected format.
401	`invalid_key`	The key does not exist.
401	`revoked`	The key has been revoked. Ask your account manager for a new one.
401	`key_expired`	The key passed its end date.
403	`suspended`	Your account is paused. Contact your account manager.
403	`access_ended`	Your access period has ended. Contact your account manager to renew.
429	`rate_limited`	Too many requests. Wait the number of seconds in the Retry-After header.
503	`unavailable`	Temporary problem on our side. Retry shortly.

Rate limits

Each key has a per-minute limit, 60 requests by default (see GET /me). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with a Retry-After header in seconds.

Best practices

Call the API from your server and cache the answer for your visitors; do not call it from their browsers.
Use id to de-duplicate picks and to match each pick with its result.
Show play.selection as it is; it is the pick exactly as posted, line and price included.
Show game_starts_at in your audience's time zone.
Ignore fields you do not use. New fields may appear within v1.
On 429 or 503, wait and retry; never retry in a tight loop.

Getting access

The API is available to approved partners under a partner agreement. To request access, email support@yourswami.com. Your account manager issues your key and sets which sports and add-ons it includes.

Picks are provided for entertainment and information, for adults 21 and over where sports wagering is legal. Partners show their own responsible gaming notice, send any text messages under their own registration, and do not resell picks to other businesses. The partner agreement governs; see also our Terms of Service.