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 data platform.

List coverage

A coverage range represents a time span for which Foxglove Data Platform 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:

SessionApiKey

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
device.name	string Name of device associated with the data
device.id	string ID of device associated with the data
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 `importStatus` for the coverage range.
importId	string Deprecated Filter coverage by import ID
recordingId	string Filter coverage by recording ID
sortBy	string Enum: "deviceId" "device.id" "device.name" "start" "end" Field to sort 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

deviceId required	string ID of device
required	object (DeviceSummary) ID and name of a device.
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`: Data Platform has received a request to import this recording. `importing`: The recording data is being processed for access via Data Platform. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Data Platform. 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. assign location IDs. This enables you to assign a location to each of your devices, view that data in Console, and filter devices by a location ID.

List custom properties

Authorizations:

SessionApiKey

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:

SessionApiKey

Request Body schema: application/json

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:

SessionApiKey

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:

SessionApiKey

path Parameters

required

string

Custom Property ID

Request Body schema: application/json

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:

SessionApiKey

path Parameters

required

string

Custom Property ID

Responses

Response Schema: application/json

required

string

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
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:

SessionApiKey

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 <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

Content type

application/json

[{"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:

SessionApiKey

Request Body schema: application/json

name required	string <= 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

Content type

application/json

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

Response samples

Content type

application/json

{"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:

SessionApiKeyNone

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

Content type

application/json

{"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:

SessionApiKey

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:

SessionApiKey

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

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 `null` as the value.

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

Content type

application/json

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

Response samples

Content type

application/json

{"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"
}
}

Device Tokens

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

List device tokens

Authorizations:

SessionApiKey

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 account to create and use device tokens

Authorizations:

SessionApiKey

Request Body schema: application/json

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:

SessionApiKey

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:

SessionApiKey

path Parameters

required

string

Device token ID

Request Body schema: application/json

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:

SessionApiKey

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"
}

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:

SessionApiKey

query Parameters

start	string <date-time> Start of an inclusive time range
end	string <date-time> End of an inclusive time range
deviceId	string Deprecated Filter events matching device ID
device.name	string Name of device associated with the event
device.id	string ID of device associated with the event
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" "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:

ApiKeySession

Request Body schema: application/json

deviceId	string Deprecated ID of the device to associate with the event
device.id	string ID of the device to associate with the event
device.name	string ID of the device to associate with the event
	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",
"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:

ApiKeySession

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:

ApiKeySession

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:

ApiKeySession

path Parameters

required

string

ID of the event

Request Body schema: application/json

	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"
}

Recordings

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

List recordings

Authorizations:

SessionApiKey

query Parameters

start	string <date-time> Define the start of an inclusive time range. All recordings with data overlapping this time-range will be returned.
end	string <date-time> Define the end of an inclusive time range. All recordings with data overlapping this time-range will be returned.
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
device.id	string Filter response to recordings for the device with this ID
device.name	string Filter response to recordings for the device with this name
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: "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 Data Platform. 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 Data Platform, this is the `filename` query arg provided to `/data/upload`.
size required	number <bigint> Size of the recording file in bytes
messageCount	number number of messages in the recording file.
createdAt required	string <date-time> Timestamp when the recording file was added to Data Platform.
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`: Data Platform has received a request to import this recording. `importing`: The recording data is being processed for access via Data Platform. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Data Platform. 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,
"messageCount": 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:

SessionApiKey

path Parameters

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 Data Platform. 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 Data Platform, this is the `filename` query arg provided to `/data/upload`.
size required	number <bigint> Size of the recording file in bytes
messageCount	number number of messages in the recording file.
createdAt required	string <date-time> Timestamp when the recording file was added to Data Platform.
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`: Data Platform has received a request to import this recording. `importing`: The recording data is being processed for access via Data Platform. `failed`: The recording data could not be imported. `complete`: The contents of the recording are available for access via Data Platform. 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,
"messageCount": 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:

SessionApiKey

path Parameters

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 successuly queued for import, is already imported, or already queued for import, this endpoint will return a 200 respoonse 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:

SessionApiKey

path Parameters

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: Data Platform has received a request to import this recording.
importing: The recording data is being processed for access via Data Platform.
failed: The recording data could not be imported.
complete: The contents of the recording are available for access via Data Platform.

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:

SessionApiKey

query Parameters

requestId	string A specific import request ID
deviceId	string Deprecated ID of device associated with the pending import
device.name	string Name of device associated with the pending import
device.id	string ID of device associated with the pending import
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" "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 or null ID of device
deviceName	string or null Name of the device from which the import originated
error	string or null Error message, if status is "error"
filename required	string Filename of the import
importId	string or null ID of import; null 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	string or null 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

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"
}
]

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-managed site, see this guide for uploading data.

Authorizations:

ApiKeySessionNoneNone

Request Body schema: application/json

In addition to filename, one of device.id, device.name, or deviceId is required.

deviceId	string Deprecated
device.name	string
device.id	string
filename required	string

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",
"device.name": "string",
"device.id": "string",
"filename": "string"
}

Response samples

Content type

application/json

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

Recording Attachments

A recording attachment resource represents information about an MCAP attachment imported to the data platform.

Attachments are available for individual download or with their recording.

List attachments

Authorizations:

SessionApiKeyNoneNoneNone

query Parameters

recordingId	string filter by recording ID
siteId	string filter by primary site ID
deviceId	string Deprecated filter by device ID
device.id	string filter by device ID
device.name	string filter by device name
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.

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"
}
]

Get an attachment

Authorizations:

SessionApiKeyNone

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.

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"
}

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:

SessionApiKey

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='Wwz2ZHLSQTUepB3z')

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:

SessionApiKey

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 <uuid>
deviceId required	string
deviceName required	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": "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:

SessionApiKey

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:

SessionApiKey

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"
}

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.

Either recordingId, importId, or all three of device.id/device.name, start, and end must be specified.

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

Authorizations:

SessionApiKey

Request Body schema: application/json

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 `importId` or `recordingId` must also be set. Only valid for mcap0 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 Deprecated ID of device associated with the exported data
device.id	string ID of device associated with the exported data.
device.name	string Name of device associated with the exported data.
start	string <date-time> Inclusive start of requested time range
end	string <date-time> Inclusive end of requested time range
importId	string ID of the import to stream
recordingId	string ID of the 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": "mcap",
"includeAttachments": true,
"isHosted": true,
"replayLookbackSeconds": 0,
"replayPolicy": "lastPerChannel",
"deviceId": "string",
"device.id": "string",
"device.name": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"importId": "string",
"recordingId": "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:

SessionApiKey

query Parameters

start	string <date-time> Filter response to topics appearing in recordings ending at or after `start`.
end	string <date-time> Filter response to topics appearing in recordings starting before `end`.
importId	string ID of the import from which to list topics
recordingId	string ID of the recording from which to list topics
deviceId	string Deprecated ID of device being queried
device.name	string Name of device being queried
device.id	string ID of device being queried
includeSchemas	boolean Default: false Whether full schemas should be included in the repsonse
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"
}
]

Extensions

Publish an extension

Requires Team plan or above

Publish a new Foxglove Studio 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 Studio extensions.

Authorizations:

SessionApiKey

Request Body schema: application/octet-stream

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 Studio 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

Foxglove Data Platform allows organization admins to share and manage Foxglove Studio extensions. Check out the Foxglove Studio docs to learn more.

Authorizations:

SessionApiKey

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:

SessionApiKey

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:

SessionApiKey

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:

SessionApiKey

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
updatedAt required	string <date-time> Timestamp when the layout was last updated
savedAt	string <date-time> Timestamp when the layout was last saved
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",
"permission": "CREATOR_WRITE",
"data": { }
}
]