shipp

What this skill does

# Shipp API

[Shipp.ai](https://shipp.ai) is the real-time data connector for AI builders.

[Create an API Key](https://platform.shipp.ai)

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 URL: `https://api.shipp.ai/api/v1`

---

## Sitemap & Documentation Index

If docs change or you need the latest page list, fetch the sitemap:

```
curl -sL "https://markdown.new/docs.shipp.ai/sitemap.xml"
```

To read any doc page as clean markdown:

```
curl -sL "https://markdown.new/docs.shipp.ai/<path>"
```

### Full Sitemap

| Page | markdown.new URL |
|---|---|
| Getting Started | https://markdown.new/docs.shipp.ai/ |
| Setup Instructions | https://markdown.new/docs.shipp.ai/instructions/setup/ |
| Test Your Connection | https://markdown.new/docs.shipp.ai/instructions/test/ |
| Shipp Your Product | https://markdown.new/docs.shipp.ai/instructions/shipp/ |
| How to Shipp | https://markdown.new/docs.shipp.ai/how-to/ |
| API Reference | https://markdown.new/docs.shipp.ai/api-reference/ |
| Create Connection | https://markdown.new/docs.shipp.ai/api-reference/connections-create/ |
| List Connections | https://markdown.new/docs.shipp.ai/api-reference/connections-list/ |
| Run Connection | https://markdown.new/docs.shipp.ai/api-reference/connections-run/ |
| Sport Schedule | https://markdown.new/docs.shipp.ai/api-reference/sport-schedule/ |
| Data Shape | https://markdown.new/docs.shipp.ai/api-reference/connections-run-data-shape/ |
| Error Format | https://markdown.new/docs.shipp.ai/api-reference/error-format/ |
| Usage Tips | https://markdown.new/docs.shipp.ai/api-reference/usage-tips/ |
| Versioning | https://markdown.new/docs.shipp.ai/api-reference/versioning/ |
| x402 Payments | https://markdown.new/docs.shipp.ai/api-reference/x402/ |
| Platform Guides | https://markdown.new/docs.shipp.ai/platform-guides/ |
| Lovable Guide | https://markdown.new/docs.shipp.ai/platform-guides/lovable/ |
| Base44 Guide | https://markdown.new/docs.shipp.ai/platform-guides/base44/ |
| Claude Code Guide | https://markdown.new/docs.shipp.ai/platform-guides/claude-code/ |
| Blink Guide | https://markdown.new/docs.shipp.ai/platform-guides/blink/ |
| Replit Guide | https://markdown.new/docs.shipp.ai/platform-guides/replit/ |

---

## Getting Started

Shipp enables a faster way to create connections to real-time data. It's cost-effective, fast to run, and easy to start.

1. Sign up on [Shipp](https://platform.shipp.ai)
2. Paste your API key into your favorite AI builder. See [Platform Guides](https://markdown.new/docs.shipp.ai/platform-guides/)
3. Shipp works with your AI builder to provide the live data your app needs

Following the instructions ([Setup](https://markdown.new/docs.shipp.ai/instructions/setup/), [Test](https://markdown.new/docs.shipp.ai/instructions/test/), [Shipp](https://markdown.new/docs.shipp.ai/instructions/shipp/)) is the best way to create your first Connection.

### Available Data

- **Sports:** NBA, NFL, NCAA Football, MLB, Soccer (Multiple Leagues)
- News, Financials, Travel, Shopping, Social, Prediction Markets, Weather — coming soon

---

## Authentication

All endpoints require an API key. The API supports several methods:

| 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

### `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.

**Request body:**

```json
{
  "filter_instructions": "string (required)"
}
```

**Response (200):**

```json
{
  "connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
  "enabled": true,
  "name": "string",
  "description": "string"
}
```

**Errors:** 400 (invalid JSON, empty body, missing `filter_instructions`), 500

Use at build time — there is time and credit overhead. Store and reuse the returned `connection_id`.

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/connections-create/)

---

### `POST /api/v1/connections/{connection_id}`

Run a connection and return **raw event data**.

**Path params:** `connection_id` (required, ULID)

**Body params (all optional):**

- `since` (string, ISO 8601): reference time to pull from. Default: 48 hours ago
- `limit` (int): max events to return. Default: 100
- `since_event_id` (ULID): last event id received — only returns newer events. Causes events to be ordered asc by `wall_clock_start`

**Response (200):**

```json
{
  "connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
  "data": [
    { "any": "shape varies by feed + event data availability" }
  ]
}
```

**Errors:** 400 (missing/invalid `connection_id`, over limit / not authorized), 500

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/connections-run/)

---

### `GET /api/v1/connections`

List all connections in the current org scope. Free to call.

**Response (200):**

```json
{
  "connections": [
    {
      "connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
      "enabled": true,
      "name": "string (optional)",
      "description": "string (optional)"
    }
  ]
}
```

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/connections-list/)

---

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

Get upcoming and recent games (past 24 hours through next 7 days).

**Path params:** `sport` (required) — e.g. `nba`, `nfl`, `mlb`, `ncaafb`, `soccer` (case-insensitive)

**Response (200):**

```json
{
  "schedule": [
    {
      "sport": "Soccer",
      "game_status": "live",
      "game_id": "01KGREKH8PXFV8AHA4Q9H2Z68F",
      "scheduled": "2026-02-06T15:00:00Z",
      "home": "Al-Ittifaq FC",
      "home_team_players": null,
      "away": "Damac FC",
      "away_team_players": null
    }
  ]
}
```

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/sport-schedule/)

---

### `POST /api/v1/connections/inline` (x402)

Create and run a connection in one step, paid via x402 — **no API key required**. Requires a crypto wallet funded with USDC on Base.

**Body params:**

- `filter_instructions` (string, required)
- `since` (string, ISO 8601, optional)
- `limit` (int, optional)
- `since_event_id` (ULID, optional)

**Flow:**

1. Agent sends request — gets `402 Payment Required` with pricing details
2. Agent signs payment with funded wallet
3. Agent retries with `PAYMENT-SIGNATURE` header
4. Server returns data (same shape as Run Connection)

Use an x402-compatible library (`x402-fetch`, Coinbase SDK) to handle the 402 → pay → retry loop automatically.

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/x402/)

---

## Data Shape

Each element of `data[]` is a schema-flexible JSON object. Fields vary by sport, feed, and event.

**Identifiers:** `game_id`, `home_id`, `away_id`, `attribution_id`, `posession_id`

**Text / enums:** `sport`, `home_name`, `away_name`, `game_clock`, `game_period_sub`, `desc`, `type`, `category`, `score_method`, `score_missed_outcome`

**Numeric:** `home_points`, `away_points`, `game_period`, `game_num`, `down`, `yards_first_down`, `location_yard_line`, `injury_time_minutes`

**Time:** `wall_clock_start`, `wall_clock_end`

**Booleans:** `fake_punt`, `fake_field_goal`, `screen_pass`, `play_action`, `run_pass_options`

Not every row has every field. Treat every field as optional. Agents and clients should be defensive and handle missing keys.

> [Full docs](https://markdown.new/docs.shipp.ai/api-reference/connections-run-data-s