/

Markers API

Invalidation markers are how an out-of-band event tells the Gateway that a cache rule's results are now suspect. Once a marker is recorded, the next read against the targeted cache rule re-executes against the warehouse, even if the rule's TTL hadn't expired. Use this API for ETL completions, scheduled refreshes, and anything else that changes data outside the SQL stream.

Authentication

All endpoints require a Personal Access Token in the Authorization header with cache-admin scope on the target tenant. 

Authorization: Bearer YOUR_PAT

Endpoints

MethodPathPurpose
GET/tenants/{tenantId}/invalidation-markersList markers
GET/tenants/{tenantId}/invalidation-markers/{markerId}Get marker details
POST/tenants/{tenantId}/invalidation-markersCreate a manual marker
DELETE/tenants/{tenantId}/invalidation-markers/{markerId}Delete a marker

List markers

GET /tenants/{tenantId}/invalidation-markers

Query parameters

ParameterDescription
statusFilter by active or expired.
targetRuleIdFilter by the cache rule a marker invalidates.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.airbrx.ai/tenants/your-slug/invalidation-markers"

Response

{
  "_links": {
    "self": { "href": "/tenants/your-slug/invalidation-markers" },
    "items": [
      {
        "name": "cache-orders.1-InvalidationMarker",
        "href": "/tenants/your-slug/invalidation-markers/cache-orders.1-InvalidationMarker"
      }
    ]
  }
}

Get marker details

GET /tenants/{tenantId}/invalidation-markers/{markerId}

Response

{
  "invalidatedAt": "2026-02-01T17:31:04Z",
  "expiresAt":     "2026-02-02T17:31:04Z",
  "ttlSeconds":    86400,
  "invalidatedBy": {
    "ruleId": "orders-dml",
    "statement": "INSERT INTO orders (id, customer_id, total) VALUES (:p0, :p1, :p2)",
    "triggeredBy": "Cross-rule invalidation"
  },
  "createdAt": "2026-02-01T17:31:04Z"
}
FieldTypeDescription
invalidatedAtISO 8601When the marker was created.
expiresAtISO 8601invalidatedAt plus the target rule’s TTL — never earlier than the last cache entry the marker invalidates.
ttlSecondsintegerMarker lifetime in seconds, inherited from the target cache rule’s TTL. Derived, not settable — POST accepts no TTL field.
invalidatedBy.ruleIdstringRule that fired (DML rule for cross-rule invalidation, or the marker's own creator).
invalidatedBy.statementstringSQL that triggered the marker, when applicable.
invalidatedBy.triggeredBystringSource description: "Cross-rule invalidation", "Manual", etc.

Create a manual marker

POST /tenants/{tenantId}/invalidation-markers

Request body

{
  "markerId": "etl-refresh-20260201",
  "targetRuleId": "cache-analytics",
  "metadata": {
    "reason": "Daily ETL completed"
  }
}
FieldRequiredDescription
markerIdYesUnique identifier for this marker.
targetRuleIdYesCache rule whose results should be marked stale.
metadata.reasonNoFree-form description for debugging and audit.

Example

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"markerId":"etl-20260201","targetRuleId":"cache-analytics","metadata":{"reason":"ETL completed"}}' \
  "https://api.airbrx.ai/tenants/your-slug/invalidation-markers"

Delete a marker

DELETE /tenants/{tenantId}/invalidation-markers/{markerId}

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.airbrx.ai/tenants/your-slug/invalidation-markers/etl-20260201"

Response

{
  "success": true,
  "message": "Marker etl-20260201 deleted successfully"
}

Marker lifecycle

StatusMeaning
activeThe marker is the effective cutoff for its target rule. Entries cached before it read as misses and re-execute on the warehouse; entries cached after it are valid immediately.
expiredThe marker's TTL — the target rule's TTL — has elapsed. Every cache entry born before the marker has aged out with it, so nothing stale can be served; the marker remains only as a record.

A marker's TTL is inherited from the target cache rule's TTL — it is not set independently and cannot be overridden on POST. The practical guarantee: a marker never expires before the cache entries it invalidates. You will often see 24 hours, but only because 86400 is the default rule TTL; a rule with a one-hour TTL gets one-hour markers, and both age out together. There is no need to re-fire a marker to keep an invalidation alive — firing a new one just moves the cutoff forward, superseding any older marker on the same rule.

Naming conventions

markerId is yours — pick something that's easy to identify in audit and debugging. Patterns that work well: 

etl-daily-20260201
inventory-sync-20260201-0600
manual-cache-clear-admin
schema-migration-orders-v3

See also