zone.stratos.sync.subscribeRecords Documentation (EN)

main subscription

Subscribe to stratos events. When 'did' is provided, subscribes to record updates for that account. When omitted, subscribes to service-level events (enrollments). Callers must authenticate with a signed service JWT via the Authorization: Bearer header.

Parameters

cursor integer Optional

The last known event sequence number to resume from.

did stringdid Optional

The DID of the account to subscribe to. If omitted, subscribes to service-level enrollment events.

domain string Optional

Optional domain filter. Only events for records with this domain in their boundary will be emitted.

Message Types

Open union

#commit #enrollment #info

Errors

FutureCursor Cursor is in the future.

AuthRequired Authentication is required.

View raw schema

{
  "type": "subscription",
  "errors": [
    {
      "name": "FutureCursor",
      "description": "Cursor is in the future."
    },
    {
      "name": "AuthRequired",
      "description": "Authentication is required."
    }
  ],
  "message": {
    "schema": {
      "refs": [
        "#commit",
        "#enrollment",
        "#info"
      ],
      "type": "union"
    }
  },
  "parameters": {
    "type": "params",
    "properties": {
      "did": {
        "type": "string",
        "format": "did",
        "description": "The DID of the account to subscribe to. If omitted, subscribes to service-level enrollment events."
      },
      "cursor": {
        "type": "integer",
        "description": "The last known event sequence number to resume from."
      },
      "domain": {
        "type": "string",
        "maxLength": 253,
        "description": "Optional domain filter. Only events for records with this domain in their boundary will be emitted."
      }
    }
  },
  "description": "Subscribe to stratos events. When 'did' is provided, subscribes to record updates for that account. When omitted, subscribes to service-level events (enrollments). Callers must authenticate with a signed service JWT via the Authorization: Bearer header."
}

commit object

A commit event containing record operations.

Properties

did string did Required

The DID of the account.

ops array of ref#recordOp Required

List of record operations in this commit.

rev string tid Required

The repo revision.

seq integer Required

The sequence number of this event.

time string datetime Required

Timestamp of when the event was sequenced.

View raw schema

{
  "type": "object",
  "required": [
    "seq",
    "did",
    "time",
    "rev",
    "ops"
  ],
  "properties": {
    "did": {
      "type": "string",
      "format": "did",
      "description": "The DID of the account."
    },
    "ops": {
      "type": "array",
      "items": {
        "ref": "#recordOp",
        "type": "ref"
      },
      "description": "List of record operations in this commit."
    },
    "rev": {
      "type": "string",
      "format": "tid",
      "description": "The repo revision."
    },
    "seq": {
      "type": "integer",
      "description": "The sequence number of this event."
    },
    "time": {
      "type": "string",
      "format": "datetime",
      "description": "Timestamp of when the event was sequenced."
    }
  },
  "description": "A commit event containing record operations."
}

enrollment object

An enrollment event indicating a user has enrolled or unenrolled from the service.

Properties

action string Required

The enrollment action.

maxLength: 32 bytes

Known values: enroll, unenroll

boundaries array of string Optional

The boundaries assigned to the user.

did string did Required

The DID of the user.

service string uri Optional

The Stratos service endpoint URL.

time string datetime Required

Timestamp of the enrollment event.

View raw schema

{
  "type": "object",
  "required": [
    "did",
    "action",
    "time"
  ],
  "properties": {
    "did": {
      "type": "string",
      "format": "did",
      "description": "The DID of the user."
    },
    "time": {
      "type": "string",
      "format": "datetime",
      "description": "Timestamp of the enrollment event."
    },
    "action": {
      "type": "string",
      "maxLength": 32,
      "description": "The enrollment action.",
      "knownValues": [
        "enroll",
        "unenroll"
      ]
    },
    "service": {
      "type": "string",
      "format": "uri",
      "description": "The Stratos service endpoint URL."
    },
    "boundaries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The boundaries assigned to the user."
    }
  },
  "description": "An enrollment event indicating a user has enrolled or unenrolled from the service."
}

info object

An informational message about the subscription state.

Properties

message string Optional

Additional details about the info message.

maxLength: 1024 bytes

name string Required

The type of info message.

maxLength: 128 bytes

Known values: OutdatedCursor

View raw schema

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 128,
      "description": "The type of info message.",
      "knownValues": [
        "OutdatedCursor"
      ]
    },
    "message": {
      "type": "string",
      "maxLength": 1024,
      "description": "Additional details about the info message."
    }
  },
  "description": "An informational message about the subscription state."
}

recordOp object

A single record operation within a commit.

Properties

action string Required

The type of operation.

maxLength: 32 bytes

Known values: create, update, delete

cid cid-link Optional

The CID of the record. Present for create and update operations.

path string Required

The record path (collection/rkey).

maxLength: 512 bytes

record unknown Optional

The record content. Present for create and update operations.

View raw schema

{
  "type": "object",
  "required": [
    "action",
    "path"
  ],
  "properties": {
    "cid": {
      "type": "cid-link",
      "description": "The CID of the record. Present for create and update operations."
    },
    "path": {
      "type": "string",
      "maxLength": 512,
      "description": "The record path (collection/rkey)."
    },
    "action": {
      "type": "string",
      "maxLength": 32,
      "description": "The type of operation.",
      "knownValues": [
        "create",
        "update",
        "delete"
      ]
    },
    "record": {
      "type": "unknown",
      "description": "The record content. Present for create and update operations."
    }
  },
  "description": "A single record operation within a commit."
}