How to Shipp?

Real-time data is pivotal in every app¶

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?¶

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?¶

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¶

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

If you're an Agent or Technically Savvy¶

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

If you're a Vibe Coder / Business Leader¶

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 (e.g. Lovable) and come back here for implementation strategy.

The mental model: Shipp “Connections” = reusable live-data queries¶

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.

How to build¶

Step 1 — Write a “Real-Time Contract” for one screen¶

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¶

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¶

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.

Step 3 — Create a Connection once, store the connection_id¶

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.)

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

Step 4 — Run the Connection to fetch updates¶

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.

See the API Reference

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¶

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)

Step 6 — Deduplicate, order, and reconcile¶

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¶

If you’re building sports experiences use the 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)¶

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¶

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¶

• Go through a practical example with Instructions
• Follow a platform guide to connect Shipp to your AI builder: Lovable
• Review the implemented endpoints and examples: API Reference