Replica Cache

Replica Cache is a read-only REST API that serves NetBox data from an operationally independent cache, delivering sub-50ms P95 query latency and resilience independent of the primary NetBox database. It is available as a premium-tier feature on NetBox Cloud.

Customer Preview: Replica Cache is in customer preview. The API surface may evolve in future releases.

For the interactive API reference (OpenAPI/ReDoc), visit /docs on your Replica Cache endpoint.

Why Use Replica Cache

• Operational resilience - Replica Cache serves reads from an operationally independent cache. Your monitoring, reporting, and automation scripts keep working even during NetBox maintenance windows or outages.
• Fast reads at scale - Queries return in single-digit milliseconds for most workloads. Filtering and pagination happen server-side, reducing data transfer and client-side processing.
• Zero load on the primary database - Every Replica Cache read is served from the cache. High-frequency polling, dashboards, and bulk data exports never touch the primary NetBox database.

Replica Cache complements the primary NetBox API - use it for read-heavy automation that benefits from speed and resilience, and continue using the primary API for writes and real-time consistency.

Replica Cache vs. TurboBulk: Both are premium-tier performance features. TurboBulk provides fast bulk reads and writes with exact consistency, operating directly against the primary database. Replica Cache offloads reads to an independent cache - eventually consistent, but zero primary database load and resilient to outages. They're complementary: TurboBulk for bulk writes and consistent reads, Replica Cache for high-frequency read automation and resilience.

Key Differences from the NetBox API

Replica Cache is not a drop-in replacement for the NetBox API. Responses use flat column values rather than nested objects, filter syntax differs, and write operations are not supported.

Authentication

Every request to /v1/* endpoints requires two headers:

BASE_URL="https://<your-netbox>.cloud.netboxapp.com/replica-cache"

curl -s \
  -H "Authorization: Bearer $REPLICA_CACHE_API_TOKEN" \
  -H "NBC-Netbox-ID: $TENANT_ID" \
  "$BASE_URL/v1/dcim/devices?limit=1"

Replica Cache uses tenant-bound API tokens that are separate from your NetBox Cloud API token - contact NetBox Labs Support to have one issued for your tenant. The token is permanently bound to a single tenant_id, so the value you send in NBC-Netbox-ID must match the tenant the token was issued for. If they disagree the server returns 403; if NBC-Netbox-ID is missing the server returns 400; if the token is unknown the server returns 401.

Quick Start

1. Choose an entity

Entity coverage is published in the OpenAPI reference at /docs. Entity paths use {app}/{model} style, for example dcim/devices.

2. List records

Query any entity using its {app}/{model} path (derived from the table name - dcim_device becomes dcim/devices):

curl -s \
  -H "Authorization: Bearer $REPLICA_CACHE_API_TOKEN" \
  -H "NBC-Netbox-ID: $TENANT_ID" \
  "$BASE_URL/v1/dcim/devices?limit=2"

{
  "count": 1042,
  "next_cursor": "WzEsMl0",
  "results": [
    { "id": 1, "name": "spine-01", "status": "active", "site_id": 5 },
    { "id": 2, "name": "spine-02", "status": "active", "site_id": 5 }
  ]
}

3. Get a single record

Fetch one record by its primary key:

curl -s \
  -H "Authorization: Bearer $REPLICA_CACHE_API_TOKEN" \
  -H "NBC-Netbox-ID: $TENANT_ID" \
  "$BASE_URL/v1/dcim/devices/1"

{ "id": 1, "name": "spine-01", "status": "active", "site_id": 5 }

Querying

Filtering

Filter results using query parameters in the form filter[column]__operator=value. When no operator is specified, eq (exact match) is used.

# Devices with status "active" at site 5
curl -s \
  -H "Authorization: Bearer $REPLICA_CACHE_API_TOKEN" \
  -H "NBC-Netbox-ID: $TENANT_ID" \
  "$BASE_URL/v1/dcim/devices?filter[status]=active&filter[site_id]=5"

Operators:

Column names correspond to database columns. Available columns vary by NetBox version and configuration; unknown columns are rejected with 400.

Sorting

Sort results with the sort parameter. Prefix with - for descending order:

?sort=name          # ascending by name
?sort=-id           # descending by id

Default sort order is ascending by primary key.

Field Selection

Return only specific columns with the fields parameter:

?fields=id,name,status

The primary key column is always included in the response, even if not listed.

Pagination

Replica Cache uses cursor-based pagination. Each list response includes:

Use the limit parameter to control page size (default: 50, maximum: 1000).

To paginate through all results, pass the next_cursor value from each response as the cursor parameter on the next request:

cursor=""
while true; do
  response=$(curl -s \
    -H "Authorization: Bearer $REPLICA_CACHE_API_TOKEN" \
    -H "NBC-Netbox-ID: $TENANT_ID" \
    "$BASE_URL/v1/dcim/devices?limit=100${cursor:+&cursor=$cursor}")

  # Process results...
  echo "$response" | jq '.results[]'

  # Get next cursor; exit loop if null (last page)
  cursor=$(echo "$response" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Data Freshness

Replica Cache is fed by a continuous stream of changes from the primary NetBox database. Every create, update, and delete is propagated to the cache as it happens - not on a fixed polling interval - so a change made in NetBox typically appears in the cache within 1-2 seconds, and nearly always within 10 seconds.

Schema

Replica Cache schema depends on your NetBox version and installed plugins. Row payloads are JSON objects whose keys mirror the cached database columns for that entity. Build filters and field selections against columns present in returned rows; requests for unknown filter, sort, or field-selection columns return 400.

Error Handling

Errors are returned as JSON with an error field:

{ "error": "missing tenant header" }

Status codes:

Limitations

• Read-only - no create, update, or delete operations. Use the primary NetBox API for writes.
• Near-real-time, eventually consistent - changes stream from NetBox continuously and typically appear within 1-2 seconds (nearly always within 10s), but Replica Cache is not transactionally consistent with the primary. Do not rely on it for read-after-write consistency.
• Main branch only - Replica Cache serves data from the main NetBox branch. Branching plugin branches are not available.
• Flat responses - related objects are represented by foreign key IDs, not nested objects. Join data client-side if needed.
• Schema varies by NetBox version - available columns may change across NetBox upgrades. Requests for unknown columns return 400.
• Non-core object types require configuration - core NetBox object types are available by default. Plugin models and non-core types can be enabled by contacting the NetBox Cloud support team.
• Customer preview - the API surface may change in future releases.

API Reference

All endpoints below require the Authorization and NBC-Netbox-ID headers.

Path segments beginning with _ under /v1 are reserved and return 404 after successful authentication.

For the full OpenAPI specification, visit /docs on your Replica Cache endpoint.