shipp

Original：🇺🇸 English
Translated

Shipp is a real-time data connector. Use it to fetch authoritative, changing external data (e.g., sports schedules, live events) via the Shipp API.

9installs
Sourceoutsharp/shipp-skills
Added on

NPX Install

npx skill4agent add outsharp/shipp-skills shipp

Tags

Translated version includes tags in frontmatter
real-time-datashipp-apisports-datadata-connectorapi-integration

SKILL.md Content

View Translation Comparison →

Shipp API

Shipp.ai is the definitive source on real-time data.
Create an API Key
Reference docs.
Implement as many tests as possible as soon as possible. Verify data and how the app uses data. Be flexible in schema — event rows are schema-flexible JSON and fields vary by sport, feed, and event.
Base prefix:
  • All routes are under: 
    https://api.shipp.ai/api/v1

Documentation & References

All detailed examples, request/response schemas, and walkthroughs live in the official docs. Always consult these before building:
ResourceURL
Full documentationhttps://docs.shipp.ai
How-to guideshttps://docs.shipp.ai/how-to/
Setup instructionshttps://docs.shipp.ai/instructions/setup/
API referencehttps://docs.shipp.ai/api-reference/
Dashboard / Signuphttps://platform.shipp.ai/signup
Billing managementhttps://platform.shipp.ai/billing

Authentication

All endpoints require an API key. The API supports several ways to provide it:
MethodExample
Query parameter 
api_key
?api_key=YOUR_API_KEY
Query parameter 
apikey
?apikey=YOUR_API_KEY
Authorization
header (Bearer)
Authorization: Bearer YOUR_API_KEY
Authorization
header (Basic)
Authorization: Basic base64(:YOUR_API_KEY)
X-API-Key
header
X-API-Key: YOUR_API_KEY
User-API-Key
header
User-API-Key: YOUR_API_KEY
API-Key
header
API-Key: YOUR_API_KEY
Pick whichever method works best for your client.

Endpoints Overview

Below is a summary of the available endpoints. For full request/response examples, schemas, and field descriptions see the API reference.

POST /api/v1/connections/create

Create a new raw-data connection by providing natural-language 
filter_instructions
that describe what games, teams, sports, or events you want to track.
Returns a 
connection_id
(ULID) you'll reuse for all subsequent runs.
→ Full docs & examples

POST /api/v1/connections/{connectionId}

Run a connection and receive raw event data.
Supports optional body fields for time-based filtering (
since
), cursor-based pagination (
since_event_id
), and result limiting (
limit
).
→ Full docs & examples

GET /api/v1/connections

List all connections in the current org scope.
→ Full docs & examples

GET /api/v1/sports/{sport}/schedule

Retrieve upcoming and recent games for a given sport (past 24 hours through next 7 days).
Supported sport values: 
nba
, 
nfl
, 
mlb
, 
ncaafb
, 
soccer
(case-insensitive).
→ Full docs & examples

Data Shape

Event rows returned in 
data[]
are schema-flexible JSON objects. Fields vary by sport, feed, and event. Common field categories include:
  • IDs: 
    game_id
    , 
    home_id
    , 
    away_id
    , 
    attribution_id
    , 
    posession_id
  • Text / enums: 
    sport
    , 
    home_name
    , 
    away_name
    , 
    game_clock
    , 
    desc
    , 
    type
    , 
    category
  • Numeric: 
    home_points
    , 
    away_points
    , 
    game_period
    , 
    down
    , 
    yards_first_down
    , 
    location_yard_line
  • Time: 
    wall_clock_start
    , 
    wall_clock_end
Not every row has every field. Agents and clients should be defensive and handle missing keys.
For the complete field reference see docs.shipp.ai.

Error Format

Errors are returned as JSON with an 
error
message, HTTP 
status
code, and a 
hint
:
StatusMeaning
400Invalid request — check JSON and required fields
401Missing or invalid API key
402Billing changes required — manage at https://platform.shipp.ai/billing
403API key lacks access to this resource
404Connection not found or doesn't belong to your org
429Rate-limited — retry with backoff
5xxServer error — retry later or contact support@shipp.ai

Response Compression

Include an 
Accept-Encoding
header to receive compressed responses (
zstd
, 
gzip
, or 
deflate
). Compression is applied automatically when the response body exceeds 1 KB.

Usage Tips

  • Keep 
    filter_instructions
    short, explicit, and testable. Mention the sport/league and scope.
  • Store and reuse 
    connection_id
    — don't create a new connection per run. Creating connections has time and credit overhead.
  • Use 
    since_event_id
    for efficient polling (cursor-based pagination). Send the lexicographically largest event ID you've received.
  • Use the schedule endpoint to discover 
    game_id
    s and team names before creating connections.
  • Surface error 
    hint
    messages directly to users when limits are hit.
  • Treat every field in 
    data[]
    as optional — use existence checks and graceful fallbacks.
  • Log unknown data shapes in development so you can refine 
    filter_instructions
    .
  • Polling interval: 5–30 seconds depending on domain and cost sensitivity.
  • Deduplicate events by keeping a rolling set of seen event IDs.
  • Consult the how-to guides for end-to-end integration walkthroughs.

Integration Pattern: "Real-Time Contract"

When building a feature powered by Shipp, define a contract for each screen or agent loop:
  1. User promise — what must stay accurate while the user (or agent) is watching?
  2. Triggering events — what changes should cause UI updates or agent actions?
  3. Data shape needed — what fields do you need to render or decide?
  4. Freshness window — how old can the last update be before you warn the user?
  5. Failure mode — what do you show/do if updates stop arriving?
Then translate the contract into 
filter_instructions
when creating the connection.

Example Project: Alph Bot

Alph Bot is an open-source automated trading bot that uses Shipp for real-time sports data and trades on prediction markets. It demonstrates a production-quality integration of the Shipp API.

How Alph Bot Uses Shipp

  1. Game discovery — Uses 
    GET /api/v1/sports/{sport}/schedule
    to list available games:
  2. Connection creation — Creates a Shipp connection for a specific game, describing what events to track via 
    filter_instructions
    .
  3. Live polling — Runs the connection on an interval, using 
    since_event_id
    for cursor-based pagination to receive only new events since the last poll.
  4. AI analysis — Feeds the schema-flexible 
    data[]
    events directly to Claude AI, which analyzes game state and estimates outcome probabilities.
  5. Trading decisions — Compares AI-estimated probabilities against Kalshi market prices to find value bets.

Key Takeaways from Alph Bot

  • Reuse connections — Alph Bot creates a connection once and polls it repeatedly, avoiding unnecessary creation overhead.
  • Cursor pagination — Uses 
    since_event_id
    so each poll only returns new events, keeping responses fast and costs low.
  • Defensive data handling — Treats all fields as optional since the data shape varies by sport, game phase, and event type.
  • Schedule-first workflow — Discovers game IDs via the schedule endpoint before creating targeted connections.
See the Alph Bot README for full setup instructions.

Versioning

This API is versioned under 
/api/v1/
. New versions will be introduced under a new prefix when breaking changes are required.