Shipp API

Shipp.ai is the definitive source on real-time data.

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:

Resource	URL
Full documentation	https://docs.shipp.ai
How-to guides	https://docs.shipp.ai/how-to/
Setup instructions	https://docs.shipp.ai/instructions/setup/
API reference	https://docs.shipp.ai/api-reference/
Dashboard / Signup	https://platform.shipp.ai/signup
Billing management	https://platform.shipp.ai/billing

Authentication

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

Method	Example
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

Status	Meaning
400	Invalid request — check JSON and required fields
401	Missing or invalid API key
402	Billing changes required — manage at https://platform.shipp.ai/billing
403	API key lacks access to this resource
404	Connection not found or doesn't belong to your org
429	Rate-limited — retry with backoff
5xx	Server 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:

User promise — what must stay accurate while the user (or agent) is watching?
Triggering events — what changes should cause UI updates or agent actions?
Data shape needed — what fields do you need to render or decide?
Freshness window — how old can the last update be before you warn the user?
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

Game discovery — Uses
```
GET /api/v1/sports/{sport}/schedule
```
to list available games:
Connection creation — Creates a Shipp connection for a specific game, describing what events to track via
```
filter_instructions
```
.
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.
AI analysis — Feeds the schema-flexible
```
data[]
```
events directly to Claude AI, which analyzes game state and estimates outcome probabilities.
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.

shipp

NPX Install

Tags

SKILL.md Content

Shipp API

Documentation & References

Authentication

Endpoints Overview

`POST /api/v1/connections/create`

`POST /api/v1/connections/{connectionId}`

`GET /api/v1/connections`

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

Data Shape

Error Format

Response Compression

Usage Tips

Integration Pattern: "Real-Time Contract"

Example Project: Alph Bot

How Alph Bot Uses Shipp

Key Takeaways from Alph Bot

Versioning