Title: How to Shipp?

URL Source: https://docs.shipp.ai/how-to/

Markdown Content:
---
description: Creating Modern Applications with Shipp
---

[ Skip to content](#real-time-data-is-pivotal-in-every-app) 

* [  How to Shipp ](./)
* [  API Reference ](../api-reference/)
* [  Guides ](../platform-guides/)
* [  Go To Shipp Dashboard ](https://platform.shipp.ai)

* [  Who this document is for ](#who-this-document-is-for)
* [  The mental model: Shipp “Connections” = reusable live-data queries ](#the-mental-model-shipp-connections-reusable-live-data-queries)
* [  How to build ](#how-to-build)
* [  Step 3 — Create a Connection once, store the connection\_id ](#step-3-create-a-connection-once-store-the-connection%5Fid)
* [  Step 4 — Run the Connection to fetch updates ](#step-4-run-the-connection-to-fetch-updates)
* [  Step 5 — Handle schema-flexible data\[\] defensively ](#step-5-handle-schema-flexible-data-defensively)
* [  Step 6 — Deduplicate, order, and reconcile ](#step-6-deduplicate-order-and-reconcile)
* [  Sports-specific helper ](#sports-specific-helper)
* [  What “good” looks like (business value checklist) ](#what-good-looks-like-business-value-checklist)
* [  Agent-friendly implementation prompt ](#agent-friendly-implementation-prompt)
* [  Next steps ](#next-steps)

# How to Shipp?

## Real-time data is pivotal in every app[¶](#real-time-data-is-pivotal-in-every-app "Permanent link")

Every industry has its own vocabulary (Entertainment, Financial, Logistics, Scheduling, Security, Insurance) but the underlying product requirements are the same:

1. **Users make decisions in the present**
2. The app must reflect **what’s true right now** (availability, status, risk, progress, market movement)
3. The app must update that truth as **the world changes**

That “truth right now” is real-time data.

If you’re building with AI (agents, copilots, workflows, vibecoding), real-time data matters even more: an agent can generate UI and logic quickly, but **without fresh data** the app becomes untrustworthy. A great demo but fragile product.

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

### Does this apply to me?[¶](#does-this-apply-to-me "Permanent link")

Real-time data is the foundation for:

* **Commerce:** inventory changes, price updates, order status, delivery ETAs
* **Travel & hospitality:** availability, delays, cancellations, rebooking options
* **Finance:** quotes, filings, transactions, fraud/risk signals, portfolio changes
* **Operations & logistics:** scans, routing changes, exceptions, SLA breaches
* **Healthcare:** appointment openings, lab result statuses, care coordination events
* **Security:** alerts, detections, posture changes, incident timelines
* **Media & communities:** trending, engagement spikes, moderation events

In all of these, users want answers that stay correct as the world changes. Not last year's trending topics or yesterday's market shock.

### What does Shipp do for me?[¶](#what-does-shipp-do-for-me "Permanent link")

**Shipp is the real-time data connector for AI builders:** you describe the live information your app needs, and Shipp delivers the right event stream into your product without building pipelines or managing integrations.

---

## Who this document is for[¶](#who-this-document-is-for "Permanent link")

This guide is designed to scratch the surface, going only deep enough to start your journey.

#### If you're an Agent or Technically Savvy[¶](#if-youre-an-agent-or-technically-savvy "Permanent link")

Expect to find clear, testable integration patterns and data-handling rules

#### If you're a Vibe Coder / Business Leader[¶](#if-youre-a-vibe-coder-business-leader "Permanent link")

Expect to find why the feature matters and how it improves trust, conversion, and retention

If you’re integrating Shipp via an AI builder, start with a [platform guide](/platform-guides) (e.g. [Lovable](/platform-guides/lovable)) and come back here for implementation strategy.

Too deep?

Let your agent go deep from here, if you're not an engineer or agent no worries! Shipp has you in mind and we're here to help. Reach out to support if you need guidance:[Support](/cdn-cgi/l/email-protection#463533363629343206352e2f363668272f) can be emailed at [support@shipp.ai](mailto:support@shipp.ai)

---

## The mental model: Shipp “Connections” = reusable live-data queries[¶](#the-mental-model-shipp-connections-reusable-live-data-queries "Permanent link")

The primary way to interact with Shipp is collecting events with a **Connection**:

* You **create** a connection by providing `filter_instructions` as plain English
* You **run** a connection to retrieve **raw event data** in a schema-flexible `data[]` array

This is intentionally simple: the “hard part” is describing what you want, and the agent can build the rest of the app around a stable `connection_id`.

For details on usage, see the [API Reference](/api-reference/).

---

## How to build[¶](#how-to-build "Permanent link")

### Step 1 — Write a “Real-Time Contract” for one screen[¶](#step-1-write-a-real-time-contract-for-one-screen "Permanent link")

Pick one screen that users will watch/refresh frequently (a “watch screen”), then define:

* **User promise:** what must stay accurate while they’re looking at it?
* **Triggering events:** what changes should cause UI updates?
* **Data shape you need:** what fields do you need to render and decide?
* **Freshness window:** how old can the last update be before you warn the user?
* **Failure mode:** what do you show if you can’t fetch updates?

Example contract (cross-industry):

* Screen: “Order Status”
* Promise: “Status changes and exceptions show up quickly.”
* Needs: `status`, `updated_at`, `location` (if present), `desc/type/category` as human-readable explanation
* Freshness window: 10 seconds to 5 minutes depending on your domain.
* Failure mode: “Last updated X minutes ago” + manual refresh + retry

This contract becomes the grounding spec for the agent.

---

### Step 2 — Translate the contract into `filter_instructions`[¶](#step-2-translate-the-contract-into-filter%5Finstructions "Permanent link")

Your `filter_instructions` should be:

* **Short**
* **Explicit**
* **Testable**
* **Scoped**

Think of it like a product requirement statement your data layer can execute.

Patterns that work well:

* include the domain (“NBA”, “shipment tracking”, “price changes”, etc.)
* scope to an entity, time window, or set (“for game\_id X”, “for today”, “for Team A”, “for this order/user”)
* name what you want surfaced (“high impact moments”, “status changes”, “exceptions”, “score updates”)

Example (sports, today):

* `filter_instructions`: `NBA games today: scoring runs, lead changes, 4th quarter clutch moments`

Example (generic product signal language):

* `filter_instructions`: `Status changes and exceptions for <entity>; include human-readable descriptions of what changed`

#### Not Everything Fits in a Perfect Box[¶](#not-everything-fits-in-a-perfect-box "Permanent link")

Shipp is ready to make data accessible for every industry, and that means access patterns will never fit in a perfect box with one way to do it all. 

Shipp provides helper APIs to maximize the value of real-time data specific to the industry. Sports has a future games schedule to help determine timing of future games. Other industries will include helper functions to maximize your value of Shipp.

Support is Expanding 

Today, the API docs show sports-specific examples and a sports schedule helper. The same “connection + run” pattern is applicable to all industries: you describe what you need; Shipp delivers the relevant event stream.

---

### Step 3 — Create a Connection once, store the `connection_id`[¶](#step-3-create-a-connection-once-store-the-connection%5Fid "Permanent link")

Use the API to create a connection, then persist:

* `connection_id`
* your `filter_instructions` (for debugging and iteration)
* any app-level metadata (screen/user/team/game\_id, etc.)
Expanding Support for Meta Fields 

We plan to introduce improved support for editing connections and adding arbitrary user metadata to connections so you can programmaticaly organize connections directly in Shipp. Additionally, expanded support to view and edit fields directly should eliminate most use cases for storing anything about your connections outside of Shipp. 

Why this matters:

* Faster app (creating connections can take a few seconds and cost credits)
* Lower costs & higher stability (eliminate chances for connections doing something different, fewer credits for creating connections)
* Less work (it's easier to offload management to another service, like Shipp)

[See the API Reference](/api-reference/connections-create)

---

### Step 4 — Run the Connection to fetch updates[¶](#step-4-run-the-connection-to-fetch-updates "Permanent link")

To power real-time UX with today’s API surface, use **pull-based** updates:

* On page load, run the connection with a reasonable `since` (or omit for default behavior).
* On an interval, re-run with `since_event_id` set to the most recent event processed.
* Merge/dedupe events into your UI state.
Pull vs Push 

Push is a superior method for most of these connections, however it comes with a tradeoff for supporting environments and quick iteration. We are currently investigating how we can implement and support push based connections for the best experience.

[See the API Reference](/api-reference/connections-run)

Practical UX defaults:

* polling interval: 5–30 seconds depending on your domain and cost sensitivity
* initial `limit`: start small (e.g. 25–100) until you learn the feed shape
* always surface “last updated” in the UI for trust

---

### Step 5 — Handle schema-flexible `data[]` defensively[¶](#step-5-handle-schema-flexible-data-defensively "Permanent link")

Shipp returns `data: [{...}, {...}]` where each element is a JSON object and the shape can vary by feed and availability.

Rules of thumb for agents/engineers:

* Treat every field as optional.
* Prefer safe access (existence checks) and graceful fallbacks.
* Log unknown shapes in development so you can refine `filter_instructions`.

What you can generally rely on:

* `connection_id` in the response
* `data` is an array
* elements may include common fields like `type`, `category`, `desc`, time fields, and IDs (especially in sports)

Build your UI around:

* a “headline” text (`desc` when present, otherwise a synthesized summary)
* a timestamp (if present; otherwise use “received\_at” from your app)
* a category/type badge (if present)
* domain-specific highlights (points/period in sports, etc. when present)
Available Data Fields are Extensive 

We'll soon have many hundreds of data fields available with specific definitions depending on the industry and even sub-industry (period in Hockey and Basketball are very different). Documenting these fields, though important, is not implemented. We highly encourage testing your connections to understand these fields while our field documentation catch up.

---

### Step 6 — Deduplicate, order, and reconcile[¶](#step-6-deduplicate-order-and-reconcile "Permanent link")

Polling-based real-time has normal failure modes: duplicates, late events, missing events.

Recommended reconciliation strategy:

* Keep a rolling set of seen events using the id, e.g. `01KGD5EVM8P0MCFTZ0AJBQZRDD`
* Prefer ordering by an explicit timestamp if present; otherwise order by id (Lexicographically stable).
* Send the lexicographically largest event id received as `since_event_id` to let Shipp send only the freshest data.
* If not using ID, Periodically re-run with a wider `since` window to self-heal (e.g., last 5–10 minutes) and dedupe.

If you’re storing events server-side:

* Store raw events as JSON for debug.
* Store a derived “latest state” view for fast UI rendering.

---

## Sports-specific helper[¶](#sports-specific-helper "Permanent link")

If you’re building sports experiences use the [schedule](/api-reference/sport-schedule)to discover current sport games available. Use that context to craft `filter_instructions` and create a connection. This also useful for ad-hoc connections on specific games.

This is a good example of how Shipp can provide “discovery endpoints” alongside the core connection pattern as additional industries come online.

---

## What “good” looks like (business value checklist)[¶](#what-good-looks-like-business-value-checklist "Permanent link")

A real-time feature is doing its job when you can say:

* “Users trust it while they’re watching it.”
* “It reduces manual refresh and uncertainty.”
* “It prevents bad decisions with stale state.”
* “It creates urgency or confidence at the right moments.”

Measurable outcomes often include:

* higher conversion (fewer stale availability/pricing surprises)
* lower support (fewer “what’s happening?” tickets)
* better retention (users return to live status)
* better automation (agents can act on fresh signals)
* faster iteration (change the product without rebuilding pipelines)

---

## Agent-friendly implementation prompt[¶](#agent-friendly-implementation-prompt "Permanent link")

When instructing an agent, include a fully testable spec. For example:

* “Build a watch screen that displays live events from Shipp.
* Create a Shipp connection using `POST https://api.shipp.ai/api/v1/connections/create?api_key=...` with `filter_instructions` \= `<paste>`.
* Persist the returned `connection_id`.
* On initial load, run `POST https://api.shipp.ai/api/v1/connections/{connection_id}?api_key=...` with `{ "limit": 50 }`.
* Every 10 seconds, re-run the connection with `{ "since_event_id": "<most recent id>", "limit": 5 }`.
* Render each event defensively (schema-flexible). Prefer `desc` when present.
* Show a “Last updated” indicator and a manual refresh button.
* If no updates succeed for 2 minutes, show a stale warning and keep retrying with backoff.
* Never expose the API key in client code; store it as a server-side secret.”

---

## Next steps[¶](#next-steps "Permanent link")

* Go through a practical example with [Instructions](/instructions/setup)
* Follow a platform guide to connect Shipp to your AI builder: [Lovable](/platform-guides/lovable)
* Review the implemented endpoints and examples: [API Reference](/api-reference/)

 Back to top