Foxglove API (v1)
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.
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 responseoffset
– 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.
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.
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.
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, set the includeEdgeRecordings
query parameter
to true
Authorizations:
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 |
deviceId | string Deprecated 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 Equivalent to deviceId, and ignored if deviceId is supplied |
includeEdgeRecordings | boolean Default: false Include edge recordings in the response. When edge recordings are included, each item in the response array will also include the
|
importId | string Deprecated Filter coverage by import ID |
recordingId | string Filter coverage by recording ID |
recordingKey | string Filter coverage by recordingKey |
sortBy | string Enum: "deviceId" "device.id" "device.name" "deviceName" "start" "end" Field to sort items by |
sortOrder | string Enum: "asc" "desc" Sort order for the |
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
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:
Note: The set of |
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
- 200
[- {
- "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 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:
query Parameters
resourceType | string Value: "device" Filter properties matching a resource type |
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 |
Response samples
- 200
[- {
- "id": "string",
- "key": "string",
- "label": "string",
- "resourceType": "device",
- "valueType": "string",
- "values": [
- "string"
]
}
]
Create a custom property
Authorizations:
Request Body schema: application/jsonrequired
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 |
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 |
Request samples
- Payload
{- "key": "string",
- "label": "string",
- "resourceType": "device",
- "valueType": "string",
- "values": [
- "string"
]
}
Response samples
- 200
{- "id": "string",
- "key": "string",
- "label": "string",
- "resourceType": "device",
- "valueType": "string",
- "values": [
- "string"
]
}
Get a custom property
Authorizations:
path Parameters
id 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 |
Response samples
- 200
{- "id": "string",
- "key": "string",
- "label": "string",
- "resourceType": "device",
- "valueType": "string",
- "values": [
- "string"
]
}
Edit a custom property
Authorizations:
path Parameters
id required | string Custom Property ID |
Request Body schema: application/jsonrequired
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 |
Request samples
- Payload
{- "label": "string",
- "values": [
- "string"
]
}
Response samples
- 200
{- "id": "string",
- "key": "string",
- "label": "string",
- "resourceType": "device",
- "valueType": "string",
- "values": [
- "string"
]
}
List device tokens
Authorizations:
query Parameters
deviceId | string Filter by device 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
- 200
[- {
- "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:
Request Body schema: application/jsonrequired
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
{- "deviceId": "string"
}
Response samples
- 200
{- "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "deviceId": "string",
- "enabled": true,
- "token": "string"
}
Get a device token
Authorizations:
path Parameters
id 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
- 200
{- "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "deviceId": "string",
- "enabled": true
}
Edit a device token
Authorizations:
path Parameters
id required | string Device token ID |
Request Body schema: application/jsonrequired
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
{- "enabled": true
}
Response samples
- 200
{- "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "deviceId": "string",
- "enabled": true
}
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 namedkey
and its value isvalue
properties.key:value1,value2
: matches devices with a property that contains a key namedkey
and its value is eithervalue1
orvalue2
properties.key:*
: matches devices with a property that contains a key namedkey
and any valuefoo
: matches devices with properties where any key or stringified value containsfoo
Multiple qualifiers can be used in the same query string; this will filter devices matching the intersection of the qualifiers (AND).
Authorizations:
query Parameters
sortBy | string Field to sort items by ("id", "name", or a custom property key prefixed with |
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 |
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
id required | string Opaque identifier |
name required | string Organization-chosen device name |
orgId | string <uuid> |
createdAt | string <date> |
updatedAt | string <date-time> |
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
- 200
[- {
- "id": "string",
- "name": "string",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "createdAt": "2019-08-24",
- "updatedAt": "2019-08-24T14:15:22Z",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
]
Create a device
Authorizations:
Request Body schema: application/jsonrequired
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 <uuid> |
createdAt | string <date> |
updatedAt | string <date-time> |
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
{- "name": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
Response samples
- 200
{- "id": "string",
- "name": "string",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "createdAt": "2019-08-24",
- "updatedAt": "2019-08-24T14:15:22Z",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
Get a device
Get details on a specific device.
Authorizations:
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 <uuid> |
createdAt | string <date> |
updatedAt | string <date-time> |
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
- 200
{- "id": "string",
- "name": "string",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "createdAt": "2019-08-24",
- "updatedAt": "2019-08-24T14:15:22Z",
- "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:
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 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
- 200
{- "id": "string"
}
Update a device
Authorizations:
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/jsonrequired
name | string Device names must be unique in your organization. |
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 |
Responses
Response Schema: application/json
id required | string Opaque identifier |
name required | string Organization-chosen device name |
orgId | string <uuid> |
createdAt | string <date> |
updatedAt | string <date-time> |
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
{- "name": "string",
- "properties": { }
}
Response samples
- 200
{- "id": "string",
- "name": "string",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "createdAt": "2019-08-24",
- "updatedAt": "2019-08-24T14:15:22Z",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
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 namedkey
with a value ofvalue
key:value1,value2
: matches events with metadata that contains a key namedkey
with a value of eithervalue1
orvalue2
key:*
: matches events where any metadata that contains a key namedkey
*:value
: matches events where any metadata that containsvalue
as a valuefoo
: matches events with metadata where any key or value string containsfoo
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 namedkey1
with its valuevalue1
and another key namedkey2
with its valuevalue2
key:"value with spaces"
: matches metadata with a key namedkey
and its valuevalue with spaces
key:value foo
: matches metadata that contains both a key namedkey
with its valuevalue
and any key or value that contains the textfoo
Note: The
start
andend
query arguments will find any events which intersect the query range (inclusive of start and end).
Authorizations:
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 |
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
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
- 200
[- {
- "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:
Request Body schema: application/jsonrequired
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
{- "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
- 200
{- "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:
path Parameters
id 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
- 200
{- "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:
path Parameters
id required | string ID of the event |
Responses
Response Schema: application/json
id 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
- 200
{- "id": "string"
}
Update an event
Authorizations:
path Parameters
id required | string ID of the event |
Request Body schema: application/jsonrequired
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
{- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z"
}
Response samples
- 200
{- "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"
}
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:
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 |
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
id required | string Opaque ID |
importId required | string Deprecated |
orgId required | string <uuid> |
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
- 200
[- {
- "id": "string",
- "importId": "string",
- "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",
- "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:
query Parameters
id required | Array of strings <= 50 items ID of import to delete. You can specify up to 50 IDs (for example, |
Responses
Response Schema: application/json
required | Array of objects | ||||
Array
|
Response samples
- 200
{- "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:
path Parameters
importId required | string The |
query Parameters
deviceId | string Deprecated The deviceId from the import record |
Responses
Response Schema: application/json
id 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
- 200
{- "id": "string"
}
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:
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
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
- 200
[- {
- "path": "string",
- "topics": [
- "string"
]
}
]
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:
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 |
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
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
- 200
[- {
- "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:
path Parameters
id 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
- 200
{- "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:
path Parameters
id 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='Wwz2ZHLSQTUepB3z')
A recording is a resource representing the content of an MCAP file or ROS bag managed by Data Platform.
List recordings
Authorizations:
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 |
sortOrder | string Enum: "asc" "desc" Sort order for the |
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 |
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:
Note: The set of |
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
- 200
[- {
- "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:
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 |
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:
Note: The set of |
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
- 200
{- "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:
path Parameters
keyOrId required | string Recording ID |
Responses
Response Schema: application/json
recordingId required | string The recording ID |
Response samples
- 200
{- "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:
path Parameters
keyOrId required | string Recording ID |
Responses
Response Schema: application/json
id | string Recording ID |
importStatus | string (RecordingImportStatus) Enum: "none" "pending" "importing" "failed" "complete" The import status of recordings. Status will be one of:
Note: The set of |
Response samples
- 200
{- "id": "string",
- "importStatus": "none"
}
List pending imports
List the pending imports. These are in-progress import jobs for newly uploaded recordings.
Authorizations:
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 |
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
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
- 200
[- {
- "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:
Request Body schema: application/jsonrequired
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 |
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
{- "deviceId": "string",
- "deviceName": "string",
- "device.name": "string",
- "device.id": "string",
- "filename": "string",
- "key": "string"
}
Response samples
- 200
{- "link": "string",
- "requestId": "string"
}
Site tokens are credentials a Self-hosted primary site or Edge site use to communicate with the Foxglove API.
List site tokens
Authorizations:
query Parameters
siteId | string Filter by site ID |
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 |
Response samples
- 200
[- {
- "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "siteId": "string"
}
]
Create a site token
Authorizations:
Request Body schema: application/jsonrequired
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
{- "siteId": "string"
}
Response samples
- 200
{- "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "siteId": "string",
- "token": "string"
}
List sites
Retrieve a list of sites.
Authorizations:
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.
|
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
- 200
[- {
- "id": "string",
- "name": "string",
- "type": "foxglove-hosted",
- "url": "string",
- "retainRecordingsSeconds": 0
}
]
Create a Site
Create a new site.
Authorizations:
Request Body schema: application/jsonrequired
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.
|
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
{- "name": "string",
- "type": "edge",
- "retainRecordingsSeconds": 0
}
Response samples
- 200
{- "id": "string",
- "name": "string",
- "type": "foxglove-hosted",
- "url": "string",
- "retainRecordingsSeconds": 0
}
Get site details
Get details for a specific site.
Authorizations:
path Parameters
id 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.
|
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
- 200
{- "id": "string",
- "name": "string",
- "type": "foxglove-hosted",
- "url": "string",
- "retainRecordingsSeconds": 0
}
Update site details
Update the name or retention period for a Site.
Authorizations:
path Parameters
id required | string Site ID |
Request Body schema: application/jsonrequired
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.
|
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
{- "name": "string",
- "retainRecordingsSeconds": 0,
- "url": "string"
}
Response samples
- 200
{- "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:
path Parameters
id required | string Site ID |
Responses
Response Schema: application/json
id required | string ID of the deleted site |
Response samples
- 200
{- "id": "string"
}
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 thelink
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:
Request Body schema: application/jsonrequired
topics | Array of strings List of topics to include in the exported file (defaults to all topics) |
outputFormat | string Enum: "mcap" "mcap0" "bag1" Output an .mcap (v0), or .bag file |
includeAttachments | boolean Include attachments in streamed data. One of |
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
{- "topics": [
- "string"
], - "outputFormat": "mcap",
- "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
- 200
{- "link": "string"
}
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:
query Parameters
start | string <date-time> Return all topics appearing in recordings ending on or after |
end | string <date-time> Return all topics appearing in recordings starting on or before |
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 |
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
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
- 200
[- {
- "encoding": "string",
- "schema": "string",
- "schemaEncoding": "string",
- "schemaName": "string",
- "topic": "string",
- "version": "string"
}
]
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
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",
- "importStatus": "none",
- "path": "string",
- "device": {
- "id": "string",
- "name": "string"
}, - "edgeSite": {
- "id": "string",
- "name": "string"
}, - "site": {
- "id": "string",
- "name": "string"
}
}
}
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",
- "importStatus": "none",
- "path": "string",
- "device": {
- "id": "string",
- "name": "string"
}, - "edgeSite": {
- "id": "string",
- "name": "string"
}, - "site": {
- "id": "string",
- "name": "string"
}
}
}
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
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"
}
}
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"
}
}
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:
Request Body schema: application/octet-streamrequired
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.
Responses
Response Schema: application/json
id required | string |
Response samples
- 200
- 409
{- "id": "string"
}
List extensions
Organization admins can share and manage Foxglove extensions. Check out the docs to learn more.
Authorizations:
Responses
Response Schema: application/json
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
- 200
[- {
- "id": "string",
- "name": "string",
- "publisher": "string",
- "displayName": "string",
- "description": "string",
- "activeVersion": "string",
- "sha256Sum": "string"
}
]
Delete an extension
Once deleted, the extension will no longer be available within your organization.
Authorizations:
path Parameters
id required | string Extension ID |
Responses
Response Schema: application/json
id required | string The ID of the deleted extension |
Response samples
- 200
{- "id": "string"
}
List layouts
List the org layouts.
Note: Only layouts shared with the org are returned in the response; no personal layouts are returned.
Authorizations:
query Parameters
updatedSince | string <date-time> Return only layouts updated since this time. |
includeData | boolean Default: true When set to false, the |
Responses
Response Schema: application/json
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
- 200
[- {
- "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": { }
}
]