Foxglove API (v1)

Authentication

All routes require an API key with specific capabilities. Org admins can create an api key.

Requests must include the API key in the Authorization header as a bearer token:

Authorization: Bearer fox_sk_1234...

Each endpoint in the API reference lists the capabilities required for access. An endpoint with Authorizations ApiKey (devices.list) would require an api key with the devices.list capability.

Sorting and pagination

Some GET endpoints support sorting and pagination.

Where supported, you will see the following query parameters in the endpoint documentation:

sortBy – Field name to sort by (endpoint specific)
sortOrder – "asc" or "desc"
limit – Number of records in the response
offset – Number of records to skip

If no limit is provided, endpoints will default to a limit of 2000 items. Requesting a limit greater than 2000 items will result in a 400 response.

Timestamps

Unless otherwise documented, all timestamp related fields (start, end, created, etc) use the ISO8601 conforming RFC3339 UTC "Zulu" format.

In the documentation this will appear as string types with <date-time> formatting (i.e. string <date-time>).

These timestamps support nanosecond resolution with up to nine fractional digits.

Examples:

2023-04-06T09:15:30Z
2023-04-06T18:27:45.876543210Z

Note: Variants of RFC3339 using durations or offsets which are not conforming to ISO8601 are not supported.

Python examples

Documentation here includes examples for the Foxglove Python SDK where supported. The SDK can be downloaded from PyPI and source is available on GitHub.

Note: As of v0.5.0, all methods require the use of keyword arguments.

Rate limits

To help ensure responsiveness for all clients, requests to the API may be rate-limited. In this case, a request will receive a status code of 429. Your client may refer to headers, such as "Retry-After", to determine when a request should be retried.

In general, if your client experiences an error, you should adjust the rate at which your client makes requests, and you may issue retries with a strategy such as exponential backoff.

Coverage

Coverage provides the ability to see which time spans are available within Foxglove.

List coverage

A coverage range represents a time span for which Foxglove has data for a given device.

Your must specify the start and end arguments when making a coverage request.

Note: By default, only coverage ranges with imported recordings are returned. To include coverage ranges with unimported recordings from an Edge Site or Agent, set the includeEdgeRecordings query parameter to true

Authorizations:

ApiKey

query Parameters

start	string <date-time> Start of an inclusive time range
end	string <date-time> End of an inclusive time range
tolerance	number >= 0 Minimum interval (in seconds) that ranges must be separated by to be considered discrete. Currently, the minimum meaningful value is 14s and smaller values will be clamped to this value.
deviceId	string Filter coverage by device ID
deviceName	string Name of device associated with the data
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
includeEdgeRecordings	boolean Default: false Include recordings from an Edge Site or Agent in the response. When edge recordings are included, each item in the response array will also include the `importStatus` for the coverage range.
importId	string Deprecated Filter coverage by import ID
recordingId	string Filter coverage by recording ID
recordingKey	string Filter coverage by recordingKey

Responses

Response Schema: application/json

Array

deviceId	string ID of device.
	object (DeviceSummary) Device summary.
start required	string <date-time> Start of this coverage
end required	string <date-time> End of this coverage
status required	string Deprecated Enum: "at-edge" "import-pending" "imported" The status of the coverage range
importStatus	string (RecordingImportStatus) Enum: "none" "pending" "importing" "failed" "complete" The import status of recordings. Status will be one of: `none`: The recording has not yet been imported, and import has not been requested. `pending`: Foxglove has received a request to import this recording. `importing`: The recording data is being processed for access via Foxglove. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent. The set of `importStatus` values may expand in the future.

Request samples

Python

from foxglove_data_platform.client import Client
from datetime import datetime, timedelta

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_coverage(
    start=datetime.now() - timedelta(hours=3),
    end=datetime.now() - timedelta(hours=1),
)

Response samples

Content type

application/json

[{"deviceId": "string",
"device": {"id": "string",
"name": "string"
},
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"status": "at-edge",
"importStatus": "none"
}
]

Custom Properties

Custom properties are typed metadata which you can assign to resources such as devices.

For example, you can create a device custom property identified with a key locationId and a type of string. This enables you to assign a location to each of your devices, view that data in Foxglove, and filter devices by a location ID.

List custom properties

Authorizations:

ApiKey

query Parameters

resourceType

string

Value: "device"

Filter properties matching a resource type

Responses

Response Schema: application/json

Array

id required	string ID of the custom property
key required	string [ 1 .. 32 ] characters ^[A-Za-z0-9_-]+$ An immutable identifier for this custom property; it cannot be edited once saved. This key is used to identify the custom property in queries; for example, when filtering your devices by a custom property ("partNumber:456").
label required	string [ 1 .. 32 ] characters Display label for user interfaces. May be changed after saving.
resourceType required	string Value: "device" Resource type to which this custom property may be assigned
valueType required	string Enum: "string" "number" "enum" "boolean" The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats.
values	Array of strings unique Allowed string values; required if `valueType` is "enum"

Response samples

Content type

application/json

[{"id": "string",
"key": "string",
"label": "string",
"resourceType": "device",
"valueType": "string",
"values": ["string"
]
}
]

Create a custom property

Authorizations:

ApiKey

Request Body schema: application/json
required

key required	string [ 1 .. 32 ] characters ^[A-Za-z0-9_-]+$ An immutable identifier for this custom property; it cannot be edited once saved. This key is used to identify the custom property in queries; for example, when filtering your devices by a custom property ("partNumber:456").
label required	string [ 1 .. 32 ] characters Display label for user interfaces. May be changed after saving.
resourceType required	string Value: "device" Resource type to which this custom property may be assigned
valueType required	string Enum: "string" "number" "enum" "boolean" The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats.
values	Array of strings unique Allowed string values; required if `valueType` is "enum"

Responses

Response Schema: application/json

id required	string ID of the custom property
key required	string [ 1 .. 32 ] characters ^[A-Za-z0-9_-]+$ An immutable identifier for this custom property; it cannot be edited once saved. This key is used to identify the custom property in queries; for example, when filtering your devices by a custom property ("partNumber:456").
label required	string [ 1 .. 32 ] characters Display label for user interfaces. May be changed after saving.
resourceType required	string Value: "device" Resource type to which this custom property may be assigned
valueType required	string Enum: "string" "number" "enum" "boolean" The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats.
values	Array of strings unique Allowed string values; required if `valueType` is "enum"

Request samples

Payload

Content type

application/json

{"key": "string",
"label": "string",
"resourceType": "device",
"valueType": "string",
"values": ["string"
]
}

Response samples

Content type

application/json

{"id": "string",
"key": "string",
"label": "string",
"resourceType": "device",
"valueType": "string",
"values": ["string"
]
}

Get a custom property

Authorizations:

ApiKey

path Parameters

required

string

Custom Property ID

Responses

Response Schema: application/json

id required	string ID of the custom property
key required	string [ 1 .. 32 ] characters ^[A-Za-z0-9_-]+$ An immutable identifier for this custom property; it cannot be edited once saved. This key is used to identify the custom property in queries; for example, when filtering your devices by a custom property ("partNumber:456").
label required	string [ 1 .. 32 ] characters Display label for user interfaces. May be changed after saving.
resourceType required	string Value: "device" Resource type to which this custom property may be assigned
valueType required	string Enum: "string" "number" "enum" "boolean" The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats.
values	Array of strings unique Allowed string values; required if `valueType` is "enum"

Response samples

Content type

application/json

{"id": "string",
"key": "string",
"label": "string",
"resourceType": "device",
"valueType": "string",
"values": ["string"
]
}

Edit a custom property

Authorizations:

ApiKey

path Parameters

required

string

Custom Property ID

Request Body schema: application/json
required

label	string [ 1 .. 32 ] characters Display label for user interfaces
values	Array of strings unique Reorder or add to enum values. Must be a superset of existing values.

Responses

Response Schema: application/json

id required	string ID of the custom property
key required	string [ 1 .. 32 ] characters ^[A-Za-z0-9_-]+$ An immutable identifier for this custom property; it cannot be edited once saved. This key is used to identify the custom property in queries; for example, when filtering your devices by a custom property ("partNumber:456").
label required	string [ 1 .. 32 ] characters Display label for user interfaces. May be changed after saving.
resourceType required	string Value: "device" Resource type to which this custom property may be assigned
valueType required	string Enum: "string" "number" "enum" "boolean" The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats.
values	Array of strings unique Allowed string values; required if `valueType` is "enum"

Request samples

Payload

Content type

application/json

{"label": "string",
"values": ["string"
]
}

Response samples

Content type

application/json

{"id": "string",
"key": "string",
"label": "string",
"resourceType": "device",
"valueType": "string",
"values": ["string"
]
}

Delete a custom property

Authorizations:

ApiKey

path Parameters

required

string

Custom Property ID

Responses

Response Schema: application/json

required

string

Response samples

Content type

application/json

{"id": "string"
}

Device Tokens

Device tokens are used by Foxglove device agents to authenticate to the API.

List device tokens

Authorizations:

ApiKey

query Parameters

deviceId

string

Filter by device ID

Responses

Response Schema: application/json

Array

id required	string
createdAt required	string <date-time> Timestamp of the device token's creation
deviceId required	string ID of the associated device
enabled required	boolean Whether this token is enabled or not

Response samples

Content type

application/json

[{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "string",
"enabled": true
}
]

Create a device token

You must have an Enterprise or Team account to create and use device tokens

Authorizations:

ApiKey

Request Body schema: application/json
required

deviceId

required

string

Device ID associated with the newly created token

Responses

Response Schema: application/json

id required	string
createdAt required	string <date-time> Timestamp of the device token's creation
deviceId required	string ID of the associated device
enabled required	boolean Whether this token is enabled or not
token	string Generated token. This is only available on creation.

Request samples

Payload

Content type

application/json

{"deviceId": "string"
}

Response samples

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "string",
"enabled": true,
"token": "string"
}

Get a device token

Authorizations:

ApiKey

path Parameters

required

string

Device token ID

Responses

Response Schema: application/json

id required	string
createdAt required	string <date-time> Timestamp of the device token's creation
deviceId required	string ID of the associated device
enabled required	boolean Whether this token is enabled or not

Response samples

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "string",
"enabled": true
}

Edit a device token

Authorizations:

ApiKey

path Parameters

required

string

Device token ID

Request Body schema: application/json
required

enabled

required

boolean

Enables or disables the device token.

Responses

Response Schema: application/json

id required	string
createdAt required	string <date-time> Timestamp of the device token's creation
deviceId required	string ID of the associated device
enabled required	boolean Whether this token is enabled or not

Request samples

Payload

Content type

application/json

{"enabled": true
}

Response samples

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "string",
"enabled": true
}

Delete a device token

Authorizations:

ApiKey

path Parameters

required

string

Device token ID

Responses

Response Schema: application/json

required

string

The device token ID

Response samples

Content type

application/json

{"id": "string"
}

Devices

Devices represent robots in your organization. It is common to have devices for both physical and virtual robots.

Devices are referenced by other resources like recordings, events, and imports.

List devices

Retrieve a list of devices.

Filtering by custom properties

Use the query parameter to filter devices on custom properties. Syntax:

properties.key:value: matches devices with a property that contains a key named key and its value is value
properties.key:value1,value2: matches devices with a property that contains a key named key and its value is either value1 or value2
properties.key:*: matches devices with a property that contains a key named key and any value
foo: matches devices with properties where any key or stringified value contains foo Multiple qualifiers can be used in the same query string; this will filter devices matching the intersection of the qualifiers (AND).

Authorizations:

ApiKey

query Parameters

sortBy	string Field to sort items by ("id", "name", or a custom property key prefixed with `properties.`)
query	string Space-separated query string for device custom properties. Each custom property key must be valid and prefixed with "properties.". See above for syntax and examples.
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

id required	string Opaque identifier
name required	string Organization-chosen device name
orgId	string
createdAt	string <date>
updatedAt	string <date-time>
retainRecordingsSeconds	number The retention period for recordings created on this device. If set to zero, recordings are retained indefinitely. This is only relevant for devices that have an agent installed.
	object A key-value map, where each key is one of your pre-defined device custom properties. Keys which are not recognized as custom properties will be ignored.

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_devices()

Response samples

Content type

application/json

[{"id": "string",
"name": "string",
"orgId": "string",
"createdAt": "2019-08-24",
"updatedAt": "2019-08-24T14:15:22Z",
"retainRecordingsSeconds": 0,
"properties": {"property1": "string",
"property2": "string"
}
}
]

Create a device

Authorizations:

ApiKey

Request Body schema: application/json
required

name required	string (deviceName) <= 100 characters ^[A-Za-z0-9_.-]+$ The name of the device.
	object A key-value map, where each key is one of your pre-defined device custom property keys. Keys which are not recognized as custom properties will be ignored.

Responses

Response Schema: application/json

id required	string Opaque identifier
name required	string Organization-chosen device name
orgId	string
createdAt	string <date>
updatedAt	string <date-time>
retainRecordingsSeconds	number The retention period for recordings created on this device. If set to zero, recordings are retained indefinitely. This is only relevant for devices that have an agent installed.
	object A key-value map, where each key is one of your pre-defined device custom properties. Keys which are not recognized as custom properties will be ignored.

Request samples

Payload
Python

Content type

application/json

{"name": "string",
"properties": {"property1": "string",
"property2": "string"
}
}

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"orgId": "string",
"createdAt": "2019-08-24",
"updatedAt": "2019-08-24T14:15:22Z",
"retainRecordingsSeconds": 0,
"properties": {"property1": "string",
"property2": "string"
}
}

Get a device

Get details on a specific device.

Authorizations:

ApiKeyNone

path Parameters

nameOrId

required

string

Device name or ID. Device names must be URI-encoded if they contain non-URI-safe characters. If a device is named with another device's ID, the device with the matching name will be returned.

Responses

Response Schema: application/json

id required	string Opaque identifier
name required	string Organization-chosen device name
orgId	string
createdAt	string <date>
updatedAt	string <date-time>
retainRecordingsSeconds	number The retention period for recordings created on this device. If set to zero, recordings are retained indefinitely. This is only relevant for devices that have an agent installed.
	object A key-value map, where each key is one of your pre-defined device custom properties. Keys which are not recognized as custom properties will be ignored.

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_device(
    device_id=device_id,
)

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"orgId": "string",
"createdAt": "2019-08-24",
"updatedAt": "2019-08-24T14:15:22Z",
"retainRecordingsSeconds": 0,
"properties": {"property1": "string",
"property2": "string"
}
}

Delete a device

Delete a device. Once a device is deleted, it will no longer show up in your list of devices.

Before deleting a device, you must delete all associated data.

Authorizations:

ApiKey

path Parameters

nameOrId

required

string

Device name or ID. Device names must be URI-encoded if they contain non-URI-safe characters. If a device is named with another device's ID, the device with the matching name will be returned.

Responses

Response Schema: application/json

required

string

The ID of the deleted device

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.delete_device(device_id=device_id)

Response samples

Content type

application/json

{"id": "string"
}

Update a device

Authorizations:

ApiKey

path Parameters

nameOrId

required

string

Device name or ID. Device names must be URI-encoded if they contain non-URI-safe characters. If a device is named with another device's ID, the device with the matching name will be returned.

Request Body schema: application/json
required

name	string Device names must be unique in your organization.
retainRecordingsSeconds	number >= 0 Optionally set a retention period for recordings created on this device. If set to zero, recordings are retained indefinitely. This is only relevant for devices that have an agent installed.
	object A key-value map, where each key is one of your pre-defined device custom property keys. Keys which are not recognized as custom properties will be ignored. Keys which are not included in the request, but exist on the device, will be unchanged. To unset a property, pass `null` as the value.

Responses

Response Schema: application/json

id required	string Opaque identifier
name required	string Organization-chosen device name
orgId	string
createdAt	string <date>
updatedAt	string <date-time>
retainRecordingsSeconds	number The retention period for recordings created on this device. If set to zero, recordings are retained indefinitely. This is only relevant for devices that have an agent installed.
	object A key-value map, where each key is one of your pre-defined device custom properties. Keys which are not recognized as custom properties will be ignored.

Request samples

Payload

Content type

application/json

{"name": "string",
"retainRecordingsSeconds": 0,
"properties": { }
}

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"orgId": "string",
"createdAt": "2019-08-24",
"updatedAt": "2019-08-24T14:15:22Z",
"retainRecordingsSeconds": 0,
"properties": {"property1": "string",
"property2": "string"
}
}

Events

Adding events can help you quickly identify, categorize, and search for points of interest in your data. Each event is tied to a device and time span, and can contain metadata.

You can list events by devices, time ranges, and metadata.

List events

Retrieve a list of events.

Use the query parameter to filter events on key/value criteria.

Syntax:

key:value: matches events with metadata that contains a key named key with a value of value
key:value1,value2: matches events with metadata that contains a key named key with a value of either value1 or value2
key:*: matches events where any metadata that contains a key named key
*:value: matches events where any metadata that contains value as a value
foo: matches events with metadata where any key or value string contains foo

Multiple qualifiers can be used in the same query string; this will filter events where metadata matches the intersection of the qualifiers (AND).

Examples:

key1:value1 key2:value2: matches metadata that contains both a key named key1 with its value value1 and another key named key2 with its value value2
key:"value with spaces": matches metadata with a key named key and its value value with spaces
key:value foo: matches metadata that contains both a key named key with its value value and any key or value that contains the text foo

Note: The start and end query arguments will find any events which intersect the query range (inclusive of start and end).

Authorizations:

ApiKey

query Parameters

start	string <date-time> Start of an inclusive time range
end	string <date-time> End of an inclusive time range
createdAfter	string <date-time> Return all events created after this date and time
updatedAfter	string <date-time> Return all events updated after this date and time
deviceId	string Filter events matching device ID
deviceName	string Name of device associated with the event
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
query	string Event query string. Comprises a space-separated list of event queries, where the syntax of those queries is described above.
sortBy	string Enum: "id" "deviceId" "deviceName" "device.name" "device.id" "start" "createdAt" "updatedAt" field to sort response items by
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

id required	string ID of the event
start required	string <date-time> Event start time (inclusive)
end required	string <date-time> Event end time (inclusive)
deviceId	string ID of the device associated with the event
	object (DeviceSummary) ID and name of a device.
required	object Any metadata associated with the event
createdAt required	string <date-time> When the event was created
updatedAt required	string <date-time> When the event was last updated

Request samples

Python

from foxglove_data_platform.client import Client
from datetime import datetime, timedelta

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_events(
    device_id=device_id,
    sort_by=sort_by,
    sort_order=sort_order,
    limit=limit,
    offset=offset,
    start=datetime.now() - timedelta(hours=3),
    end=datetime.now() - timedelta(hours=1),
    query="key:val"
)

Response samples

Content type

application/json

[{"id": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"deviceId": "string",
"device": {"id": "string",
"name": "string"
},
"metadata": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Create an event

Create a new event.

Note: Creating an new event currently requires a device ID or device name, however the device field on the Event resource responses is optional to allow future API expansion for attaching events to other types of resources.

Authorizations:

ApiKey

Request Body schema: application/json
required

deviceId	string ID of the device to associate with the event
deviceName	string Name of the device to associate with the event
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
	object An object with user-defined string keys and string values; key order is not preserved
start required	string <date-time> Event start time (inclusive)
end required	string <date-time> Event end time (inclusive)

Responses

Response Schema: application/json

id required	string ID of the event
start required	string <date-time> Event start time (inclusive)
end required	string <date-time> Event end time (inclusive)
deviceId	string ID of the device associated with the event
	object (DeviceSummary) ID and name of a device.
required	object Any metadata associated with the event
createdAt required	string <date-time> When the event was created
updatedAt required	string <date-time> When the event was last updated

Request samples

Payload
Python

Content type

application/json

{"deviceId": "string",
"deviceName": "string",
"device.id": "string",
"device.name": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"id": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"deviceId": "string",
"device": {"id": "string",
"name": "string"
},
"metadata": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get an event

Authorizations:

ApiKey

path Parameters

required

string

ID of the event

Responses

Response Schema: application/json

id required	string ID of the event
start required	string <date-time> Event start time (inclusive)
end required	string <date-time> Event end time (inclusive)
deviceId	string ID of the device associated with the event
	object (DeviceSummary) ID and name of a device.
required	object Any metadata associated with the event
createdAt required	string <date-time> When the event was created
updatedAt required	string <date-time> When the event was last updated

Response samples

Content type

application/json

{"id": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"deviceId": "string",
"device": {"id": "string",
"name": "string"
},
"metadata": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete an event

Authorizations:

ApiKey

path Parameters

required

string

ID of the event

Responses

Response Schema: application/json

required

string

ID of the deleted event

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.delete_event(
    event_id=event_id,
)

Response samples

Content type

application/json

{"id": "string"
}

Update an event

Authorizations:

ApiKey

path Parameters

required

string

ID of the event

Request Body schema: application/json
required

	object An object with user-defined string keys and string values; key order is not preserved
start	string <date-time> Event start time (inclusive)
end	string <date-time> Event end time (inclusive)

Responses

Response Schema: application/json

id required	string ID of the event
start required	string <date-time> Event start time (inclusive)
end required	string <date-time> Event end time (inclusive)
deviceId	string ID of the device associated with the event
	object (DeviceSummary) ID and name of a device.
required	object Any metadata associated with the event
createdAt required	string <date-time> When the event was created
updatedAt required	string <date-time> When the event was last updated

Request samples

Payload

Content type

application/json

{"metadata": {"property1": "string",
"property2": "string"
},
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"id": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"deviceId": "string",
"device": {"id": "string",
"name": "string"
},
"metadata": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Imports

The Imports endpoints are deprecated. Use the Recordings endpoints instead.

Imports are recordings that are available at a Primary Site.

List imports Deprecated

This endpoint is deprecated. Use the list recordings endpoint instead.

Authorizations:

ApiKey

query Parameters

deviceId	string ID of device associated with the exported data
filename	string Filename to match
start	string <date-time> Inclusive start of import time
end	string <date-time> Inclusive end of import time
dataStart	string <date-time> Inclusive start of message log time
dataEnd	string <date-time> Inclusive end of message log time
sortBy	string Enum: "importId" "deviceId" "importTime" "dataStart" "dataEnd" Sort by a single field of the import type
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

id required	string Opaque ID
importId required	string Deprecated
orgId required	string
deviceId	string
deviceName	string
filename required	string
importTime required	string <date-time> Imported timestamp
start required	string <date-time> Message log time start of imported data
end required	string <date-time> Message log time end of imported data
inputType	string Supported input type: ROS 1 bag ("bag1") or MCAP v0.x ("mcap0") file
outputType	string Supported output type: ROS 1 bag ("bag1") or MCAP v0.x ("mcap0") file
inputSize	number <bigint> Size in bytes of the uploaded file
totalOutputSize	number <bigint> Size in bytes of the data after processing
date	string Message log time start date in YYYYMMDD format e.g. 20170322
deleted	boolean

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_imports()

Response samples

Content type

application/json

[{"id": "string",
"importId": "string",
"orgId": "string",
"deviceId": "string",
"deviceName": "string",
"filename": "string",
"importTime": "2019-08-24T14:15:22Z",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"inputType": "string",
"outputType": "string",
"inputSize": 0,
"totalOutputSize": 0,
"date": "string",
"deleted": true
}
]

Delete multiple imports Deprecated

Deletes multiple imports by ID. Returns an array of result objects, which indicate whether a given import was successfully deleted. An import that has already been deleted will result in "notFound". Note: All imports must belong to the same site. If any import belongs to a different site, the entire request is rejected with a 400 response.

Authorizations:

ApiKey

query Parameters

required

Array of strings <= 50 items

ID of import to delete. You can specify up to 50 IDs (for example, ?id=abc&id=def&...).

Responses

Response Schema: application/json

required

Array of objects

Array

importId required	string The import ID that was provided
result required	string Enum: "success" "notFound" The result of the deletion attempt.

Response samples

Content type

application/json

{"deletionResults": [{"importId": "string",
"result": "success"
}
]
}

Delete an import Deprecated

This endpoint is deprecated. Use the delete recording endpoint instead.

Deleting an import deletes all data associated with the import.

This action is permanent and cannot be undone.

Authorizations:

ApiKey

path Parameters

importId

required

string

The importId of an import

query Parameters

deviceId

string

Deprecated

The deviceId from the import record

Responses

Response Schema: application/json

required

string

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.delete_import(
    device_id=device_id,
    import_id=import_id,
)

Response samples

Content type

application/json

{"id": "string"
}

Lake files

MCAP files stored in the lake bucket of a self-hosted Primary Site. You must have an Enterprise account to use lake file endpoints.

List lake files

This endpoint returns a list of MCAP files in the lake bucket for a given Primary Site.

For each recording that has been imported, multiple files are created — one per topic.

This endpoint is only supported for self-managed sites.

A query must be limited to a device or recording using one of the following parameters:

deviceId
deviceName
recordingId
recordingKey

If querying by a device (ID or name), you must also provide start and end parameters to limit the range of files included.

The range expressed by start and end must not exceed 24h.

Authorizations:

ApiKey

query Parameters

siteId required	string The ID of a self-managed Primary Site for which the files have been imported
deviceId	string ID of the device associated with the imported files
deviceName	string Name of the device associated with the imported files
recordingId	string A recording ID for which the files have been imported
recordingKey	string A recording key for which the files have been imported
start	string <date-time> Inclusive start of an imported recording's time range. If start is provided, end must be too.
end	string <date-time> Inclusive end of an imported recording's time range. If end is provided, start must be too.
topic	string Include only imported files matching this topic name

Responses

Response Schema: application/json

Array

path required	string The full path of the file in the lake bucket
topics required	Array of strings The topic names associated with this file

Response samples

Content type

application/json

[{"path": "string",
"topics": ["string"
]
}
]

Recording Attachments

A recording attachment resource represents information about an MCAP attachment imported to Foxglove.

Attachments are available for individual download or with their recording.

List attachments

Authorizations:

ApiKey

query Parameters

recordingId	string filter by recording ID
siteId	string filter by Primary Site ID
deviceId	string filter by device ID
deviceName	string filter by device name
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
sortBy	string Value: "logTime" Sort by a single field of the attachment
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

id required	string ID of the attachment
recordingId required	string ID of the recording with which the attachment is associated
siteId required	string ID of the Primary Site where the attachment data is stored
name required	string Name field from the attachment record
mediaType required	string Media type from the attachment record
logTime required	string Log time field from the attachment record
createTime required	string Create time field from the attachment record
crc required	number CRC field from the attachment record as a decimal number
size required	integer Size of the attachment in bytes
fingerprint required	string A hash of the attachment content (algorithm subject to change). Two attachments with the same fingerprint will have identical content.
lakePath	string Path of attachment in lake storage. Only provided for self-hosted Primary Sites.

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_attachments()

Response samples

Content type

application/json

[{"id": "string",
"recordingId": "string",
"siteId": "string",
"name": "string",
"mediaType": "string",
"logTime": "string",
"createTime": "string",
"crc": 0,
"size": 0,
"fingerprint": "string",
"lakePath": "string"
}
]

Get an attachment

Authorizations:

ApiKeyNone

path Parameters

required

string

ID of the attachment

Responses

Response Schema: application/json

id required	string ID of the attachment
recordingId required	string ID of the recording with which the attachment is associated
siteId required	string ID of the Primary Site where the attachment data is stored
name required	string Name field from the attachment record
mediaType required	string Media type from the attachment record
logTime required	string Log time field from the attachment record
createTime required	string Create time field from the attachment record
crc required	number CRC field from the attachment record as a decimal number
size required	integer Size of the attachment in bytes
fingerprint required	string A hash of the attachment content (algorithm subject to change). Two attachments with the same fingerprint will have identical content.
lakePath	string Path of attachment in lake storage. Only provided for self-hosted Primary Sites.

Response samples

Content type

application/json

{"id": "string",
"recordingId": "string",
"siteId": "string",
"name": "string",
"mediaType": "string",
"logTime": "string",
"createTime": "string",
"crc": 0,
"size": 0,
"fingerprint": "string",
"lakePath": "string"
}

Download an attachment

To download an attachment make a request to this endpoint and follow the 302 redirect. The attachment will download directly from the Primary Site.

Note: The redirect link expires after 15 minutes.

Authorizations:

ApiKey

path Parameters

required

string

ID of the attachment to download

Responses

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

bytes = client.download_attachment(id='att_0dHT6ZvqJhfwOcml')

Recordings

A recording is a resource representing the content of an MCAP file or ROS bag managed by Data Platform.

List recordings

Authorizations:

ApiKey

query Parameters

start	string <date-time> Start of inclusive time range: return all recordings with data on or after this value
end	string <date-time> End of inclusive time range: return all recordings with data on or before this value
path	string Filter response to recordings with this path
site.id	string Filter response to recordings stored at the Primary Site with this ID
edgeSite.id	string Filter response to recordings stored at the Edge Site with this ID
deviceId	string Filter response to recordings for the device with this ID
deviceName	string Filter response to recordings for the device with this name
topic	string Filter response to recordings containing the topic
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
importStatus	string Enum: "none" "pending" "importing" "failed" "complete" Filter response to recordings with this import status
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results
sortBy	string Enum: "deviceName" "device.name" "createdAt" "start" "end" "duration" "path" "importedAt" Sort returned recordings by a field in the response type. Specifying `duration` sorts by the duration between the recording `start` and `end` fields.
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field

Responses

Response Schema: application/json

Array

id required	string ID of the recording
path required	string filepath of the recording as it was originally provided to Foxglove. for recordings originated at the edge, this is the full path of the recording file in the edge controller store. For recordings uploaded directly to Foxglove, this is the `filename` query arg provided to `/data/upload`.
size required	number <bigint> Size of the recording file in bytes
createdAt required	string <date-time> Timestamp when the recording file was added to Foxglove.
importedAt	string <date-time> Timestamp when the recording was imported to a primary site.
start required	string <date> log time of first message in the recording.
end required	string <date> log time of last message in the recording.
importStatus required	string (RecordingImportStatus) Enum: "none" "pending" "importing" "failed" "complete" The import status of recordings. Status will be one of: `none`: The recording has not yet been imported, and import has not been requested. `pending`: Foxglove has received a request to import this recording. `importing`: The recording data is being processed for access via Foxglove. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent. The set of `importStatus` values may expand in the future.
	object (SiteSummary) The primary site for this recording.
	object (SiteSummary) The edge site for this recording.
	object (DeviceSummary) ID and name of a device.
	Array of objects (RecordingMetadata) The metadata records of the original MCAP file content

Request samples

Python

from foxglove_data_platform.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_recordings()

Response samples

Content type

application/json

[{"id": "string",
"path": "string",
"size": 0,
"createdAt": "2019-08-24T14:15:22Z",
"importedAt": "2019-08-24T14:15:22Z",
"start": "2019-08-24",
"end": "2019-08-24",
"importStatus": "none",
"site": {"id": "string",
"name": "string"
},
"edgeSite": {"id": "string",
"name": "string"
},
"device": {"id": "string",
"name": "string"
},
"metadata": [{"name": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}
]
}
]

Get a recording

Get details on a specific recording.

Authorizations:

ApiKey

path Parameters

keyOrId

required

string

Recording ID

Responses

Response Schema: application/json

id required	string ID of the recording
path required	string filepath of the recording as it was originally provided to Foxglove. for recordings originated at the edge, this is the full path of the recording file in the edge controller store. For recordings uploaded directly to Foxglove, this is the `filename` query arg provided to `/data/upload`.
size required	number <bigint> Size of the recording file in bytes
createdAt required	string <date-time> Timestamp when the recording file was added to Foxglove.
importedAt	string <date-time> Timestamp when the recording was imported to a primary site.
start required	string <date> log time of first message in the recording.
end required	string <date> log time of last message in the recording.
importStatus required	string (RecordingImportStatus) Enum: "none" "pending" "importing" "failed" "complete" The import status of recordings. Status will be one of: `none`: The recording has not yet been imported, and import has not been requested. `pending`: Foxglove has received a request to import this recording. `importing`: The recording data is being processed for access via Foxglove. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent. The set of `importStatus` values may expand in the future.
	object (SiteSummary) The primary site for this recording.
	object (SiteSummary) The edge site for this recording.
	object (DeviceSummary) ID and name of a device.
	Array of objects (RecordingMetadata) The metadata records of the original MCAP file content

Response samples

Content type

application/json

{"id": "string",
"path": "string",
"size": 0,
"createdAt": "2019-08-24T14:15:22Z",
"importedAt": "2019-08-24T14:15:22Z",
"start": "2019-08-24",
"end": "2019-08-24",
"importStatus": "none",
"site": {"id": "string",
"name": "string"
},
"edgeSite": {"id": "string",
"name": "string"
},
"device": {"id": "string",
"name": "string"
},
"metadata": [{"name": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}
]
}

Delete a recording

Deletes a recording. Deleting a recording also deletes the data for that recording (including attachments, messages, metadata, etc).

Note: For recordings stored at an Edge Site, this method deletes only the imported data for that recording, leaving the edge copy intact.

Authorizations:

ApiKey

path Parameters

keyOrId

required

string

Recording ID

Responses

Response Schema: application/json

recordingId

required

string

The recording ID

Response samples

Content type

application/json

{"recordingId": "string"
}

Import from edge

Request import of a recording from an Edge Site to a Primary Site. Importing a recording makes the data (messages, metadata, attachments, etc.) available for download and streaming.

If the recording is successfully queued for import, is already imported, or already queued for import, this endpoint will return a 200 response and include the recording ID and the importStatus.

An import status of complete indicates the recording is already imported. Poll the GET v1/recordings/{id} endpoint to observe changes to the importStatus.

If the recording cannot be found or is unavailable for import because the edge copy or site is deleted, this endpoint will return a 404 response.

Authorizations:

ApiKey

path Parameters

keyOrId

required

string

Recording ID

Responses

Response Schema: application/json

string

Recording ID

importStatus

string (RecordingImportStatus)

Enum: "none" "pending" "importing" "failed" "complete"

The import status of recordings. Status will be one of:

none: The recording has not yet been imported, and import has not been requested.
pending: Foxglove has received a request to import this recording.
importing: The recording data is being processed for access via Foxglove.
failed: The recording data could not be imported.
complete: The contents of the recording are available for access via Foxglove.

Note: none and pending statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent.

The set of importStatus values may expand in the future.

Response samples

Content type

application/json

{"id": "string",
"importStatus": "none"
}

List pending imports

List the pending imports. These are in-progress import jobs for newly uploaded recordings.

Authorizations:

ApiKey

query Parameters

requestId	string A specific import request ID
key	string The unique key optionally provided when importing
deviceId	string ID of device associated with the pending import
deviceName	string Name of device associated with the pending import
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
error	string A string to filter based on error messages
filename	string Filename to exactly match
updatedSince	string <date-time> Filter pending imports updated since this time
showCompleted	boolean Default: false Include completed requests
showQuarantined	boolean Default: false Include quarantined requests
siteId	string Filter response to imports at site with this ID
sortBy	string Enum: "createdAt" "deviceId" "deviceName" "device.name" "device.id" "error" "importId" "requestId" "updatedAt" Sort by a single field of the import type
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

createdAt required	string <date-time> When the pending import was created
deviceId	string ID of device
deviceName	string Name of the device from which the import originated
error	string Error message, if status is "error"
filename required	string Filename of the import
importId	string ID of import; undefined until status is "complete"
orgId required	string ID of org to which the import belongs
pipelineStage required	string stage in the import pipeline the import currently occupies
requestId required	string ID of the import request
siteId required	string ID of Primary Site where import will be stored
status	string Enum: "received" "processing" "ready for indexing" "error" "complete" Status of initiated import
updatedAt required	string <date-time> When the pending import was last updated
quarantinedAt	string <date-time> When the pending import was quarantined

Response samples

Content type

application/json

[{"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "string",
"deviceName": "string",
"error": "string",
"filename": "string",
"importId": "string",
"orgId": "string",
"pipelineStage": "string",
"requestId": "string",
"siteId": "string",
"status": "received",
"updatedAt": "2019-08-24T14:15:22Z",
"quarantinedAt": "2019-08-24T14:15:22Z"
}
]

Upload a recording

Use this endpoint to upload data to your foxglove-hosted site. The upload is a two-request process.

Make a request to this upload endpoint to create an upload link.
Issue a PUT HTTP request to the link response field URL.

Your PUT request header should have Content-Type: application/octet-stream, and your request body should contain your file content.

Note: If you are using a self-hosted site, see this guide for uploading data.

Authorizations:

ApiKeyNoneNone

Request Body schema: application/json
required

In addition to filename, one of deviceId, deviceName, or key is required.

deviceId	string Foxglove ID of the associated device
deviceName	string Unique name of the associated device. If no device exists with this name, the device will be created.
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
filename required	string Name of the file that will be uploaded
key	string non-empty A unique key to identify the recording

Responses

Response Schema: application/json

link required	string A signed upload URL. Upload your data to this URL using a PUT request.
requestId required	string

Request samples

Payload
Python

Content type

application/json

{"deviceId": "string",
"deviceName": "string",
"device.name": "string",
"device.id": "string",
"filename": "string",
"key": "string"
}

Response samples

Content type

application/json

{"link": "string",
"requestId": "string"
}

Site Tokens

Site tokens are credentials a self-hosted Primary Site or Edge Site use to communicate with the Foxglove API.

List site tokens

Authorizations:

ApiKey

query Parameters

siteId

string

Filter by site ID

Responses

Response Schema: application/json

Array

id required	string ID of the site token
createdAt required	string <date-time> Timestamp of the site token's creation
siteId required	string ID of the associated Primary or Edge Site

Response samples

Content type

application/json

[{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"siteId": "string"
}
]

Create a site token

Authorizations:

ApiKey

Request Body schema: application/json
required

siteId

required

string

Site associated with the newly created token

Responses

Response Schema: application/json

id required	string ID of the site token
createdAt required	string <date-time> Timestamp of the site token's creation
siteId required	string ID of the associated Primary or Edge Site
token	string Generated token. This is only available on creation.

Request samples

Payload

Content type

application/json

{"siteId": "string"
}

Response samples

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"siteId": "string",
"token": "string"
}

Delete a site token

Authorizations:

ApiKey

path Parameters

required

string

Site token ID

Responses

Response Schema: application/json

success

required

boolean

Value: true

Response samples

Content type

application/json

{"success": true
}

Sites

A site is a logical grouping of storage and compute for storing Recording data.

List sites

Retrieve a list of sites.

Authorizations:

ApiKey

Responses

Response Schema: application/json

Array

id required	string Unique identifier for this site
name required	string Name for this site
type required	string Enum: "foxglove-hosted" "self-hosted" "edge" The type of the site. `foxglove-hosted`: A Foxglove-hosted Primary Site. `self-hosted`: A self-hosted Primary Site. `edge`: An Edge Site.
url	string The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites).
retainRecordingsSeconds	number >= 0 An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

Response samples

Content type

application/json

[{"id": "string",
"name": "string",
"type": "foxglove-hosted",
"url": "string",
"retainRecordingsSeconds": 0
}
]

Create a Site

Create a new site.

Authorizations:

ApiKey

Request Body schema: application/json
required

name required	string A name for this site
type required	string Value: "edge" The type of site to create.
retainRecordingsSeconds	number >= 0 Optionally set a retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

Responses

Response Schema: application/json

id required	string Unique identifier for this site
name required	string Name for this site
type required	string Enum: "foxglove-hosted" "self-hosted" "edge" The type of the site. `foxglove-hosted`: A Foxglove-hosted Primary Site. `self-hosted`: A self-hosted Primary Site. `edge`: An Edge Site.
url	string The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites).
retainRecordingsSeconds	number >= 0 An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

Request samples

Payload

Content type

application/json

{"name": "string",
"type": "edge",
"retainRecordingsSeconds": 0
}

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"type": "foxglove-hosted",
"url": "string",
"retainRecordingsSeconds": 0
}

Get site details

Get details for a specific site.

Authorizations:

ApiKey

path Parameters

required

string

Site ID

Responses

Response Schema: application/json

id required	string Unique identifier for this site
name required	string Name for this site
type required	string Enum: "foxglove-hosted" "self-hosted" "edge" The type of the site. `foxglove-hosted`: A Foxglove-hosted Primary Site. `self-hosted`: A self-hosted Primary Site. `edge`: An Edge Site.
url	string The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites).
retainRecordingsSeconds	number >= 0 An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"type": "foxglove-hosted",
"url": "string",
"retainRecordingsSeconds": 0
}

Update site details

Update the name or retention period for a Site.

Authorizations:

ApiKey

path Parameters

required

string

Site ID

Request Body schema: application/json
required

name	string A name for this site
retainRecordingsSeconds	number Optionally set a retention period for recordings created at this Edge Site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)
url	string The URL a self-hosted Primary Site exposes for accessing available data. See The self-hosting installation guide for details.

Responses

Response Schema: application/json

id required	string Unique identifier for this site
name required	string Name for this site
type required	string Enum: "foxglove-hosted" "self-hosted" "edge" The type of the site. `foxglove-hosted`: A Foxglove-hosted Primary Site. `self-hosted`: A self-hosted Primary Site. `edge`: An Edge Site.
url	string The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites).
retainRecordingsSeconds	number >= 0 An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

Request samples

Payload

Content type

application/json

{"name": "string",
"retainRecordingsSeconds": 0,
"url": "string"
}

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"type": "foxglove-hosted",
"url": "string",
"retainRecordingsSeconds": 0
}

Delete a site

Delete a site.

NOTE: Site deletion is permanent and cannot be undone. Any recordings stored at this site will no longer be available through Foxglove.

For edge and self-hosted sites, you should shut down your deployment before deleting the site through the API.

If the site type is self-hosted, the contents of your inbox and lake buckets will not be affected by this action, and should be cleaned up separately after deleting the site.

If the site type is edge, any files in edge storage will not be affected by this action.

Authorizations:

ApiKey

path Parameters

required

string

Site ID

Responses

Response Schema: application/json

required

string

ID of the deleted site

Response samples

Content type

application/json

{"id": "string"
}

Stream data

Download data

This endpoint returns a link URL where you can download your data as an .mcap or .bag file.

To download your data:

Make a request to this endpoint.
Make a GET request to the link URL.

One of recordingId, key, importId (deprecated) or all three of deviceId/deviceName, start, and end must be specified.

Note: You can only export a .bag file if you originally uploaded a .bag file.

Authorizations:

ApiKey

Request Body schema: application/json
required

topics	Array of strings List of topics to include in the exported file (defaults to all topics)
outputFormat	string Enum: "bag1" "mcap" "mcap0" Output file format. `bag1` - output a .bag file `mcap` - output a .mcap file `mcap0` - Deprecated. Use `mcap`.
includeAttachments	boolean Include attachments in streamed data. One of `recordingId` or `importId` (deprecated) must also be set. Only valid for mcap outputFormat.
isHosted	boolean true if the import is hosted
replayLookbackSeconds	number >= 0 time in seconds to look back before start
replayPolicy	string Enum: "lastPerChannel" "" replay policy
deviceId	string ID of device associated with the exported data
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
deviceName	string Name of device associated with the exported data.
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
start	string <date-time> Inclusive start of requested time range. If start is provided, end must be too.
end	string <date-time> Inclusive end of requested time range. If end is provided, start must be too.
importId	string Deprecated ID of the import to stream
recordingId	string ID of the recording to stream
recordingKey	string Key of recording to stream
key	string Deprecated Key of recording to stream

Responses

Response Schema: application/json

link

required

string

A signed url to access the data. This link expires after 15 seconds.

Request samples

Payload
Python

Content type

application/json

{"topics": ["string"
],
"outputFormat": "bag1",
"includeAttachments": true,
"isHosted": true,
"replayLookbackSeconds": 0,
"replayPolicy": "lastPerChannel",
"deviceId": "string",
"device.id": "string",
"deviceName": "string",
"device.name": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"importId": "string",
"recordingId": "string",
"recordingKey": "string",
"key": "string"
}

Response samples

Content type

application/json

{"link": "string"
}

Topics

Topics provide schema information for messages in the data source.

List topics

Get a list of topics available for a device within a given time range.

By default, this endpoint will not return the schema for each topic. To include the schemas, you must provide the includeSchemas query parameter.

Use start and end to limit the response to overlapping recording ranges.

Authorizations:

ApiKey

query Parameters

start	string <date-time> Return all topics appearing in recordings ending on or after `start`
end	string <date-time> Return all topics appearing in recordings starting on or before `end` (updated March 2024 to be `<=` instead of `<`)
importId	string Deprecated ID of the import from which to list topics
recordingId	string ID of the recording from which to list topics
recordingKey	string Key of the recording from which to list topics
deviceId	string ID of device being queried
device.name	string Deprecated Equivalent to deviceName, and ignored if deviceName is supplied
deviceName	string Name of device being queried
device.id	string Deprecated Equivalent to deviceId, and ignored if deviceId is supplied
includeSchemas	boolean Default: false Whether full schemas should be included in the response
sortBy	string Enum: "topic" "version" Sort by a single field of the topic type ("topic" or "version")
sortOrder	string Enum: "asc" "desc" Sort order for the `sortBy` field
limit	number [ 0 .. 2000 ] Default: 2000 Maximum number of items to return
offset	integer >= 0 Default: 0 Number of items to skip before returning the results

Responses

Response Schema: application/json

Array

encoding required	string Encoding of the topic
schema	string Full schema, base-64 encoded; included only if the request's includeSchemas is true
schemaEncoding required	string Encoding of the topic schema
schemaName required	string Name of the topic schema
topic required	string Topic name
version required	string Topic version

Request samples

Python

from foxglove_data_platform.client import Client
from datetime import datetime, timedelta

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_topics(
    device_id=device_id,
    start=datetime.now() - timedelta(hours=3),
    end=datetime.now() - timedelta(hours=1),
)

Response samples

Content type

application/json

[{"encoding": "string",
"schema": "string",
"schemaEncoding": "string",
"schemaName": "string",
"topic": "string",
"version": "string"
}
]

Webhook Payloads

Webhooks send POST request notifications to your HTTPS endpoint when events occur within Foxglove. This section describes the JSON request body format your endpoint should expect for each event type.

recording.created

recording.created events occur when a recording is created. Recordings are created when a file is uploaded, added to Edge Site storage, or created on a device that runs the Foxglove Agent.

type required	string The event type Value: "recording.created"
timestamp required	string <date-time> When the webhook event occurred
attemptedAt required	string <date-time> When the delivery was attempted
webhookEventId required	string ID of the associated webhook event
webhookId required	string ID of the webhook that notified your endpoint
required	object

{"type": "recording.created",
"timestamp": "2019-08-24T14:15:22Z",
"attemptedAt": "2019-08-24T14:15:22Z",
"webhookEventId": "string",
"webhookId": "string",
"recording": {"id": "string",
"key": "string",
"importStatus": "none",
"path": "string",
"device": {"id": "string",
"name": "string"
},
"edgeSite": {"id": "string",
"name": "string"
},
"site": {"id": "string",
"name": "string"
}
}
}

recording.imported

recording.imported events occur when a recording is imported and is ready for streaming.

type required	string The event type Value: "recording.imported"
timestamp required	string <date-time> When the webhook event occurred
attemptedAt required	string <date-time> When the delivery was attempted
webhookEventId required	string ID of the associated webhook event
webhookId required	string ID of the webhook that notified your endpoint
required	object

{"type": "recording.imported",
"timestamp": "2019-08-24T14:15:22Z",
"attemptedAt": "2019-08-24T14:15:22Z",
"webhookEventId": "string",
"webhookId": "string",
"recording": {"id": "string",
"key": "string",
"importStatus": "none",
"path": "string",
"device": {"id": "string",
"name": "string"
},
"edgeSite": {"id": "string",
"name": "string"
},
"site": {"id": "string",
"name": "string"
}
}
}

device.created

device.created events occur when a new Device is created.

type required	string The event type Value: "device.created"
timestamp required	string <date-time> When the webhook event occurred
attemptedAt required	string <date-time> When the delivery was attempted
webhookEventId required	string ID of the associated webhook event
webhookId required	string ID of the webhook that notified your endpoint
required	object

{"type": "device.created",
"timestamp": "2019-08-24T14:15:22Z",
"attemptedAt": "2019-08-24T14:15:22Z",
"webhookEventId": "string",
"webhookId": "string",
"device": {"id": "string"
}
}

event.created

event.created events occur when a new Event is created in Foxglove.

type required	string The event type Value: "event.created"
timestamp required	string <date-time> When the webhook event occurred
attemptedAt required	string <date-time> When the delivery was attempted
webhookEventId required	string ID of the associated webhook event
webhookId required	string ID of the webhook that notified your endpoint
required	object

{"type": "event.created",
"timestamp": "2019-08-24T14:15:22Z",
"attemptedAt": "2019-08-24T14:15:22Z",
"webhookEventId": "string",
"webhookId": "string",
"event": {"id": "string"
}
}

ping

The ping event type is used to test webhook connectivity.

type required	string The event type Value: "ping"
timestamp required	string <date-time> When the webhook event occurred
attemptedAt required	string <date-time> When the delivery was attempted
webhookEventId required	string ID of the associated webhook event
webhookId required	string ID of the webhook that notified your endpoint
	object

{"type": "ping",
"timestamp": "2019-08-24T14:15:22Z",
"attemptedAt": "2019-08-24T14:15:22Z",
"webhookEventId": "string",
"webhookId": "string",
"webhook": {"id": "string"
}
}

Extensions

Publish an extension

Available on Free, Team, and Enterprise plans

Publish a new Foxglove extension or an updated version of an existing extension. When uploaded, the extension will automatically be installed for users in your organization.

See our packaging tool create-foxglove-extension for more information on how to create an extension.

Read the docs for more information on Foxglove extensions.

Authorizations:

ApiKey

Request Body schema: application/octet-stream
required

The request headers must contain Content-Type: application/octet-stream. The request body must contain the contents of your (.foxe) extension file. All other information about the extension will be parsed from the package.json file.

package.json requirements

An extension is uniquely identified by its publisher and name, which are both required in your package.json. Both values are case-insensitive, so a package named custompanel would be the same as one named CustomPanel.

To update an extension, change its version in package.json, create a new .foxe bundle, and upload it via this endpoint. Version numbers must be unique to each extension. There are no other restrictions on versioning schemes.

To publish an extension to your organization, your package.json must define a displayName. This is displayed to users in your organization.

Once an extension is uploaded, its displayName may not be changed by future versions.

string <binary>

Responses

Response Schema: application/json

required

string

Response samples

Content type

application/json

{"id": "string"
}

List extensions

Organization admins can share and manage Foxglove extensions. Check out the docs to learn more.

Authorizations:

ApiKey

Responses

Response Schema: application/json

Array

id required	string Assigned by backend
name required	string Name as it appears in your package.json
publisher required	string Publisher as it appears in your package.json
displayName required	string Display name as it appears in your package.json
description required	string or null Description as it appears in the active version's package.json
activeVersion required	string or null Version string as it appears in the active version's package.json
sha256Sum required	string or null SHA-256 sum of the active version contents, encoded as hex

Response samples

Content type

application/json

[{"id": "string",
"name": "string",
"publisher": "string",
"displayName": "string",
"description": "string",
"activeVersion": "string",
"sha256Sum": "string"
}
]

Get an extension

Authorizations:

ApiKey

path Parameters

required

string

Extension ID

Responses

Response Schema: application/json

foxe

required

string

Signed download link for the extension

Response samples

Content type

application/json

{"foxe": "string"
}

Delete an extension

Once deleted, the extension will no longer be available within your organization.

Authorizations:

ApiKey

path Parameters

required

string

Extension ID

Responses

Response Schema: application/json

required

string

The ID of the deleted extension

Response samples

Content type

application/json

{"id": "string"
}

Layouts

List layouts

List the org layouts.

Note: Only layouts shared with the org are returned in the response; no personal layouts are returned.

Authorizations:

ApiKey

query Parameters

updatedSince	string <date-time> Return only layouts updated since this time.
includeData	boolean Default: true When set to false, the `data` field is omitted from the response items. This can be used to limit bandwidth when querying many Layouts.

Responses

Response Schema: application/json

Array

id required	string ID of the layout
name required	string Name of the layout
createdAt required	string <date-time> Timestamp when the layout was created on the server
updatedAt required	string <date-time> Timestamp when the layout was last updated on the server
savedAt	string <date-time> Timestamp when the layout was last saved locally
folderName	string Name of the folder the layout belongs to.
permission required	string (LayoutPermission) Enum: "CREATOR_WRITE" "ORG_READ" "ORG_WRITE"
	object An object containing the layout data. Note: The layout data format is not considered stable and may change over time.

Response samples

Content type

application/json

[{"id": "string",
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"savedAt": "2019-08-24T14:15:22Z",
"folderName": "string",
"permission": "CREATOR_WRITE",
"data": { }
}
]

Foxglove API (v1)

Authentication

Sorting and pagination

Timestamps

Python examples

Rate limits

Coverage

List coverage

Authorizations:

query Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Custom Properties

List custom properties

Authorizations:

query Parameters

Responses

Response Schema: application/json

Response samples

Create a custom property

Authorizations:

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

Get a custom property

Authorizations:

path Parameters

Responses

Response Schema: application/json

Response samples

Edit a custom property

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

Delete a custom property

Authorizations:

path Parameters

Responses

Response Schema: application/json

Response samples

Device Tokens

List device tokens

Authorizations:

query Parameters

Responses

Response Schema: application/json

Response samples

Create a device token

Authorizations:

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

Get a device token

Authorizations:

path Parameters

Responses

Response Schema: application/json

Response samples

Edit a device token

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

Delete a device token

Authorizations:

path Parameters

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required