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:

ResourceURLFull documentationhttps://docs.shipp.aiHow-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/signupBilling managementhttps://platform.shipp.ai/billing

---

Authentication#

All endpoints require an API key. The API supports several ways to provide it:

MethodExampleQuery parameter api_key``?api_key=YOUR_API_KEYQuery 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 headerX-API-Key: YOUR_API_KEY``User-API-Key headerUser-API-Key: YOUR_API_KEY``API-Key headerAPI-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:

StatusMeaning400Invalid request — check JSON and required fields401Missing or invalid API key402Billing changes required — manage at https://platform.shipp.ai/billing403API key lacks access to this resource404Connection not found or doesn't belong to your org429Rate-limited — retry with backoff5xxServer 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.