RoboSystems
Browse technical docs

Shared Repositories

A shared repository is a platform-managed, read-only public dataset you subscribe to and query alongside your own graphs. Where the dedicated tiers in Graphs & Multi-Tenancy give each customer an isolated graph, a shared repository is a single large graph that every subscriber reads — served from its own infrastructure tier and billed per subscriber. SEC EDGAR is the one shared repository available today.

Running your own stack? Every example here works against a local deployment: use http://localhost:8000 and the key from just demo-user. See Local Development.

Table of Contents

What a shared repository is

A shared repository is a public dataset modeled as a graph that the platform owns, maintains, and serves to all subscribers — as opposed to a customer graph (kg…), which holds one tenant's private data. The two differ on nearly every axis:

Customer graph (kg…)Shared repository (e.g. sec)
DataYour private dataPublic data, identical for everyone
AccessOwner + granted usersAny user with a subscription
WritesRead + writeRead-only
InfrastructureDedicated per-customer instanceShared master + read-only replica fleet
ScalingVertical (bigger instance)Horizontal (more replicas)
BillingPer-graph subscriptionPer-subscriber repository plan

Because it is just a graph, you query a shared repository through the same surfaces as your own — Cypher, the MCP tools, search — using its repository id as the graph_id. An AI Operator can traverse a shared repository and your own graph in a single workflow (for example, comparing your portfolio against SEC filings). It is strictly read-only: write, backup, restore, and admin operations are rejected.

The ladybug-shared tier

Shared repositories run on a dedicated infrastructure tier, ladybug-shared, separate from the per-customer dedicated tiers:

  • A shared master instance owns the build path — the ingestion pipeline materializes the graph here.
  • A read-only replica fleet serves queries. Replicas download the materialized .lbug / .duckdb / vector artifacts from S3 on boot and sit behind a load balancer, so read volume scales by adding replicas rather than by resizing one instance.
  • On robosystems.ai this tier serves the SEC repository; for a self-hosted deployment it is opt-in (LBUG_SHARED_ENABLED), since the replica fleet is separate infrastructure.

See the Architecture Overview for the cluster topology and the S3-publish → replica-refresh flow.

The registry and manifest model

Every shared repository is declared by a single adapter manifest and registered in config/shared_repositories.py. The manifest is the one source of truth for the repository — its identity, data source, schema, allowed and blocked endpoints, rate limits, subscription plans, and credit costs all live in one file. The registry lazy-loads manifests and exposes a query API (is_shared_repository, get_manifest, get_all_repository_ids, get_plan_details) used across billing, middleware, and operations.

Adding a new shared repository is therefore a two-step change — write the manifest, register it — with no separate billing config, database migrations, or hardcoded lists to update. The ingestion side (how a repository's data is downloaded, staged, materialized, and published to the replica fleet) is covered in the Pipeline Guide. SEC is the only shared repository registered today; the model is built to host additional public datasets.

Subscribing and accessing

Shared repository plans are discoverable without authentication at the public offering endpoint, which returns graph subscription tiers, shared repository plans, and AI credit costs:

curl https://api.robosystems.ai/v1/offering

A customer graph's subscription is created automatically when the graph is provisioned. A shared repository is different — you subscribe to it explicitly, choosing one of its plans, from Repositories in the app or over the API:

export ROBOSYSTEMS_API_KEY=rfs...   # Settings → API keys at robosystems.ai

curl -X POST "https://api.robosystems.ai/v1/graphs/sec/subscriptions" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_name": "starter"}'

A repository's plans are named in its manifest — for sec, starter and advanced. The repository-prefixed spellings (sec-starter, sec-advanced) are accepted as well, and the subscription records the bare plan name. Checking your subscription uses the same endpoint, which auto-detects graphs versus repositories:

curl "https://api.robosystems.ai/v1/graphs/sec/subscriptions" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY"

Changing plan and cancelling are the other two verbs on the same path:

# Move to the higher plan (synchronous for repositories)
curl -X PATCH "https://api.robosystems.ai/v1/graphs/sec/subscriptions" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_plan_name": "advanced"}'

# Cancel at period end (access stays until the period closes)
curl -X POST "https://api.robosystems.ai/v1/graphs/sec/subscriptions/cancel" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY"

Cancellation defaults to end-of-period; pass immediate: true together with confirm: "sec" to stop access right away. All three write calls accept an optional user_id, so an org owner or admin can subscribe, change, or cancel on behalf of another member of their organization — repository access is per-user while the billing is org-level, so the subscriber is what determines who gets in. A member acting on their own subscription omits it.

Once subscribed, you query the repository exactly like your own graph — its id (sec) is the graph_id in the URL:

curl -X POST "https://api.robosystems.ai/v1/graphs/sec/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (e:Entity) RETURN e.name LIMIT 10"}'

Database operations (query, MCP, search) are free — they draw down rate-limit budget, not credits. Only AI operations consume credits, drawn from your repository plan's monthly allocation. See Credits & Billing.

The SEC shared repository

SEC EDGAR is the one shared repository available today — public-company filings and XBRL financial data, updated through each business day (Freshness), with semantic enrichment for natural-language element resolution. Its plans are read-only and differ on throughput and backup-download allowance:

Planplan_nameAccess
StarterstarterRead
AdvancedadvancedRead, with higher rate limits and a larger download allowance

Prices, monthly AI credit allocations and download allowances are served live and unauthenticated at GET /v1/offering, and shown on the pricing page. Rate limits apply per category — queries, MCP calls, searches, and AI agent calls each have their own per-minute / per-hour / per-day budgets.

The repository id is sec. For the data model and the rules a query must follow to return the right number, see SEC Data Model & Query Rules; for loading filings into a local stack, the SEC XBRL Pipeline demo.

Freshness

The repository moves on two clocks, on business days:

  • The day a filing is filed. Three passes through the day bring new XBRL filings into the filer catalog and their public folders, so the text views (describe-filing, search-text, read-text), disclosures, information-block and the viewer reach a filing the day it is filed. 8-K earnings releases from filers in the corpus are captured with their exhibits every 30 minutes through the filing day.
  • The next morning. The nightly run rebuilds the graph and the document search index with the day's filings, so Cypher, build-fact-grid, financial-statement-analysis, resolve-element and search-documents have them the following morning.

Downloading a snapshot

Subscribers whose plan carries a download allowance can pull the whole repository down as a LadybugDB file rather than querying it over the API. Ask for a presigned URL, then fetch it:

# Latest published snapshot — one backup record per repository, republished on each pipeline run
curl -s "https://api.robosystems.ai/v1/graphs/sec/backups" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY"

curl -s "https://api.robosystems.ai/v1/graphs/sec/backups/BACKUP_ID/download" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY"

curl -L -o sec.lbug.zst "PASTE_THE_DOWNLOAD_URL"

Snapshots arrive zstd-compressed (.lbug.zst), so you need the zstd tool — it ships with neither macOS nor most Linux distributions by default:

brew install zstd            # macOS
sudo apt-get install zstd    # Debian / Ubuntu
sudo dnf install zstd        # Amazon Linux / Fedora / RHEL

Then decompress it in the folder holding the download (on macOS, right-click the folder → Services → New Terminal at Folder to get there):

zstd -d sec.lbug.zst   # -> sec.lbug ; add --rm to delete the .zst afterwards

Plain zstd -d is enough — no --long flag — and the decompressed file is roughly 2× the download, so leave disk headroom. The result is a LadybugDB database you can query directly; see Graph Operations for the full download-and-unpack walkthrough.

The same graph file is also published as a public dataset on Hugging Face, robosystems/sec-xbrl-knowledge-graphs, under CC BY 4.0 and with no subscription. That copy is published by hand, not on every pipeline run, so it is a point-in-time snapshot — its dataset card gives the date and the filings it runs through — and lags the hosted graph. It is the graph alone: the filing-text views, the viewer and document search are not in it.

Self-hosted deployments

There is no free hosted SEC tier; self-hosting is the free path. On a stack you run, load the filings you want with just sec-load, or the whole corpus from the Hugging Face snapshot with just sec-dump, and query them through the same sec graph id — see Local Development.

Support