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 8601When the marker stops affecting reads.
ttlSecondsintegerMarker lifetime in seconds.
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 in effect. Reads against the target cache rule re-execute on the warehouse.
expiredMarker TTL has elapsed. Cache resumes normal behavior on the target rule.

Markers expire after 24 hours by default. Long-running invalidations should re-fire markers periodically rather than relying on a single one to last indefinitely.

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