openapi: 3.1.0
info:
title: Foxglove API
version: v1
x-logo:
url: https://foxglove.dev/images/logo-icon-round.png
description: >
# Python client
Foxglove provides a Python client library
([`foxglove-client`](https://github.com/foxglove/foxglove-python)) to more
easily interact with the Foxglove API.
The SDK can be downloaded from
[PyPI](https://pypi.org/project/foxglove-client/) and source is available on
[GitHub](https://github.com/foxglove/foxglove-python).
# Authentication
All routes excluding the [Site Bucket Notifications
endpoint](#tag/Sites/paths/~1site-bucket-notifications/post) require an [API
key](/docs/settings#api-keys) with specific capabilities. Only organization
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](https://www.ietf.org/rfc/rfc3339.txt) 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.
# 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.
servers:
- url: https://api.foxglove.dev/v1
description: Production
security: []
tags:
- name: Custom Properties
description: |
Custom properties are typed metadata which you can assign to 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.
- name: Devices
description: >
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 and events.
A device may have [Foxlet](https://docs.foxglove.dev/docs/fleet/foxlet)
installed on it. In this case, you may configure the retention period for
recordings on the
device by setting its `retainRecordingsSeconds`.
To help manage your devices, you may define [custom
properties](#tag/Custom-Properties) and
assign metadata to each device via its `properties`.
- name: Coverage
description: >
Coverage provides the ability to see which time spans are available within
Foxglove.
- name: Imports
description: >
**The Imports endpoints are deprecated. Use the
[Recordings](#tag/Recordings) endpoints instead.**
Imports are recordings that are available at a Primary Site.
- name: Topics
description: |
Topics provide schema information for messages in the data source.
- name: Events
description: >
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.
- name: Event Types
description: >
Event types help ensure data quality through validation, enable better
filtering and analytics,
and provide visual distinctions between categories of events.
- name: Recordings
description: >
A recording is a resource representing the content of an MCAP file or ROS
bag managed by Data
Platform.
- name: Sessions
description: >
Sessions are logical groupings of recordings from a single device. They
allow you to manage
and interact with recording data independent of how the recordings are
stored.
- name: Recording Attachments
description: >
A recording attachment resource represents information about an MCAP
attachment
imported to Foxglove.
Attachments are available for individual download or with their recording.
- name: Sites
description: >
A site is a logical grouping of storage and compute for storing Recording
data.
- name: Device Tokens
description: |
Device tokens authenticate a device to the API.
- name: Webhook Payloads
description: >
[Webhooks](/docs/webhooks) send POST request notifications to your HTTPS
endpoint
when events occur within Foxglove. This section describes the JSON request
body format
your endpoint should expect for each event type.
## recording.created
`recording.created` events occur when a recording is created. Recordings
are created
when a file is [uploaded](/api#tag/Recordings/paths/~1data~1upload/post),
added to
[Edge Site](/docs/edge-sites) storage, or created on a device that runs
[Foxlet](/docs/fleet/foxlet).
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/RecordingCreated" />
## recording.imported
`recording.imported` events occur when a recording is
[imported](/docs/importing-data)
and is ready for streaming.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/RecordingImported" />
## session.created
`session.created` events occur when a new [Session](/docs/data/sessions)
is created. Sessions
group related recordings and can be created via the API or when recordings
are
associated with a session.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/SessionCreated" />
## device.created
`device.created` events occur when a new
[Device](/docs/importing-data#add-a-device) is created.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/DeviceCreated" />
## device.updated
`device.updated` events occur when a
[Device](/docs/importing-data#add-a-device) is updated.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/DeviceUpdated" />
## event.created
`event.created` events occur when a new [Event](/docs/events) is created
in Foxglove.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/EventCreated" />
## event.updated
`event.updated` events occur when an [Event](/docs/events) is updated.
<SchemaDefinition
schemaRef="#/components/schemas/webhook_payloads/EventUpdated" />
## ping
The `ping` event type is used to test webhook connectivity.
<SchemaDefinition schemaRef="#/components/schemas/webhook_payloads/Ping"
/>
- name: Site Tokens
description: >
Site tokens are credentials a [self-hosted Primary
Site](https://docs.foxglove.dev/docs/primary-sites#self-hosted) or [Edge
Site](https://docs.foxglove.dev/docs/edge-sites) use to communicate with
the Foxglove API.
- name: Site Inbox Notification Tokens
description: >
Site inbox notification tokens are credentials used to authenticate bucket
notifications for a [Primary
Site](https://docs.foxglove.dev/docs/primary-sites) (self-managed or BYOS)
to the Foxglove API.
- name: Lake files
description: >
MCAP files stored in the lake bucket of a [self-hosted Primary
Site](https://docs.foxglove.dev/docs/primary-sites#self-hosted).
You must have an Enterprise account to use lake file endpoints.
- name: Projects
description: >
[Projects](https://docs.foxglove.dev/docs/projects) are a container for
organizing data and resources in Foxglove.
Your plan must support managing projects.
x-tagGroups:
- name: Data Platform
tags:
- Coverage
- Custom Properties
- Device Tokens
- Devices
- Events
- Event Types
- Imports
- Lake files
- Projects
- Recording Attachments
- Recordings
- Sessions
- Site Tokens
- Site Inbox Notification Tokens
- Sites
- Stream data
- Topics
- name: Webhooks
tags:
- Webhook Payloads
- name: Visualization
tags:
- Extensions
- Layouts
paths:
/devices:
get:
tags:
- Devices
security:
- ApiKey:
- devices.list
summary: List devices
description: >
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` with a value of `value`; use double quotes if the
value contains spaces or special characters
* `properties.key:value1,value2`: matches devices with a property that
contains a key named `key` and its value is either `value1` or `value2`
* `properties.key:*`: matches devices with a property that contains a
key named `key` and any value
* `*:value`: matches devices with a property that contains a key with
any name and a value of `value`
* `foo`: matches devices with properties where any key or stringified
value contains `foo`
Multiple qualifiers can be used in the same query string; this will
filter devices matching the intersection of the qualifiers (AND).
x-codeSamples:
- lang: python
label: Python
source: |
from foxglove.client import Client
token = "<YOUR API TOKEN HERE>"
client = Client(token=token)
client.get_devices()
parameters:
- in: query
name: projectId
description: Filter devices by project
schema:
type: string
required: false
- in: query
name: sortBy
description: >-
Field to sort items by ("id", "name", or a custom property key
prefixed with `properties.`)
schema:
type: string
required: false
- in: query
name: query
description: >-
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.
schema:
type: string
- $ref: '#/components/parameters/sortOrder'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: List of devices
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/Device'
- $ref: '#/components/schemas/DeviceDetails'
- $ref: '#/components/schemas/DeviceRemoteAccessState'
post:
tags:
- Devices
summary: Create a device
security:
- ApiKey:
- devices.create
x-codeSamples:
- lang: python
label: Python
source: |
from foxglove.client import Client
token = "<YOUR API TOKEN HERE>"
client = Client(token=token)
client.create_device(
name=name,
project_id="<YOUR PROJECT ID HERE>",
)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
$ref: '#/components/schemas/deviceName'
properties:
$ref: '#/components/schemas/CustomPropertyValues'
description: >
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.
required: []
projectId:
description: >-
The project ID that the device belongs to. Required for
multi-project orgs.
type: string
required:
- name
responses:
'200':
description: The newly created device
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Device'
- $ref: '#/components/schemas/DeviceDetails'
/recordings:
get:
tags:
- Recordings
summary: List recordings
security:
- ApiKey:
- recordings.list
x-codeSamples:
- lang: python
label: Python
source: |
from foxglove.client import Client
token = "<YOUR API TOKEN HERE>"
client = Client(token=token)
client.get_recordings()
parameters:
- $ref: '#/components/parameters/start'
description: >
Start of inclusive time range: return all recordings with data on or
after this value
- $ref: '#/components/parameters/end'
description: >
End of inclusive time range: return all recordings with data on or
before this value
- in: query
name: path
description: Filter response to recordings with this path
schema:
type: string
- in: query
name: site.id
description: >-
Filter response to recordings stored at the Primary Site with this
ID
schema:
type: string
- in: query
name: edgeSite.id
description: Filter response to recordings stored at the Edge Site with this ID
schema:
type: string
- in: query
name: deviceId
description: >-
Filter response to recordings for the device with this ID, empty
string for those without any
schema:
type: string
- in: query
name: deviceName
description: Filter response to recordings for the device with this name
schema:
type: string
- in: query
name: topic
description: Filter response to recordings containing the topic
schema:
type: string
- in: query
name: device.id
description: Equivalent to deviceId, and ignored if deviceId is supplied
schema:
type: string
deprecated: true
- in: query
name: device.name
description: Equivalent to deviceName, and ignored if deviceName is supplied
schema:
type: string
deprecated: true
- in: query
name: importStatus
description: Filter response to recordings with this import status
schema:
type: string
enum:
- none
- pending
- importing
- failed
- complete
- in: query
name: projectId
description: Filter recordings by project
schema:
type: string
required: false
- in: query
name: sessionId
description: >-
Filter response to recordings in the session with this ID, or empty
string for recordings with no associated session
schema:
type: string
- in: query
name: sessionKey
description: >-
Filter response to recordings in the session with this key (sessions
group recordings from a specific device)
schema:
type: string
- in: query
name: metadataQuery
description: >
Filter recordings by metadata using a query syntax.
Supports key-value search variations (see [Recordings
Search](https://docs.foxglove.dev/docs/data/recordings#search)):
* `key:value`: matches recordings with metadata that contains a key
named `key` with a value of `value`
* `key:value1,value2`: matches recordings with metadata that
contains a key named `key` with a value of either `value1` or
`value2`
* `key:*`: matches recordings where any metadata contains a key
named `key`
* `*:value`: matches recordings where any metadata contains `value`
as a value
* `search term`: matches recordings with metadata where any key or
value string contains `search term`
Multiple qualifiers can be used in the same query string; this will
filter recordings where metadata matches the intersection of the
qualifiers (AND).
**Examples:**
* `temperature:high` - find recordings with sensor metadata where
temperature is high
* `status:* device:camera1` - find recordings with any status AND
device camera1
* `*:error` - find any key with "error" value
* `warehouseName:"leaping llama"` - use quotes for values with
spaces or special characters
As this is a query parameter, the value must be URL-encoded.
schema:
type: string
required: false
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- in: query
name: sortBy
description: >
Sort returned recordings by a field in the response type. Specifying
`duration` sorts by
the duration between the recording `start` and `end` fields.
schema:
type: string
enum:
- deviceName
- device.name
- createdAt
- start
- end
- duration
- path
- importedAt
- $ref: '#/components/parameters/sortOrder'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Recording'
/recordings/{keyOrId}:
parameters:
- in: path
name: keyOrId
schema:
type: string
required: true
description: Recording Key or ID
get:
tags:
- Recordings
summary: Get a recording
description: |
Get details on a specific recording.
parameters: []
security:
- ApiKey:
- recordings.list
responses:
'200':
description: A Recording
content:
application/json:
schema:
$ref: '#/components/schemas/Recording'
delete:
tags:
- Recordings
summary: Delete a recording
description: >
Deletes a recording. Deleting a recording also deletes the data for that
recording
(including attachments, messages, metadata, etc).
Note: If the recording was imported from an Edge Site, only the imported
data is
removed; the edge copy on the Edge Site is unchanged and the recording
can be
imported again. The recording remains associated with any session it
belongs to,
and re-importing restores it on that session.
security:
- ApiKey:
- recordings.delete
responses:
'200':
description: The deleted recording ID
content:
application/json:
schema:
type: object
properties:
recordingId:
type: string
description: The recording ID
required:
- recordingId
/recordings/{keyOrId}/import:
parameters:
- in: path
name: keyOrId
schema:
type: string
required: true
description: Recording ID
post:
tags:
- Recordings
summary: Import from edge
description: >
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.
security:
- ApiKey:
- data.upload
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Recording ID
importStatus:
$ref: '#/components/schemas/RecordingImportStatus'
/sessions:
get:
tags:
- Sessions
summary: List sessions
description: >
Retrieve a list of recording sessions.
**Filtering by custom properties**
Use the `query` parameter to filter sessions on custom properties.
Syntax:
* `key:value`: matches sessions with a property that contains a key
named `key` with a value of `value`; use double quotes if the value
contains spaces or special characters
* `key:value1,value2`: matches sessions with a property that contains a
key named `key` and its value is either `value1` or `value2`
* `key:*`: matches sessions with a property that contains a key named
`key` and any value
* `*:value`: matches sessions with a property where any key has the
value `value`
* `foo`: matches sessions with properties where any key or stringified
value contains `foo`
Multiple qualifiers can be used in the same query string; this will
filter sessions matching the intersection of the qualifiers (AND).
security:
- ApiKey:
- sessions.list
parameters:
- in: query
name: projectId
description: Filter sessions by project
schema:
type: string
required: false
- in: query
name: deviceId
description: Filter sessions by device ID
schema:
type: string
required: false
- in: query
name: deviceName
description: Filter sessions by device name
schema:
type: string
required: false
- in: query
name: keyMatches
description: Partial match on session key (case-insensitive)
schema:
type: string
required: false
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- in: query
name: sortBy
description: Field to sort items by ("id", "createdAt", "updatedAt")
schema:
type: string
enum:
- id
- createdAt
- updatedAt
required: false
- in: query
name: query
description: >-
Space-separated query string for session custom properties. Each
custom property key must be valid. See above for syntax and
examples.
schema:
type: string
required: false
- $ref: '#/components/parameters/sortOrder'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: List of recording sessions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecordingSessionListItem'
post:
tags:
- Sessions
summary: Create a session
description: >
Create a new recording session. Either `deviceId` or `recordingIds` must
be provided.
If `recordingIds` are provided without a `deviceId`, the device is
inferred from the
recordings, which must all belong to the same device. The session
inherits its org and
project from the device.
security:
- ApiKey:
- sessions.create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
description: >-
The ID of the device to associate with the session. If
omitted, inferred from `recordingIds`.
type: string
key:
description: A user-supplied identifier, unique within the project.
minLength: 1
type: string
recordingIds:
description: >-
IDs of recordings to associate with the new session. All
recordings must belong to the same device and project.
type: array
items:
type: string
properties:
$ref: '#/components/schemas/CustomPropertyValues'
description: >
A key-value map, where each key is one of your pre-defined
session custom property keys.
Keys which are not recognized as custom properties will be
ignored.
required: []
responses:
'200':
description: The newly created session
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingSession'
/sessions/{keyOrId}:
parameters:
- in: path
name: keyOrId
schema:
type: string
required: true
description: Recording Session Key or ID
get:
tags:
- Sessions
summary: Get a session
description: |
Get details on a specific session.
security:
- ApiKey:
- sessions.list
parameters:
- in: query
name: projectId
schema:
type: string
description: Filter sessions by project. Required for multi-project orgs.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingSession'
patch:
tags:
- Sessions
summary: Update recordings in a session
description: >-
Add or remove recordings associated with the session. All recordings
must belong to the same device and project.
security:
- ApiKey:
- sessions.update
parameters:
- in: query
name: projectId
schema:
type: string
description: Filter sessions by project. Required for multi-project orgs.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
addRecordingIds:
type: array
items:
type: string
description: Recording display IDs to add to the session.
removeRecordingIds:
type: array
items:
type: string
description: Recording display IDs to remove from the session.
properties:
description: >
Custom properties to assign to the session.
Keys which are not included in the request, but exist on the
session, will be unchanged.
To unset a property, pass `null` as the value.
type: object
additionalProperties: true
required: []
responses:
'200':
description: Updated session
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingSession'
delete:
tags:
- Sessions
summary: Delete a session
description: |
Soft-delete a recording session and unlink all recordings from it.
Does not delete recording data.
security:
- ApiKey:
- sessions.delete
parameters:
- in: query
name: projectId
schema:
type: string
description: Filter sessions by project. Required for multi-project orgs.
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deleted session
required:
- id
/actions/devices/{nameOrId}/update-property-time-interval:
parameters:
- in: path
name: nameOrId
schema:
type: string
required: true
description: >
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.
post:
tags:
- Devices
- Properties
summary: Update property time interval
description: >
Specify a value that was set for a given time range, or specify no value
was set for that range.
Existing records overlapping that time range may be split, trimmed, or
deleted to accommodate
this assertion. This endpoint should only be used for updating past time
intervals. To update the
current value of a property use the [update
device](#tag/Devices/paths/~1devices~1%7BnameOrId%7D/patch)
endpoint.
security:
- ApiKey:
- devices.update
x-projectIdOptional: true
requestBody:
required: true
content:
application/json
# --- truncated at 32 KB (169 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/foxglove-technologies/refs/heads/main/openapi/foxglove-technologies-openapi-original.yml