Open source · MIT

An open contract for saved content.

Orbit defines one set of schemas and client methods for saving URLs, notes, media, and extracted detail — so apps stop depending on any single service’s database layout. Orbb is the first production adapter.

View on GitHubRead the API docs
@orbb/orbit-sdkv0.3.4MIT LicenseESM · TypeScript

The data model

Five shapes. That’s the whole contract.

Every private read and write is scoped to its owner. Search implementations stay a service internal — raw index data is never part of the public contract.

OrbitItem
One saved item: a URL, a note, media, or extracted detail.
EvidenceChunk
The searchable unit. Smaller than an item, so a service can return the exact text that matched.
Entity
A person, place, organization, or topic found inside an item.
Resource
A structured thing: a book, place, song, movie, or product.
UserFact
A durable user fact or preference, kept deliberately separate from saved content.

In practice

Three lines to a saved item.

TypeScript
import { OrbitClient } from "@orbb/orbit-sdk";

const client = new OrbitClient({
  baseUrl: "https://api.orbb.app/v2",
  apiPath: false,
  apiKey: accessToken,
});

await client.bookmarks.createItem({
  source: {
    type: "url",
    url: "https://example.com/story",
    platform: "web",
  },
  title: "A useful story",
  privacy: { scope: "private" },
});

const existing = await client.bookmarks.findExistingUrls([
  "https://example.com/story",
]);

What’s in the package

A client, not a framework.

Request and response types

Full TypeScript types for every shape in the contract, generated from the JSON Schemas in the repo.

OrbitClient

An authenticated HTTP client. Appends /orbit/v1 by default, or point it anywhere with apiPath.

Ingestion helpers

Save URLs, text, and local media. The SDK uploads and finalizes media before creating the bookmark.

QR sign-in

Browser extensions and desktop apps authorize against a user’s account without shipping an API key.

Local test store

LocalOrbitStore gives owner-scoped storage, evidence extraction, filters, and keyword search in memory.

Owner-scoped by default

Public creates omit ownerId entirely. Services must bind ownership from the authenticated request.

Orbb-hosted endpoints

Two ways to connect.

QR capture

https://api.orbb.app/v2

For browser extensions and desktop or web capture apps. QR sign-in returns a user-authorized bearer token, so the client needs no backend and no pre-issued key. Capture tokens can create bookmarks, check for existing URLs, and upload media.

Public REST API

https://api.orbb.app/v1

For private servers and personal automations. Create a key in Orbb under Settings → Orbb API with only the read, write, or ai scopes you need. Keys act as the user who created them, so never ship one in a client.

Public applications should use OAuth with PKCE. Never commit an API key or embed one in an extension, website, or mobile app.

Documentation

Everything is written down.

GitHubtargaryen1212/orbit

Protocol notes, JSON Schemas, the OpenAPI definition, the SDK source, and runnable examples.

npm@orbb/orbit-sdk · v0.3.4

The published TypeScript client. ESM only, ships its own types, no runtime dependencies to configure.

developer.orbb.appREST API · MCP · OpenAPI

The Orbb developer docs. REST over HTTPS and JSON with OAuth or an API key, plus a remote MCP server with Firebase authentication — both exposing the same registered tools.

OpenAPI specapi.orbb.app/v1/openapi.json

Generate a client in any language, or point your own tooling straight at the live specification.

Build on your users’ own data.

Orbit is an early contract, MIT licensed, and open to adapters beyond Orbb.

View on GitHubRead the API docs

npm install @orbb/orbit-sdk · MIT License