Notify object created or removed

Request

Notify your primary site that an object in its bucket was created or removed. Most users should set up bucket notifications instead.

When storageProvider is azure for a bring-your-own-storage site, azureStorageAccountName is required.

For bring-your-own-storage sites, the site's ingest path policy still determines whether an object is indexed. Explicit device and project values in this request override assignments from the policy; omitted values fall back to the matched rule.

This endpoint requires a Site Bucket Notification Token as bearer token in the Authorization header:

Authorization: Bearer fox_snt_1234...

Security

SiteBucketNotificationBearerToken

Bodyapplication/jsonrequired

messageIdstringrequired

Unique message identifier. Ingest notifications are deduplicated on this value. object_removed does not use it for deduplication. A repeated removal for the same bucket and object path is idempotent.

fileNamestring, non-emptyrequired

The name of the recording file in the bucket.

bucketNamestring, non-emptyrequired

Bucket name

storageProviderstringrequired

Storage provider used for the bucket. This must match the storage provider configured for your primary site's inbox bucket or indexed bucket.

Enum:"google_cloud""aws""azure""s3_compatible"

azureStorageAccountNamestring, non-empty

Azure storage account that contains the container. Required when storageProvider is azure for a bring-your-own-storage site. Omit this field for other storage providers and for other site types.

notificationTypestring

Kind of object event this notification reports. If not provided, defaults to object_created.

deviceId, deviceName, projectId, sessionId, and sessionKey apply only to object_created. Sending any of them with object_removed returns 400. object_removed on a query-optimized site also returns 400.

Enum:"object_created""object_removed"

deviceIdstring, non-empty

Device to associate with the recording. This takes precedence over assignments from the site's ingest path policy and values provided in object metadata or MCAP metadata.

deviceNamestring, non-empty

Name of the device to associate with the recording. The device is looked up by name and created if it does not already exist. deviceId takes precedence over deviceName when both are provided. An existing device with a unique name resolves without a projectId. Provide projectId to disambiguate when the name matches devices in multiple projects, or to choose which project a new device is created in when your organization has multiple projects. This takes precedence over assignments from the site's ingest path policy and values provided in object metadata or MCAP metadata.

A name that does not match an existing device must satisfy the same rules as POST /devices: at most 100 characters, containing only letters, numbers, underscores, periods, and hyphens.

projectIdstring, non-empty

Project to associate with the recording. This takes precedence over assignments from the site's ingest path policy and values provided in object metadata or MCAP metadata.

sessionIdstring, non-empty

ID of an existing session to associate with the recording. Takes precedence over sessionKey and session values in object metadata or MCAP metadata. The session supplies omitted project and device IDs. Project and device values supplied in the request must match the session's associations. Omit deviceId and deviceName when the session has no device.

Self-hosted Primary Sites must have reported a valid version of 0.0.108 or later to use this field.

sessionKeystring, non-empty

Key of a session to associate with the recording. Keys are unique within a project. During ingestion, Foxglove looks up the session or creates it if enough project and device context is available. Ignored when sessionId is provided. This takes precedence over session values in object metadata or MCAP metadata.

Self-hosted Primary Sites must have reported a valid version of 0.0.108 or later to use this field.

Payload

{
  "messageId": "string",
  "fileName": "string",
  "bucketName": "string",
  "storageProvider": "google_cloud",
  "azureStorageAccountName": "string",
  "notificationType": "object_created",
  "deviceId": "string",
  "deviceName": "string",
  "projectId": "string",
  "sessionId": "string",
  "sessionKey": "string"
}

Responses

success

Bodyapplication/json

successbooleanrequired

Value:true

Response

{
  "success": true
}