Mozilla Remote Settings

Mozilla Remote Settings

Public read-only access to Firefox's configuration and content delivery infrastructure. Built on the Kinto protocol. No authentication required.

Architecture

Production Remote Settings—the configuration surface Firefox clients poll—is organized hierarchically: Bucket → Collection → Record.

Entity Hierarchy

• Buckets — top-level namespaces. The primary production bucket is main. Others include blocklists, security-state, and monitor/changes for polling.

  • Enumerate available buckets.
  • Retrieve a single bucket's metadata by id.

• Collections — datasets within a bucket. Each collection has a schema, last-modified timestamp, and metadata. Common collections in main:

  • addons-bloomfilters — addon blocklist data
  • anti-tracking-url-decoration — tracking protection rules
  • cfr — contextual feature recommendations
  • hijack-blocklists — DNS hijack protection
  • nimbus-desktop-experiments — experiment configurations
  • password-recipes — login form detection rules
  • regions — geographic region data
  • search-config-v2 — search engine configurations
  • sites-classification — site categorization data
  • tippytop — site icon/thumbnail mappings
  • Enumerate collections with bucket_id to discover all collections.

• Records — individual data entries within a collection. The actual configuration data Firefox consumes. Each record has an id and last_modified timestamp.

  • Reading records requires both bucket_id and collection_id.
  • A single-record read needs bucket_id, collection_id, and record id.

• Groups — permission groups within a bucket. Define who can read/write collections.

  • Enumerating groups and opening one group both require bucket_id.

Server Metadata & Health

• Server info — server version, capabilities, project info.
• Schema export — machine-readable service description for the Kinto protocol.
• Heartbeat — deep health check (database, cache).
• LB heartbeat — lightweight load balancer check.
• Version — deployed version info.
• Changes — global changelog across all buckets/collections (the high-level change feed Firefox polls).
• Contribute — contribution metadata (contribute.json).
• Collection changeset — diff-based sync surface. Requires bid (bucket), cid (collection), and _expected params.

Workflows

1. Discover available data: Enumerate buckets → choose main for most research → enumerate collections inside that bucket → scan collection ids.
2. Read configuration data: From the target collection, page records using both bucket and collection context on every request.
3. Monitor changes: Global changelog reads for “what changed anywhere,” plus per-collection diff reads when you need incremental sync.
4. Server health: Server metadata, heartbeat, and version reads confirm the service is healthy and which build is live.

Gotchas

• Read-only public integration: No mutations—inspection and export only.
• Hierarchical IDs: Every query requires parent IDs. Records need both bucket_id AND collection_id. Collections need bucket_id. There are no flat/global search endpoints.
• main bucket: ~95% of useful Firefox data lives in the main bucket. Start there.
• Collection diff reads: Diff/sync style calls need a freshness watermark (the _expected-style parameter the integration exposes) so the server can return only what changed.
• Large record sets: Some collections (e.g. addons-bloomfilters) contain very large records. Use _limit param to paginate if needed.