# Foxglove REST API Reference (Full) > This file contains the complete Foxglove REST API reference for LLM consumption. > For a concise overview, see https://docs.foxglove.dev/api/llms.txt > For product documentation (visualization, panels, SDKs), see https://docs.foxglove.dev/llms.txt and https://docs.foxglove.dev/llms-full.txt Base URL: https://api.foxglove.dev/v1 Interactive documentation: https://docs.foxglove.dev/api # 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 Python client 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](https://docs.foxglove.dev/api/sites/notify-object-created-or-removed) require an [API key](https://docs.foxglove.dev/docs/settings#api-keys) with specific capabilities. Organization admins can create organization API keys, and members can create [personal access tokens](https://docs.foxglove.dev/docs/personal-access-tokens) that act as them. Some routes, such as those that manage credentials, don't accept personal access tokens. API keys and personal access tokens can be limited to projects. A key limited to projects can read organization-wide resources (layouts, extensions, event types, custom properties, and sites), but can't create, change, or delete them. It also can't read or change a site's ingest path policy or backfill jobs, manage site tokens or site inbox notification tokens, or list organization members. These operations return a 403 error with the code `ProjectLimitedCredentialDenied`. A key limited to more than one project must send `projectId` to most endpoints that accept one. See [Limit API keys and personal access tokens](https://docs.foxglove.dev/docs/projects#limit-api-keys-and-personal-access-tokens) for the full rules and the errors a limited key can get. 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. Applications that integrate with Foxglove can instead call the API with an [OAuth](https://docs.foxglove.dev/docs/oauth) access token, which acts as the user who approved the application. An endpoint accepts an OAuth access token only when it lists `OAuthToken` among its authorizations. # 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 `` formatting (i.e. `string `). 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. --- # Data Platform ## Automations [Automations](https://docs.foxglove.dev/docs/automations) run an AI agent on your data, on a schedule, when an event occurs, or on demand. An automation acts as its owner, with the owner's access to data in the automation's project. Personal access tokens can create, edit, delete, and run automations as their member. OAuth access tokens can do the same as the member who authorized them. A run acts as the automation's owner, so the token's other scopes do not limit what the run can read or change. Organization API keys can list automations and their runs and start runs, which use only the automation's saved instructions. Your plan must support Automations. ### GET /automations **Summary**: List automations List automations for a project, newest first, with lifetime run counts. **Required capabilities**: automations.list **Query parameters**: - `projectId` (string, required): Project to list automations from - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: List of automations - `automations` (array of object (AutomationListItem), required) --- ### POST /automations **Summary**: Create an automation **Required capabilities**: automations.create **Request body** (JSON): - `projectId` (string, required) - `name` (string, required) - `actionPrompt` (string, required) - `modelSelection` (string, one of: "auto" | "sonnet" | "opus"): Model family for the automation's runs. Omit to use the organization's default model at run time. **Responses**: - `201`: The created automation - `id` (string, required) - `projectId` (string, required) - `name` (string, required) - `actionPrompt` (string, required) - `modelSelection` (one of: string, one of: "auto" | "sonnet" | "opus" | null, required): Model family the automation's runs use, or null when none is saved and runs use the organization's default model. - `isOwner` (boolean, required): True when the caller's member owns the automation. Always false for an organization API key, which acts as no member. Use `permissions` to decide which actions to offer. - `permissions` (object, required): What the caller can do to the automation, as decided by the server's access policy. For an organization API key, `canEdit`, `canSetEnabled`, and `canDelete` are false, and `canRun` is true when the owner is an active member. - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required): When the automation was created or its name, prompt, or trigger last changed. --- ### GET /automations/{automationId} **Summary**: Get an automation Get the saved definition of an automation. **Required capabilities**: automations.list **Path parameters**: - `automationId` (string, required): Automation ID **Responses**: - `200`: The automation - `id` (string, required) - `projectId` (string, required) - `name` (string, required) - `actionPrompt` (string, required) - `modelSelection` (one of: string, one of: "auto" | "sonnet" | "opus" | null, required): Model family the automation's runs use, or null when none is saved and runs use the organization's default model. - `isOwner` (boolean, required): True when the caller's member owns the automation. Always false for an organization API key, which acts as no member. Use `permissions` to decide which actions to offer. - `permissions` (object, required): What the caller can do to the automation, as decided by the server's access policy. For an organization API key, `canEdit`, `canSetEnabled`, and `canDelete` are false, and `canRun` is true when the owner is an active member. - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required): When the automation was created or its name, prompt, or trigger last changed. - `404`: Automation not found --- ### PATCH /automations/{automationId} **Summary**: Edit an automation Update the saved definition in place. Existing run prompts are unchanged. **Required capabilities**: automations.update **Path parameters**: - `automationId` (string, required): Automation ID **Request body** (JSON): - `name` (string) - `actionPrompt` (string) - `modelSelection` (string, one of: "auto" | "sonnet" | "opus", nullable): Model family for the automation's runs. Omit to leave the saved choice unchanged. Send null to clear it, so runs use the organization's default AI model. **Responses**: - `200`: The updated automation - `id` (string, required) - `projectId` (string, required) - `name` (string, required) - `actionPrompt` (string, required) - `modelSelection` (one of: string, one of: "auto" | "sonnet" | "opus" | null, required): Model family the automation's runs use, or null when none is saved and runs use the organization's default model. - `isOwner` (boolean, required): True when the caller's member owns the automation. Always false for an organization API key, which acts as no member. Use `permissions` to decide which actions to offer. - `permissions` (object, required): What the caller can do to the automation, as decided by the server's access policy. For an organization API key, `canEdit`, `canSetEnabled`, and `canDelete` are false, and `canRun` is true when the owner is an active member. - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required): When the automation was created or its name, prompt, or trigger last changed. - `403`: Forbidden - `404`: Automation not found --- ### DELETE /automations/{automationId} **Summary**: Delete an automation Delete an automation, its trigger, and its runs. Each run's chat is deleted with the run, including a run that is still in progress. **Required capabilities**: automations.delete **Path parameters**: - `automationId` (string, required): Automation ID **Responses**: - `200`: The automation was deleted - `success` (boolean, value: true, required) - `403`: Forbidden - `404`: Automation not found --- ### GET /automations/{automationId}/trigger **Summary**: Get an automation trigger **Required capabilities**: automations.list **Path parameters**: - `automationId` (string, required): Automation ID **Responses**: - `200`: The current trigger - `id` (string, required) - `automationId` (string, required) - `eventType` (string, one of: "recording.created" | "recording.imported" | "session.created" | "device.created" | "device.updated" | "event.created" | "event.updated" | "clock.updated", required) - `enabled` (boolean, required) - `configurationVersion` (integer, required) - `configuration` (object, required) - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required) - `deletedAt` (string (date-time), required, nullable): When the trigger was replaced or removed. The trigger endpoints return only the current trigger, where it is null; a run's trigger can be one deleted since. - `404`: Automation or trigger not found --- ### PUT /automations/{automationId}/trigger **Summary**: Set an automation trigger Replace the automation's current trigger definition. Only the owner can change the event type or configuration. Owners and org admins can send the current event type and configuration with a new `enabled` value to enable or disable the trigger. **Required capabilities**: automations.update **Path parameters**: - `automationId` (string, required): Automation ID **Request body** (JSON): - `eventType` (string, one of: "recording.created" | "recording.imported" | "session.created" | "event.created" | "event.updated" | "clock.updated", required): The event that starts a run. Use `clock.updated` for a trigger that runs on a schedule. - `enabled` (boolean) - `configuration` (object): Settings for the trigger's event type. `schedule` says when a `clock.updated` trigger runs. It is required for `clock.updated` and not allowed for other event types. - `schedule` (object (AutomationSchedule)): UTC calendar recurrence starting at a whole-hour anchor. Monthly anchors use days 1–28. - `cadence` (string, one of: "hourly" | "daily" | "weekly" | "monthly", required) - `anchor` (string (date-time), required): UTC start timestamp at a whole hour. Its calendar fields determine the recurrence. - `eventTypeId` (string): For `event.created` and `event.updated` only. The trigger starts a run only for events of this event type. **Responses**: - `201`: The current trigger - `id` (string, required) - `automationId` (string, required) - `eventType` (string, one of: "recording.created" | "recording.imported" | "session.created" | "device.created" | "device.updated" | "event.created" | "event.updated" | "clock.updated", required) - `enabled` (boolean, required) - `configurationVersion` (integer, required) - `configuration` (object, required) - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required) - `deletedAt` (string (date-time), required, nullable): When the trigger was replaced or removed. The trigger endpoints return only the current trigger, where it is null; a run's trigger can be one deleted since. - `403`: Forbidden - `404`: Automation not found --- ### DELETE /automations/{automationId}/trigger **Summary**: Delete an automation trigger **Required capabilities**: automations.update **Path parameters**: - `automationId` (string, required): Automation ID **Responses**: - `200`: The trigger was deleted - `success` (boolean, value: true, required) - `403`: Forbidden - `404`: Automation or trigger not found --- ### POST /automations/runs **Summary**: Create an automation run Create a pending run with a free-text run prompt and a snapshot of the saved automation instructions. Any member of the automation's project, or an organization API key, can start a run; it executes as the automation's owner, using the owner's data access and AI usage. **Required capabilities**: automations.run **Request body** (JSON): - `automationId` (string): The automation to run. Required. - `runPrompt` (string): Free-text instructions for this run. May reference recordings or other resources. Required for members, including personal access tokens. Organization API keys must omit it, and the run uses only the automation's saved instructions. **Responses**: - `201`: The pending run - `id` (string, required) - `automationId` (string, required) - `actionPrompt` (string, required): Snapshot of the automation's saved instructions. - `runPrompt` (string, required): Prompt submitted for this run. - `status` (string, one of: "pending" | "running" | "succeeded" | "failed", required) - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required) - `startedAt` (string (date-time), required, nullable) - `completedAt` (string (date-time), required, nullable) - `errorMessage` (string, required, nullable) - `execution` (string, one of: "pending" | "running" | "finished" | "error" | "blocked", required): Whether Foxglove ran the automation to the end, separate from what the run found. `finished` means the agent's turn ended, or a limit stopped the run after the agent reported its result. `blocked` means a limit or a missing permission stopped the run before that, such as the AI usage limit, the run's time limit, or an owner who lost access to the project. `error` means the run failed on Foxglove's side. - `result` (string, one of: "succeeded" | "needs_review" | "failed" | "no_result", required, nullable): What the agent reported the run accomplished. `needs_review` means the task finished but the agent was not sure whether something went wrong. `no_result` means the task ran and had nothing to act on, such as no matching data. Null when the agent did not report a result, for example because the run was blocked or failed before it finished. - `resultSummary` (string, required, nullable): The agent's one-sentence summary of what the run found or did. - `model` (string, required, nullable): Concrete model the run's chat used, such as `claude-sonnet-5-5`. Null until the run's chat exists. - `402`: The run would be refused because the automation's owner reached their AI usage limit, or the organization reached its AI spend limit for the billing period (error `code` `AiSpendLimitReached`). - `403`: Forbidden - `404`: Automation not found - `409`: The automation can't run. Its owner is missing or no longer an active member (error `code` `AutomationNoActiveOwner`), the organization's plan doesn't include AI Chat or Automations, the automation owner's seat doesn't include AI Chat, or AI Chat is turned off for the organization. - `429`: The organization or the automation's owner already has the maximum number of pending or running runs. - `503`: Another run for the organization is being started. Retry shortly. --- ### GET /automations/runs **Summary**: List automation runs List runs for a project, newest first unless `sortOrder` says otherwise. Each run includes its automation's name and what triggered it. Get a run to read its run prompt and the saved instructions it used. **Required capabilities**: automations.list **Query parameters**: - `projectId` (string, required): Project to list runs from - `automationId` (array of string): Filter runs to these automations within the project. Provide as a comma-separated list. - `status` (array of string, one of: "pending" | "running" | "succeeded" | "failed"): Filter runs to these statuses. Provide as a comma-separated list. - `execution` (array of string, one of: "pending" | "running" | "finished" | "error" | "blocked"): Filter runs to these executions, as each run's `execution` field reports it. Provide as a comma-separated list. - `result` (array of string, one of: "succeeded" | "needs_review" | "failed" | "no_result"): Filter runs to these agent-reported results, as each run's `result` field reports it. Runs without a result never match. Provide as a comma-separated list. - `createdAfter` (string (date-time)): Only include runs created at or after this time - `createdBefore` (string (date-time)): Only include runs created at or before this time - `sortBy` (string, one of: "createdAt", default: "createdAt"): Field to sort runs by - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `ownerMemberId` (string): Filter runs to automations owned by this org member. Use `me` for the member the caller acts as. Organization API keys cannot use `me`. - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: List of runs - `runs` (array of object (AutomationRunSummary), required) --- ### GET /automations/runs/{runId} **Summary**: Get an automation run Get a run's prompt snapshot and final answer. **Required capabilities**: automations.list **Path parameters**: - `runId` (string, required): Automation run ID **Responses**: - `200`: Run with its final answer - `id` (string, required) - `automationId` (string, required) - `actionPrompt` (string, required): Snapshot of the automation's saved instructions. - `runPrompt` (string, required): Prompt submitted for this run. - `status` (string, one of: "pending" | "running" | "succeeded" | "failed", required) - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required) - `startedAt` (string (date-time), required, nullable) - `completedAt` (string (date-time), required, nullable) - `errorMessage` (string, required, nullable) - `execution` (string, one of: "pending" | "running" | "finished" | "error" | "blocked", required): Whether Foxglove ran the automation to the end, separate from what the run found. `finished` means the agent's turn ended, or a limit stopped the run after the agent reported its result. `blocked` means a limit or a missing permission stopped the run before that, such as the AI usage limit, the run's time limit, or an owner who lost access to the project. `error` means the run failed on Foxglove's side. - `result` (string, one of: "succeeded" | "needs_review" | "failed" | "no_result", required, nullable): What the agent reported the run accomplished. `needs_review` means the task finished but the agent was not sure whether something went wrong. `no_result` means the task ran and had nothing to act on, such as no matching data. Null when the agent did not report a result, for example because the run was blocked or failed before it finished. - `resultSummary` (string, required, nullable): The agent's one-sentence summary of what the run found or did. - `model` (string, required, nullable): Concrete model the run's chat used, such as `claude-sonnet-5-5`. Null until the run's chat exists. - `automationName` (string, required) - `finalAnswer` (string, required, nullable): The agent's final response: the last stretch of text, after any tool call before it, in the newest recent message that has text. For a failed run, set only when the run ended on that text. Null while the run is pending or running, when no recent message has text, or when the turn holding it was stopped or failed. - `trigger` (one of: object (AutomationTrigger) | null, required): The trigger whose event started the run, or null when the run was started manually. Editing a trigger replaces it with a new one, so its event type and configuration are as they were when the run started. `deletedAt` is set once the trigger has been replaced or removed. - `triggerSource` (one of: object (AutomationRunTriggerSource) | null, required): The recording, event, session, or device whose webhook event started the run, or null for manual and scheduled runs. Taken from the event saved with the run, so it names the item even after the item is deleted. - `tokenUsage` (object (AutomationRunTokenUsage), required, nullable): Token usage summed across model calls attached to the run's assistant messages, including tool-loop iterations and reported partial usage from failed calls. The buckets are disjoint; add all four for the total. Cache reads are input served from the prompt cache; cache writes combine 5-minute and 1-hour writes. Auxiliary calls without a message are excluded. Active runs report usage persisted so far. Null means no usage has been recorded, including runs that predate usage collection. - `cost` (object (AutomationRunCost), required, nullable): Estimated AI cost of the model calls counted in `tokenUsage`: the provider's list price plus the Foxglove fee of $1 per million tokens. Null exactly when `tokenUsage` is null. - `404`: Automation run not found --- ### DELETE /automations/runs/{runId} **Summary**: Delete an automation run Delete one run and its chat. The run no longer appears in run lists. A run that is still in progress stops. **Required capabilities**: automations.delete **Path parameters**: - `runId` (string, required): Automation run ID **Responses**: - `200`: The run was deleted - `success` (boolean, value: true, required) - `403`: Forbidden - `404`: Automation run not found --- ## Coverage Coverage provides the ability to see which time spans are available within Foxglove. ### GET /data/coverage **Summary**: List coverage A coverage range represents a time span for which Foxglove has data for a given device. You must specify the `start` and `end` arguments when making a coverage request. Note: By default, only coverage ranges with imported recordings are returned. To include coverage ranges with unimported recordings from an Edge Site or a device running Foxlet, set the `includeEdgeRecordings` query parameter to true **Required capabilities**: data.coverage.list **Query parameters**: - `start` (string (date-time)): Start of an inclusive time range - `end` (string (date-time)): End of an inclusive time range - `tolerance` (number): Minimum interval (in seconds) that ranges must be separated by to be considered discrete. Currently, the minimum meaningful value is 14s and smaller values will be clamped to this value. - `deviceId` (string): Filter coverage by device ID - `deviceName` (string): Name of device associated with the data - `includeEdgeRecordings` (boolean, default: false): Include recordings from an Edge Site or a device running Foxlet in the response. When edge recordings are included, each item in the response array will also include the `importStatus` for the coverage range. - `recordingId` (string): Filter coverage by recording ID - `recordingKey` (string): Filter coverage by recordingKey - `sessionId` (string): Filter coverage to recordings in the session with this ID - `sessionKey` (string): Filter coverage to recordings in the session with this key - `projectId` (string): Filter coverage by project **Responses**: - `200`: Coverage - Type: array of object (Coverage), with fields: - `deviceId` (string): ID of device. - `device` (object (CoverageDeviceSummary)): Device summary. - `start` (string (date-time), required): Start of this coverage - `end` (string (date-time), required): End of this coverage - `status` (string, one of: "at-edge" | "import-pending" | "imported", required, deprecated): The status of the coverage range - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete"): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. **Example** (Python): ```python from foxglove.client import Client from datetime import datetime, timedelta token = "" client = Client(token=token) client.get_coverage( start=datetime.now() - timedelta(hours=3), end=datetime.now() - timedelta(hours=1), ) ``` --- ## Custom Properties Custom properties are typed metadata which you can assign to devices, events, sessions, and episodes. 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. ### GET /custom-properties **Summary**: List custom properties **Required capabilities**: properties.list **Query parameters**: - `resourceType` (string, one of: "device" | "event" | "session" | "episode"): Filter properties matching a resource type **Responses**: - `200`: The custom properties - Type: array of object (CustomProperty), with fields: - `id` (string, required): ID of the custom property - `key` (string, required): Immutable key that identifies this property in queries. For example, use the key `partNumber` in the query `partNumber:456`. - `label` (string, required): Display label for user interfaces. May be changed after saving. - `resourceType` (string, one of: "device" | "event" | "session" | "episode", required): Resource type to which this custom property may be assigned - `valueType` (string, one of: "string" | "multiline-string" | "number" | "enum" | "boolean" | "multi-enum", required): The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats. - `values` (array of string, deprecated): Moved to `enumValues`. Allowed string values; required if `valueType` is "enum" - `enumValues` (array of string): Allowed string values; required if `valueType` is "enum" --- ### POST /custom-properties **Summary**: Create a custom property **Required capabilities**: properties.create **Request body** (JSON): - `key` (string, required): Immutable key that identifies this property in queries. For example, use the key `partNumber` in the query `partNumber:456`. - `label` (string, required): Display label for user interfaces. May be changed after saving. - `resourceType` (string, one of: "device" | "event" | "session" | "episode", required): Resource type to which this custom property may be assigned - `valueType` (string, one of: "string" | "multiline-string" | "number" | "enum" | "boolean" | "multi-enum", required): The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats. - `values` (array of string, deprecated): Moved to `enumValues`. Allowed string values; required if `valueType` is "enum" - `enumValues` (array of string): Allowed string values; required if `valueType` is "enum" **Responses**: - `200`: The custom property - `id` (string, required): ID of the custom property - `key` (string, required): Immutable key that identifies this property in queries. For example, use the key `partNumber` in the query `partNumber:456`. - `label` (string, required): Display label for user interfaces. May be changed after saving. - `resourceType` (string, one of: "device" | "event" | "session" | "episode", required): Resource type to which this custom property may be assigned - `valueType` (string, one of: "string" | "multiline-string" | "number" | "enum" | "boolean" | "multi-enum", required): The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats. - `values` (array of string, deprecated): Moved to `enumValues`. Allowed string values; required if `valueType` is "enum" - `enumValues` (array of string): Allowed string values; required if `valueType` is "enum" --- ### GET /custom-properties/{id} **Summary**: Get a custom property **Required capabilities**: properties.list **Path parameters**: - `id` (string, required): Custom Property ID **Responses**: - `200`: The custom property - `id` (string, required): ID of the custom property - `key` (string, required): Immutable key that identifies this property in queries. For example, use the key `partNumber` in the query `partNumber:456`. - `label` (string, required): Display label for user interfaces. May be changed after saving. - `resourceType` (string, one of: "device" | "event" | "session" | "episode", required): Resource type to which this custom property may be assigned - `valueType` (string, one of: "string" | "multiline-string" | "number" | "enum" | "boolean" | "multi-enum", required): The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats. - `values` (array of string, deprecated): Moved to `enumValues`. Allowed string values; required if `valueType` is "enum" - `enumValues` (array of string): Allowed string values; required if `valueType` is "enum" --- ### PATCH /custom-properties/{id} **Summary**: Edit a custom property **Required capabilities**: properties.update **Path parameters**: - `id` (string, required): Custom Property ID **Request body** (JSON): - `label` (string): Display label for user interfaces - `values` (array of string, deprecated): Moved to `enumValues`. Reorder or add to enum values. Must be a superset of existing values. - `enumValues` (array of string): Reorder or add to enum values. Must be a superset of existing values. **Responses**: - `200`: The custom property - `id` (string, required): ID of the custom property - `key` (string, required): Immutable key that identifies this property in queries. For example, use the key `partNumber` in the query `partNumber:456`. - `label` (string, required): Display label for user interfaces. May be changed after saving. - `resourceType` (string, one of: "device" | "event" | "session" | "episode", required): Resource type to which this custom property may be assigned - `valueType` (string, one of: "string" | "multiline-string" | "number" | "enum" | "boolean" | "multi-enum", required): The type of the values associated with this custom property Number values will be treated as IEEE 754 64-bit floats. - `values` (array of string, deprecated): Moved to `enumValues`. Allowed string values; required if `valueType` is "enum" - `enumValues` (array of string): Allowed string values; required if `valueType` is "enum" --- ### DELETE /custom-properties/{id} **Summary**: Delete a custom property Deleting a device custom property removes all values associated with it. Event custom properties can only be deleted when they are not currently associated with any event values. **Required capabilities**: properties.delete **Path parameters**: - `id` (string, required): Custom Property ID **Responses**: - `200`: ID of the deleted custom property - `id` (string, required) --- ## Datasets Datasets are project-scoped collections of episodes. Each dataset has a draft. Add or remove episodes in the draft, then commit it as a version, discard it, or restore an earlier version into it. All recordings in a dataset must be imported to the same Primary Site. ### POST /datasets **Summary**: Create a dataset Create a new dataset in the specified project, optionally pre-populated with an initial set of episodes. **Required capabilities**: datasets.create **Request body** (JSON): - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. Must be unique within the project (case-insensitive) among datasets. - `description` (string, nullable): Optional display description. - `episodeIds` (array of string): Optional initial set of episodes to add to the dataset. **Responses**: - `200`: The created dataset - `id` (string, required): ID of the dataset. - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. - `description` (string, nullable): Optional display description. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the dataset. Null when the dataset was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the dataset. Null when the dataset was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the dataset was created. - `updatedAt` (string (date-time), required): Timestamp when the dataset was last updated. - `episodeCount` (integer): Number of episodes in this dataset. - `added` (integer, required): Number of episodes inserted. - `updated` (integer, required): Number of episodes whose selected version changed in the dataset's draft. - `removed` (integer, required): Number of episodes removed from the dataset's draft. - `alreadyPresent` (integer, required): Number of episodes in the add request that were not inserted because an equivalent episode was already in the dataset, or appeared in the same request. - `400`: Bad request: a validation failure, inaccessible episodes, or episodes with recordings that are not imported to the same Primary Site. Code `RecordingNotImported` indicates a recording that is not imported, and code `DatasetSpansPrimarySites` indicates recordings at more than one Primary Site. - `404`: Project not found or not accessible - `409`: A dataset with that name already exists in this project --- ### GET /datasets **Summary**: List datasets List datasets. **Required capabilities**: datasets.list **Query parameters**: - `projectId` (string): Filter datasets by project. - `name` (string): Filter datasets to those whose name contains this value, ignoring case. - `sortBy` (string, one of: "name" | "createdAt" | "updatedAt" | "episodeCount", default: "createdAt"): Field to sort datasets by. Defaults to `createdAt`. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. **Responses**: - `200`: List of datasets - Type: array of object (DatasetResponse), with fields: - `id` (string, required): ID of the dataset. - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. - `description` (string, nullable): Optional display description. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the dataset. Null when the dataset was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the dataset. Null when the dataset was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the dataset was created. - `updatedAt` (string (date-time), required): Timestamp when the dataset was last updated. - `episodeCount` (integer): Number of episodes in this dataset. --- ### GET /datasets/{id} **Summary**: Get a dataset Get a single dataset by its ID. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID **Responses**: - `200`: The dataset - `id` (string, required): ID of the dataset. - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. - `description` (string, nullable): Optional display description. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the dataset. Null when the dataset was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the dataset. Null when the dataset was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the dataset was created. - `updatedAt` (string (date-time), required): Timestamp when the dataset was last updated. - `episodeCount` (integer): Number of episodes in this dataset. - `404`: Not found --- ### PATCH /datasets/{id} **Summary**: Edit a dataset Update a dataset's metadata. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID **Request body** (JSON): - `name` (string): Updated display name. Must be unique within the project (case-insensitive) among datasets. - `description` (string, nullable): Updated display description. Pass `null` to clear an existing description. **Responses**: - `200`: The updated dataset - `id` (string, required): ID of the dataset. - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. - `description` (string, nullable): Optional display description. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the dataset. Null when the dataset was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the dataset. Null when the dataset was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the dataset was created. - `updatedAt` (string (date-time), required): Timestamp when the dataset was last updated. - `episodeCount` (integer): Number of episodes in this dataset. - `400`: Bad request - `404`: Not found - `409`: A dataset with that name already exists in this project --- ### DELETE /datasets/{id} **Summary**: Delete a dataset Delete a dataset. **Required capabilities**: datasets.delete **Path parameters**: - `id` (string, required): Dataset ID **Responses**: - `200`: The dataset was deleted - `success` (boolean, value: true, required) - `404`: Not found --- ### GET /datasets/{id}/episodes **Summary**: List dataset episodes List the episodes in a dataset. Returns episodes from the latest committed dataset version, or from the draft if the dataset has no commits. Each episode is returned at the version used by that dataset version. Time filters apply to those episode versions. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID **Query parameters**: - `sortBy` (string, one of: "addedAt" | "createdAt" | "startTime" | "endTime", default: "addedAt"): Field to sort episodes by. `addedAt` is when the episode joined the dataset. Defaults to `addedAt`. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. - `start` (string (date-time)): Start of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `end` (string (date-time)): End of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `hasMissingRecordings` (boolean): Filter episodes by whether a member recording is no longer available. `true` returns only episodes with at least one missing recording. `false` returns only episodes whose recordings are all available. Omit to return all episodes. A recording counts as unavailable once no primary site holds data for it. - `recordingId` (string): Filter to episodes containing this recording display ID. - `propertiesQuery` (string): Filter custom properties at the selected episode version using space-separated key/value terms, for example `owner:ana status:accepted`. Terms are combined with AND. Quote values containing spaces, for example `task:"fold towel"`. Property filtering does not require `include=properties`; use that parameter to return the values in the response. - `include` (array of string, one of: "recordings" | "creationContext" | "properties"): Comma-separated list of optional related data to include on each episode. **Responses**: - `200`: List of dataset episodes - `episodes` (array of object (DatasetEpisodeResponse), required) - `404`: Not found --- ### PATCH /datasets/{id}/episodes **Summary**: Add, update, or remove dataset episodes Add or remove episodes, or change the episode versions used by the dataset's draft. This request does not commit the draft. - **Add by string ID:** An episode not already in the draft uses its latest version. An episode already in the draft keeps its existing episode version and counts as `alreadyPresent`. Re-adding an episode with a pending removal restores the episode version used by the last committed dataset version. - **Add by object reference:** The episode must not already be in the draft. Specify `version` to select an episode version; omit it to use the latest version. - **Update:** Changes the episode versions used by existing draft members. Omit `version` to use the latest episode version. - **Operation restrictions:** An episode in `update` cannot also appear in `add` or `remove`. An episode added as an object cannot also appear in `remove`. Repeated references to an episode must either all omit `version` or all specify the same version number. - **Duplicate content:** New additions with the same recordings, start time, and end time are treated as duplicates. An existing member is retained; otherwise, one duplicate is added. The remaining additions count as `alreadyPresent`. Version updates retain all members, even when their recordings and time ranges become identical. - **Single Primary Site:** Every recording of an added or updated episode must be imported, and all of the draft's recordings must be at the same Primary Site. A change that does not follow this rule is rejected. Removals are always allowed. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID **Request body** (JSON): - `add` (array of one of: string | object with id: string, version: integer): Episodes to add to the dataset's draft. - `update` (array of one of: string | object with id: string, version: integer): Existing episodes in the dataset's draft whose selected episode versions should change. - `remove` (array of string): Episode ids to remove. **Responses**: - `200`: Patch applied - `added` (integer, required): Number of episodes inserted. - `updated` (integer, required): Number of episodes whose selected version changed in the dataset's draft. - `removed` (integer, required): Number of episodes removed from the dataset's draft. - `alreadyPresent` (integer, required): Number of episodes in the add request that were not inserted because an equivalent episode was already in the dataset, or appeared in the same request. - `400`: Bad request: a validation failure, inaccessible episodes, or episodes with recordings that are not imported to the same Primary Site as the rest of the draft. Code `RecordingNotImported` indicates a recording that is not imported, and code `DatasetSpansPrimarySites` indicates recordings at more than one Primary Site. - `404`: Not found --- ### POST /datasets/{id}/commit **Summary**: Commit a new dataset version Commit the current changes as a new dataset version. Returns `409` when the current dataset version has no changes. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID **Request body** (JSON): - `description` (string, nullable): Description of the version. Set to null to clear it. If omitted, keeps the editable version's description. **Responses**: - `200`: The committed version and the new editable version number - `committed` (object (DatasetVersionResponse), required): The version that was committed. - `editableVersionNumber` (integer, required): The number of the new editable version opened by the commit. - `404`: Not found - `409`: The editable version has no changes to commit --- ### POST /datasets/{id}/discard **Summary**: Discard the editable version's changes Discard staged edits and reset the dataset to the last committed version. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID **Responses**: - `200`: Counts of the staged edits that were discarded - `discardedUpdates` (integer, required): Number of pending episode version changes discarded from the dataset's draft. - `discardedAdds` (integer, required): Number of staged additions that were deleted. - `discardedRemoves` (integer, required): Number of staged removals that were cleared. - `404`: Not found --- ### GET /datasets/{id}/versions **Summary**: List dataset versions List dataset versions. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID **Query parameters**: - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. **Responses**: - `200`: List of dataset versions - `versions` (array of object (DatasetVersionResponse), required) - `404`: Not found --- ### GET /datasets/{id}/versions/{versionNumber} **Summary**: Get a dataset version Get a single dataset version's metadata. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID - `versionNumber` (string, required): Version number **Responses**: - `200`: The dataset version - `description` (string): Description of the version. Omitted when the version has no description. - `versionNumber` (integer, required): The version's number. The highest-numbered version is the editable latest. - `committedAt` (string (date-time)): Omitted for the editable latest version; set once the version has been committed and its episode membership is saved. - `committedByOrgMemberId` (string): ID of the org member who committed the version. Omitted when committed via API-key auth or when the version is still editable. - `committedByApiKeyId` (string): ID of the API key that committed the version. Omitted when committed via session auth or when the version is still editable. - `createdAt` (string (date-time), required): Timestamp when the version was created. - `episodeCount` (integer, required): Total number of episodes in the dataset at this version. For the editable latest version, this is the current working set, including staged, uncommitted edits. - `addedEpisodeCount` (integer, required): Number of episodes added in this version, relative to the previous version. For the editable latest version, this is the count of staged, uncommitted additions. - `removedEpisodeCount` (integer, required): Number of episodes removed in this version, relative to the previous version. For the editable latest version, this is the count of staged, uncommitted removals. - `changedEpisodeCount` (integer, required): Number of episodes using a different episode version than in the previous dataset version. - `hasMissingRecordings` (boolean, required): True when at least one recording in this dataset version has no available data source. - `404`: Not found --- ### PATCH /datasets/{id}/versions/{versionNumber} **Summary**: Update a dataset version Edit the description of an editable or committed dataset version. This does not change episodes, commit attribution, or commit time. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID - `versionNumber` (string, required): Version number **Request body** (JSON): - `description` (string, required, nullable): Description of the version. Set to null to clear it. **Responses**: - `200`: The updated dataset version - `description` (string): Description of the version. Omitted when the version has no description. - `versionNumber` (integer, required): The version's number. The highest-numbered version is the editable latest. - `committedAt` (string (date-time)): Omitted for the editable latest version; set once the version has been committed and its episode membership is saved. - `committedByOrgMemberId` (string): ID of the org member who committed the version. Omitted when committed via API-key auth or when the version is still editable. - `committedByApiKeyId` (string): ID of the API key that committed the version. Omitted when committed via session auth or when the version is still editable. - `createdAt` (string (date-time), required): Timestamp when the version was created. - `episodeCount` (integer, required): Total number of episodes in the dataset at this version. For the editable latest version, this is the current working set, including staged, uncommitted edits. - `addedEpisodeCount` (integer, required): Number of episodes added in this version, relative to the previous version. For the editable latest version, this is the count of staged, uncommitted additions. - `removedEpisodeCount` (integer, required): Number of episodes removed in this version, relative to the previous version. For the editable latest version, this is the count of staged, uncommitted removals. - `changedEpisodeCount` (integer, required): Number of episodes using a different episode version than in the previous dataset version. - `hasMissingRecordings` (boolean, required): True when at least one recording in this dataset version has no available data source. - `404`: Dataset version not found --- ### GET /datasets/{id}/versions/{versionNumber}/episodes **Summary**: List a dataset version's episodes List the episodes in a dataset version. Each episode is returned at the version used by that dataset version. Time filters apply to those episode versions. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID - `versionNumber` (string, required): Version number **Query parameters**: - `sortBy` (string, one of: "addedAt" | "createdAt" | "startTime" | "endTime", default: "addedAt"): Field to sort episodes by. `addedAt` is when the episode joined the dataset. Defaults to `addedAt`. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. - `start` (string (date-time)): Start of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `end` (string (date-time)): End of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `hasMissingRecordings` (boolean): Filter episodes by whether a member recording is no longer available. `true` returns only episodes with at least one missing recording. `false` returns only episodes whose recordings are all available. Omit to return all episodes. A recording counts as unavailable once no primary site holds data for it. - `recordingId` (string): Filter to episodes containing this recording display ID. - `propertiesQuery` (string): Filter custom properties at the selected episode version using space-separated key/value terms, for example `owner:ana status:accepted`. Terms are combined with AND. Quote values containing spaces, for example `task:"fold towel"`. Property filtering does not require `include=properties`; use that parameter to return the values in the response. - `include` (array of string, one of: "recordings" | "creationContext" | "properties"): Comma-separated list of optional related data to include on each episode. **Responses**: - `200`: List of dataset episodes - `episodes` (array of object (DatasetEpisodeResponse), required) - `404`: Not found --- ### GET /datasets/{id}/versions/{versionNumber}/compare **Summary**: Compare two dataset versions List the episodes added, removed, or changed between two dataset versions. The `version` query parameter identifies the base dataset version; the path identifies the target dataset version. - `added`: The episode is in the target but not the base. - `removed`: The episode is in the base but not the target. - `changed`: The same episode is in both, but the dataset versions use different episode versions. For a changed episode, the returned details come from the episode version used by the target. `previousVersion` is the episode version number used by the base. Changes are ordered by episode start time and returned a page at a time; the response's counts cover the whole changeset. Pages are cursor-based: pass the previous page's `nextCursor` back as `cursor` to continue. Cursors are tied to the dataset, compared versions, and accessible project scope; restart the query if a cursor is rejected. A limit of 0 returns no changes or continuation cursor, while the counts still cover the whole changeset. **Required capabilities**: datasets.list **Path parameters**: - `id` (string, required): Dataset ID - `versionNumber` (string, required): Target version number **Query parameters**: - `version` (integer, required): The base version to compare against. - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. - `include` (array of string, one of: "recordings" | "creationContext" | "properties"): Comma-separated list of optional related data to include on each episode. **Responses**: - `200`: A page of the changeset between the two versions - `changes` (array of object (DatasetEpisodeChangeResponse), required): The requested page of changes, ordered by episode start time. - `addedCount` (integer, required): Total episodes present in the target version but not the base version. - `removedCount` (integer, required): Total episodes present in the base version but not the target version. - `changedCount` (integer, required): Total episodes present in both dataset versions but using different episode versions. - `nextCursor` (string, required, nullable): Pass this value as `cursor` to retrieve the next page. `null` on the last page. - `404`: Not found --- ### POST /datasets/{id}/versions/{versionNumber}/restore **Summary**: Restore a previous version Stage changes to make the dataset's draft match a previous dataset version, including the episode versions it uses. This does not commit the draft. Use `force=true` to replace pending draft changes. **Required capabilities**: datasets.update **Path parameters**: - `id` (string, required): Dataset ID - `versionNumber` (string, required): Dataset version to restore into the draft. **Query parameters**: - `force` (boolean, default: false): Replace any pending changes in the dataset's draft. **Responses**: - `200`: Counts of the staged edits applied by the restore - `updated` (integer, required): Number of episode version changes staged to match the restored dataset version. - `discardedUpdates` (integer, required): Number of previously pending episode version changes discarded during restore. - `added` (integer, required): Number of episodes staged for addition to match the restored version. - `removed` (integer, required): Number of episodes staged for removal to match the restored version. - `discardedAdds` (integer, required): Number of previously-staged additions discarded before applying the restore. - `discardedRemoves` (integer, required): Number of previously-staged removals discarded before applying the restore. - `400`: The restored draft would include recordings at more than one Primary Site (code `DatasetSpansPrimarySites`). - `404`: Not found - `409`: The dataset's draft has pending changes and `force` was not set --- ### POST /datasets/{id}/versions/{versionNumber}/clone **Summary**: Clone a dataset version Create a new dataset in the same project with the episodes and episode versions of a committed dataset version. The new dataset is independent: later changes to either dataset do not affect the other. By default, the new dataset has a single committed version. Set `includeHistory` to copy every version up to and including the cloned version instead. Either way, the new dataset has an empty draft on top of its latest version. **Required capabilities**: datasets.create **Path parameters**: - `id` (string, required): ID of the dataset to clone. - `versionNumber` (string, required): Committed dataset version to clone. **Request body** (JSON): - `name` (string, required): Display name of the new dataset. Must be unique within the project (case-insensitive) among datasets. - `description` (string, nullable): Optional display description of the new dataset. - `includeHistory` (boolean): Copy the source dataset's versions up to and including the cloned version, with their descriptions and commit details. **Responses**: - `200`: The new dataset - `id` (string, required): ID of the dataset. - `projectId` (string, required): ID of the project the dataset belongs to. - `name` (string, required): Display name. - `description` (string, nullable): Optional display description. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the dataset. Null when the dataset was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the dataset. Null when the dataset was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the dataset was created. - `updatedAt` (string (date-time), required): Timestamp when the dataset was last updated. - `episodeCount` (integer): Number of episodes in this dataset. - `400`: The cloned version includes recordings at more than one Primary Site (code `DatasetSpansPrimarySites`). - `404`: The dataset or committed version was not found - `409`: A dataset with that name already exists in this project --- ## Device Tokens Device tokens authenticate a device to the API. ### GET /device-tokens **Summary**: List device tokens **Required capabilities**: deviceTokens.list **Query parameters**: - `deviceId` (string): Filter by device ID **Responses**: - `200`: List of device tokens - Type: array of object (DeviceToken), with fields: - `id` (string, required) - `createdAt` (string (date-time), required): Timestamp of the device token's creation - `deviceId` (string, nullable): ID of the associated device - `projectId` (string, required): ID of the associated project - `enabled` (boolean, required): Whether this token is enabled or not - `preapproved` (boolean, required): Whether devices created with this token are preapproved --- ### POST /device-tokens **Summary**: Create a device token **Required capabilities**: deviceTokens.create **Request body** (JSON): - `deviceId` (string): Device ID associated with the newly created token. If not given, the token will be "unassociated" with a device and will only be usable after using it to create a device. - `projectId` (string): Project ID associated with the newly created token. If deviceId is provided, this must match the project of the device. If deviceId is omitted, this is required. - `enabled` (boolean): Whether this token is enabled or not. - `preapproved` (boolean): Whether devices created with this token are preapproved or not. **Responses**: - `200`: A new device token - `id` (string, required) - `createdAt` (string (date-time), required): Timestamp of the device token's creation - `deviceId` (string, nullable): ID of the associated device - `projectId` (string, required): ID of the associated project - `enabled` (boolean, required): Whether this token is enabled or not - `preapproved` (boolean, required): Whether devices created with this token are preapproved - `token` (string): Generated token. This is only available on creation. --- ### GET /device-tokens/{id} **Summary**: Get a device token **Required capabilities**: deviceTokens.list **Path parameters**: - `id` (string, required): Device token ID **Responses**: - `200`: The device token - `id` (string, required) - `createdAt` (string (date-time), required): Timestamp of the device token's creation - `deviceId` (string, nullable): ID of the associated device - `projectId` (string, required): ID of the associated project - `enabled` (boolean, required): Whether this token is enabled or not - `preapproved` (boolean, required): Whether devices created with this token are preapproved --- ### PATCH /device-tokens/{id} **Summary**: Edit a device token **Required capabilities**: deviceTokens.update **Path parameters**: - `id` (string, required): Device token ID **Request body** (JSON): - `enabled` (boolean, required): Enables or disables the device token. **Responses**: - `200`: The device token - `id` (string, required) - `createdAt` (string (date-time), required): Timestamp of the device token's creation - `deviceId` (string, nullable): ID of the associated device - `projectId` (string, required): ID of the associated project - `enabled` (boolean, required): Whether this token is enabled or not - `preapproved` (boolean, required): Whether devices created with this token are preapproved --- ### DELETE /device-tokens/{id} **Summary**: Delete a device token **Required capabilities**: deviceTokens.delete **Path parameters**: - `id` (string, required): Device token ID **Responses**: - `200`: The deleted device token ID - `id` (string, required): The device token ID --- ## 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 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](https://docs.foxglove.dev/api/custom-properties) and assign metadata to each device via its `properties`. ### GET /devices **Summary**: 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` 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). **Required capabilities**: devices.list **Query parameters**: - `projectId` (string): Filter devices by project - `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, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: List of devices - Type: array of object, with fields: - `id` (string, required): Opaque identifier - `name` (string, required): Organization-chosen device name - `projectId` (string, required): The project ID that the device belongs to - `retainRecordingsSeconds` (number): Retention period for recordings on a device running Foxlet, in seconds. Set to `0` to retain recordings indefinitely. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this device. - `enabled` (boolean, required): Whether this device is enabled. Devices are enabled by default, unless they are created with a device token with `preapproved` set to false. Disabled devices show up in the device list, but you can't upload recordings for them. A device token linked to a disabled device does not grant access to the API. - `remoteAccessEnabled` (boolean, required): Whether remote access is enabled for this device. When disabled, the device cannot establish new remote access sessions. - `autoDeleteAfterImport` (boolean, required): Whether recordings on this device are automatically deleted once they have been successfully uploaded and accepted for import. This is only relevant for devices that have Foxlet installed. - `orgId` (string) - `createdAt` (string (date)) - `updatedAt` (string (date-time)) **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.get_devices() ``` --- ### POST /devices **Summary**: Create a device **Required capabilities**: devices.create **Request body** (JSON): - `name` (string, required): The name of the device. - `properties` (object (CustomPropertyValues)): 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. - `projectId` (string): The project ID that the device belongs to. Required for multi-project orgs. **Responses**: - `200`: The newly created device - `id` (string, required): Opaque identifier - `name` (string, required): Organization-chosen device name - `projectId` (string, required): The project ID that the device belongs to - `retainRecordingsSeconds` (number): Retention period for recordings on a device running Foxlet, in seconds. Set to `0` to retain recordings indefinitely. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this device. - `enabled` (boolean, required): Whether this device is enabled. Devices are enabled by default, unless they are created with a device token with `preapproved` set to false. Disabled devices show up in the device list, but you can't upload recordings for them. A device token linked to a disabled device does not grant access to the API. - `remoteAccessEnabled` (boolean, required): Whether remote access is enabled for this device. When disabled, the device cannot establish new remote access sessions. - `autoDeleteAfterImport` (boolean, required): Whether recordings on this device are automatically deleted once they have been successfully uploaded and accepted for import. This is only relevant for devices that have Foxlet installed. - `orgId` (string) - `createdAt` (string (date)) - `updatedAt` (string (date-time)) **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.create_device( name=name, project_id="", ) ``` --- ### POST /actions/devices/{nameOrId}/update-property-time-interval **Summary**: Update property time interval 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](https://docs.foxglove.dev/api/devices/update-a-device) endpoint. **Required capabilities**: devices.update **Path parameters**: - `nameOrId` (string, required): 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** (JSON): - `projectId` (string): The project ID of the device. Required for multi-project orgs. - `key` (string, required): The key of the property. Must be an existing device custom property key for your organization. - `value` (one of: string | number | boolean | array of string): The value of the property over the given time range. Omit to specify no value was set for that range. - `start` (string (date-time), required): Inclusive start of the property's effective time range. Must be in the past. - `end` (string (date-time), required): Exclusive end of the property's effective time range. Must be in the past. **Responses**: - `204`: Success --- ### GET /devices/{nameOrId} **Summary**: Get a device Get details on a specific device. **Required capabilities**: devices.list **Path parameters**: - `nameOrId` (string, required): 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. **Query parameters**: - `projectId` (string): Filter devices by project **Responses**: - `200`: Success - `id` (string, required): Opaque identifier - `name` (string, required): Organization-chosen device name - `projectId` (string, required): The project ID that the device belongs to - `retainRecordingsSeconds` (number): Retention period for recordings on a device running Foxlet, in seconds. Set to `0` to retain recordings indefinitely. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this device. - `enabled` (boolean, required): Whether this device is enabled. Devices are enabled by default, unless they are created with a device token with `preapproved` set to false. Disabled devices show up in the device list, but you can't upload recordings for them. A device token linked to a disabled device does not grant access to the API. - `remoteAccessEnabled` (boolean, required): Whether remote access is enabled for this device. When disabled, the device cannot establish new remote access sessions. - `autoDeleteAfterImport` (boolean, required): Whether recordings on this device are automatically deleted once they have been successfully uploaded and accepted for import. This is only relevant for devices that have Foxlet installed. **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.get_device( device_id=device_id, ) ``` --- ### DELETE /devices/{nameOrId} **Summary**: 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._ **Required capabilities**: devices.delete **Path parameters**: - `nameOrId` (string, required): 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. **Query parameters**: - `projectId` (string): Filter devices by project **Responses**: - `200`: Success - `id` (string, required): The ID of the deleted device **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.delete_device(device_id=device_id) ``` --- ### PATCH /devices/{nameOrId} **Summary**: Update a device **Required capabilities**: devices.update **Path parameters**: - `nameOrId` (string, required): 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. **Query parameters**: - `projectId` (string): Filter devices by project **Request body** (JSON): - `name` (string): Device names must be unique within a project. - `retainRecordingsSeconds` (integer): Retention period for recordings on a device running Foxlet, in seconds. Set to `0` to retain recordings indefinitely. - `properties` (object): A key-value map from device custom property keys to their values. Unknown keys are ignored. Omitted keys are unchanged. Set a value to `null` to remove it. - `enabled` (boolean): Whether this device is enabled. Devices are enabled by default, unless they are created with a device token with `preapproved` set to false. Disabled devices show up in the device list, but you can't upload recordings for them. A device token linked to a disabled device does not grant access to the API. - `remoteAccessEnabled` (boolean): Whether remote access is enabled for this device. When disabled, the device cannot establish new remote access sessions. - `autoDeleteAfterImport` (boolean): Whether recordings on a device running Foxlet are automatically deleted once they have been successfully uploaded and accepted for import. This is only relevant for devices that have Foxlet installed. Foxlet versions older than 1.5.0 ignore this setting until upgraded. **Responses**: - `200`: Update device - `id` (string, required): Opaque identifier - `name` (string, required): Organization-chosen device name - `projectId` (string, required): The project ID that the device belongs to - `retainRecordingsSeconds` (number): Retention period for recordings on a device running Foxlet, in seconds. Set to `0` to retain recordings indefinitely. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this device. - `enabled` (boolean, required): Whether this device is enabled. Devices are enabled by default, unless they are created with a device token with `preapproved` set to false. Disabled devices show up in the device list, but you can't upload recordings for them. A device token linked to a disabled device does not grant access to the API. - `remoteAccessEnabled` (boolean, required): Whether remote access is enabled for this device. When disabled, the device cannot establish new remote access sessions. - `autoDeleteAfterImport` (boolean, required): Whether recordings on this device are automatically deleted once they have been successfully uploaded and accepted for import. This is only relevant for devices that have Foxlet installed. --- ### GET /devices/{nameOrId}/property-time-intervals **Summary**: List property time intervals Returns a list of values and the time intervals for which they were in effect for a device. Use the `query` parameter to filter property history on custom property key/value criteria. Syntax: * `key:value`: matches rows where the property key is `key` and the value equals `value`; use double quotes if the value contains spaces or special characters * `key:value1,value2`: matches rows where the property key is `key` and the value is either `value1` or `value2` * `key:*`: matches rows where the property key is `key` and any value * `*:value`: matches rows where any key has the value `value` * `foo`: matches rows where any key or stringified value contains `foo` Multiple qualifiers can be used in the same query string; this will filter rows matching the intersection of the qualifiers (AND). **Required capabilities**: devices.list **Path parameters**: - `nameOrId` (string, required): 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. **Query parameters**: - `projectId` (string): The project ID that the device belongs to. Required for multi-project orgs. - `query` (string): Space-separated query string for device property history. Each custom property key must be valid. See above for syntax and examples. - `start` (string (date-time)): Properties active on or after this time will be included. - `end` (string (date-time)): Properties active before this time will be included. - `sortBy` (string, one of: "id" | "key" | "start" | "end"): Field to sort items by ("id", "key", "start", "end") - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `offset` (integer, default: 0): Number of items to skip before returning the results - `limit` (number, default: 2000): Maximum number of items to return **Responses**: - `200`: Property time intervals - Type: array of object (DeviceCustomPropertyTimeInterval), with fields: - `id` (string, required): ID of the property time interval. - `deviceId` (string, required): ID of the associated device. - `key` (string, required): Key of the property. - `value` (one of: string | number | boolean | array of string, required): Value of the property. - `start` (string (date-time), required): Inclusive start time this value was in effect. - `end` (string (date-time)): Exclusive end time this value was in effect. When absent the value is still in effect. --- ### GET /devices/{nameOrId}/property-time-intervals/{id} **Summary**: Get a device property time interval Returns a specific device property time interval for a device. **Required capabilities**: devices.list **Path parameters**: - `nameOrId` (string, required): 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. - `id` (string, required): Property Time Interval ID. **Query parameters**: - `projectId` (string): The project ID that the device belongs to. Required for multi-project orgs. **Responses**: - `200`: Property time interval - `id` (string, required): ID of the property time interval. - `deviceId` (string, required): ID of the associated device. - `key` (string, required): Key of the property. - `value` (one of: string | number | boolean | array of string, required): Value of the property. - `start` (string (date-time), required): Inclusive start time this value was in effect. - `end` (string (date-time)): Exclusive end time this value was in effect. When absent the value is still in effect. --- ## Episodes An episode is a time range over one or more recordings, with optional custom properties. Each effective change creates a new episode version. All recordings in an episode must be imported to the same Primary Site. Recordings that are only on an Edge Site or a device cannot be part of an episode. ### POST /episodes **Summary**: Get or create episodes Create new episodes, or return existing ones. An existing episode is returned when the time range, member recordings, and custom properties of its latest version exactly match the request. A request without custom properties matches only an episode whose latest version has none. An episode's time range is a closed window from `startTime` to `endTime`, at nanosecond precision. Equal times describe a single instant. Omit `startTime` and `endTime` to infer the time range from the recordings. Alternatively, provide `eventId` to snapshot the event's time range, including an instant event, and the completed recordings overlapping its device and time range. Event inputs in one request can resolve at most 10,000 recording memberships. Across all `episodes[].recordings` lists, a request may contain at most 100,000 recording memberships. Duplicate recording IDs within an episode count once; a recording listed in multiple episodes counts once per episode. Event edits and later imports do not change existing episodes. **Required capabilities**: episodes.create **Request body** (JSON): - `projectId` (string, required): ID of the project the episodes belong to. - `episodes` (array of object, required): The episodes to get or create. Must contain at least one episode. - `eventId` (string): Event to resolve into an episode at creation time. - `recordings` (array of string): Member recording display IDs. Requires at least one recording. Recordings must be from the same device, or all deviceless, and must all be imported to the same Primary Site. - `startTime` (string (date-time), nullable): Inclusive start of the episode window, with up to nanosecond precision. Omit to infer from the member recordings. - `endTime` (string (date-time), nullable): Inclusive end of the episode window, with up to nanosecond precision. Equal to `startTime` for a single instant. Omit to infer from the member recordings. - `properties` (object (EpisodeProperties)) **Responses**: - `200`: The existing or newly created episodes - `episodes` (array of object, required): The existing or newly created episodes, in request order. - `400`: Bad request. Code `EventRecordingMembershipLimitExceeded` indicates that event inputs exceed the recording-membership budget; split the events into smaller requests. Code `RecordingMembershipLimitExceeded` indicates that recording lists exceed 100,000 memberships; split the episodes into smaller requests. Code `RecordingNotImported` indicates an episode with a recording that is not imported to a Primary Site, and code `EpisodeSpansPrimarySites` indicates an episode with recordings at more than one Primary Site. - `404`: Not found - `429`: Episode creation limit reached (code `EpisodeCreationLimitExceeded`) --- ### GET /episodes **Summary**: List episodes List the latest version of each episode. **Required capabilities**: episodes.list **Query parameters**: - `projectId` (string): Filter episodes by project. - `start` (string (date-time)): Start of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `end` (string (date-time)): End of the range to match against episode time windows. Episodes that overlap the range are included. Provide both `start` and `end`. - `hasMissingRecordings` (boolean): Filter episodes by whether a member recording is no longer available. `true` returns only episodes with at least one missing recording. `false` returns only episodes whose recordings are all available. Omit to return all episodes. A recording counts as unavailable once no primary site holds data for it. - `recordingId` (string): Filter to episodes containing this recording display ID. - `exactRecordingIds` (array of string): Match episodes containing exactly these recording IDs. Provide a comma-separated list. Duplicate IDs are ignored. - `propertiesQuery` (string): Filter custom properties at the selected episode version using space-separated key/value terms, for example `owner:ana status:accepted`. Terms are combined with AND. Quote values containing spaces, for example `task:"fold towel"`. Property filtering does not require `include=properties`; use that parameter to return the values in the response. - `sortBy` (string, one of: "createdAt" | "startTime" | "endTime", default: "createdAt"): Field to sort episodes by. Defaults to `createdAt`. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. - `include` (array of string, one of: "recordings" | "creationContext" | "properties"): Comma-separated list of optional related data to include on each episode. **Responses**: - `200`: The matching episodes - `episodes` (array of object (EpisodeResponse), required) - `404`: Not found --- ### PATCH /episodes **Summary**: Update episodes Apply all episode changes in one transaction. Each effective change creates an episode version. An unchanged episode keeps its version. Results preserve request order. Duplicate episode IDs are rejected. If any update fails, no updates are applied. **Required capabilities**: episodes.update **Request body** (JSON): - `episodes` (array of object (EpisodeBulkPatch), required) - `id` (string, required) - `appliesToVersion` (integer): Require this current episode version. Omit to update the latest version. - `startTime` (string (date-time)): Inclusive start of the episode window, with up to nanosecond precision. - `endTime` (string (date-time)): Inclusive end of the episode window, with up to nanosecond precision. Must not be before `startTime`. Equal times describe a single instant. - `recordings` (object): Add or remove recording display IDs from this episode. After the change, all of the episode's recordings must be imported to the same Primary Site. - `add` (array of string) - `remove` (array of string) - `properties` (object (EpisodePropertyPatch)): Merge the supplied keys into the current version's properties. Omitted keys retain their values. Set a key to null to remove its assignment. An empty object makes no changes. Previous episode versions retain their property values. **Responses**: - `200`: The episode versions produced by the request - `episodes` (array of object, required) - `400`: Invalid changes or duplicate episode IDs. Code `RecordingNotImported` indicates a recording that is not imported to a Primary Site, and code `EpisodeSpansPrimarySites` indicates recordings at more than one Primary Site. - `404`: One or more episodes do not exist or are inaccessible - `409`: The episode changed since `appliesToVersion`, it has reached its maximum version number, or its stored data must be repaired before it can be updated; no updates were applied --- ### GET /episodes/{id}/versions **Summary**: List episode versions List episode versions from newest to oldest, with their authors and changed fields. **Required capabilities**: episodes.list **Path parameters**: - `id` (string, required): Episode ID **Query parameters**: - `limit` (number, default: 2000): Maximum number of items to return - `cursor` (string): Opaque cursor from the `fg-pagination-next-cursor` or, where supported, `fg-pagination-previous-cursor` response header. **Responses**: - `200`: The episode's version history - `versions` (array of object (EpisodeVersionResponse), required) - `404`: Episode not found --- ### GET /episodes/{id} **Summary**: Get an episode Get an episode by its ID. Omit version to return its latest version. **Required capabilities**: episodes.list **Path parameters**: - `id` (string, required): Episode ID **Query parameters**: - `version` (integer): Episode version to read. Defaults to the latest version. - `include` (array of string, one of: "recordings" | "properties"): Comma-separated list of optional related data to include on the episode. **Responses**: - `200`: The episode - `version` (integer, required): The episode version represented by this response. - `latestVersion` (integer, required): The episode's latest version at the time of this read. - `properties` (object (EpisodeProperties)): Custom properties at the selected version. Returned only with `include=properties`. - `creationContext` (object (EpisodeCreationContext), nullable): Original creation context. Always present when fetching an episode by ID; present on list responses only with `?include=creationContext`. - `id` (string, required): ID of the episode. - `projectId` (string, required): ID of the project the episode belongs to. - `startTime` (string (date-time), required): Inclusive start of the episode window, with up to nanosecond precision. - `endTime` (string (date-time), required): Inclusive end of the episode window, with up to nanosecond precision. Equal to `startTime` for a single instant. - `recordings` (array of object): Member recordings. Present only when the request includes `?include=recordings`. - `hasMissingRecordings` (boolean): Whether any member recording has no data at a Primary Site. Returned by episode endpoints only with `include=recordings`. Dataset endpoints report this on the containing dataset entry instead. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the episode. Null when the episode was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the episode. Null when the episode was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the episode was created. - `404`: Not found --- ### PATCH /episodes/{id} **Summary**: Update an episode Update an episode and return the resulting version. Effective changes create a version. If nothing changes, the current version is returned. **Required capabilities**: episodes.update **Path parameters**: - `id` (string, required): Episode ID **Request body** (JSON): - `appliesToVersion` (integer): Require this current episode version. Omit to update the latest version. - `startTime` (string (date-time)): Inclusive start of the episode window, with up to nanosecond precision. - `endTime` (string (date-time)): Inclusive end of the episode window, with up to nanosecond precision. Must not be before `startTime`. Equal times describe a single instant. - `recordings` (object): Add or remove recording display IDs from this episode. After the change, all of the episode's recordings must be imported to the same Primary Site. - `add` (array of string) - `remove` (array of string) - `properties` (object (EpisodePropertyPatch)): Merge the supplied keys into the current version's properties. Omitted keys retain their values. Set a key to null to remove its assignment. An empty object makes no changes. Previous episode versions retain their property values. **Responses**: - `200`: The episode at the resulting version - `version` (integer, required): The episode version represented by this response. - `latestVersion` (integer, required): The episode's latest version at the time of this read. - `properties` (object (EpisodeProperties)): Custom properties at the selected version. Returned only with `include=properties`. - `creationContext` (object (EpisodeCreationContext), nullable): Original creation context. Always present when fetching an episode by ID; present on list responses only with `?include=creationContext`. - `id` (string, required): ID of the episode. - `projectId` (string, required): ID of the project the episode belongs to. - `startTime` (string (date-time), required): Inclusive start of the episode window, with up to nanosecond precision. - `endTime` (string (date-time), required): Inclusive end of the episode window, with up to nanosecond precision. Equal to `startTime` for a single instant. - `recordings` (array of object): Member recordings. Present only when the request includes `?include=recordings`. - `hasMissingRecordings` (boolean): Whether any member recording has no data at a Primary Site. Returned by episode endpoints only with `include=recordings`. Dataset endpoints report this on the containing dataset entry instead. - `creatorOrgMemberId` (string, nullable): ID of the org member who created the episode. Null when the episode was created via API-key auth (in which case `creatorApiKeyId` is set). - `creatorApiKeyId` (string, nullable): ID of the API key that created the episode. Null when the episode was created via session auth (in which case `creatorOrgMemberId` is set). - `createdAt` (string (date-time), required): Timestamp when the episode was created. - `400`: Invalid changes or duplicate episode IDs. Code `RecordingNotImported` indicates a recording that is not imported to a Primary Site, and code `EpisodeSpansPrimarySites` indicates recordings at more than one Primary Site. - `404`: One or more episodes do not exist or are inaccessible - `409`: The episode changed since `appliesToVersion`, it has reached its maximum version number, or its stored data must be repaired before it can be updated; no updates were applied --- ### DELETE /episodes/{id} **Summary**: Delete an episode Deletes an episode. **Required capabilities**: episodes.delete **Path parameters**: - `id` (string, required): Episode ID **Responses**: - `200`: The episode was deleted - `success` (boolean, value: true, required) - `404`: Not found - `409`: The episode belongs to a dataset and cannot be deleted --- ## 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. ### GET /events **Summary**: List events Retrieve a list of events. Use the `query` parameter to filter events on key/value criteria. The `queryFields` parameter can be used in combination with `query` to specify which fields to filter events by. Syntax: * `key:value`: matches events with metadata 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 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). **Required capabilities**: events.list **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 - `projectId` (string): Filter events by project - `deviceId` (string): Filter events matching device ID - `eventId` (string): Filter events by exact event ID - `deviceName` (string): Name 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. - `queryFields` (array of string, one of: "metadata" | "properties"): Which fields to query events by. Defaults to "metadata". - `sortBy` (string, one of: "id" | "deviceId" | "deviceName" | "device.name" | "device.id" | "start" | "createdAt" | "updatedAt"): field to sort response items by - `eventTypeId` (string): Filter events by their event type. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: A list of device events - Type: array of object (Event), with fields: - `id` (string, required): ID of the event - `start` (string (date-time), required): Event start time (inclusive) - `end` (string (date-time), required): Event end time (inclusive) - `deviceId` (string, deprecated): ID of the device associated with the event. **deprecated**: Use `device.id` instead. - `device` (object (DeviceSummary)): ID and name of a device. - `metadata` (object, required): Any metadata associated with the event - `createdAt` (string (date-time), required): When the event was created - `updatedAt` (string (date-time), required): When the event was last updated - `eventTypeId` (string): ID of the event type. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this event. **Example** (Python): ```python from foxglove.client import Client from datetime import datetime, timedelta token = "" 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" ) ``` --- ### POST /events **Summary**: Create an event Create an event associated with a device. Provide a device ID or name. **Required capabilities**: events.create **Request body** (JSON): - `deviceId` (string): ID of the device to associate with the event - `deviceName` (string): Name of the device to associate with the event - `projectId` (string): Optional project ID used to disambiguate deviceName and deviceId lookups - `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 - `metadata` (object (EventMetadataInput)): An object with user-defined string keys and string values; key order is not preserved - `start` (string (date-time), required): Event start time (inclusive) - `end` (string (date-time), required): Event end time (inclusive) - `eventTypeId` (string): If provided, the event must conform to the event type's schema. - `properties` (object (CustomPropertyValues)): A key-value map, where each key is one of your pre-defined event custom property keys. Keys which are not recognized as custom properties will be ignored. **Responses**: - `200`: The created event - `id` (string, required): ID of the event - `start` (string (date-time), required): Event start time (inclusive) - `end` (string (date-time), required): Event end time (inclusive) - `deviceId` (string, deprecated): ID of the device associated with the event. **deprecated**: Use `device.id` instead. - `device` (object (DeviceSummary)): ID and name of a device. - `metadata` (object, required): Any metadata associated with the event - `createdAt` (string (date-time), required): When the event was created - `updatedAt` (string (date-time), required): When the event was last updated - `eventTypeId` (string): ID of the event type. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this event. **Example** (Python): ```python from foxglove.client import Client from datetime import datetime, timedelta token = "" client = Client(token=token) event_time = datetime.now() client.create_event( device_id=device_id, start=event_time, end=event_time, metadata={"message": "Hi from python!"} ) ``` --- ### GET /events/{id} **Summary**: Get an event **Required capabilities**: events.list **Path parameters**: - `id` (string, required): ID of the event **Responses**: - `200`: The event - `id` (string, required): ID of the event - `start` (string (date-time), required): Event start time (inclusive) - `end` (string (date-time), required): Event end time (inclusive) - `deviceId` (string, deprecated): ID of the device associated with the event. **deprecated**: Use `device.id` instead. - `device` (object (DeviceSummary)): ID and name of a device. - `metadata` (object, required): Any metadata associated with the event - `createdAt` (string (date-time), required): When the event was created - `updatedAt` (string (date-time), required): When the event was last updated - `eventTypeId` (string): ID of the event type. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this event. --- ### DELETE /events/{id} **Summary**: Delete an event **Required capabilities**: events.delete **Path parameters**: - `id` (string, required): ID of the event **Responses**: - `200`: ID of the deleted event - `id` (string, required): ID of the deleted event. **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.delete_event( event_id=event_id, ) ``` --- ### PATCH /events/{id} **Summary**: Update an event **Required capabilities**: events.update **Path parameters**: - `id` (string, required): ID of the event **Request body** (JSON): - `metadata` (object (EventMetadataInput)): 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) - `properties` (object (EventUpdatePropertiesInput)): A key-value map from event custom property keys to their values. Unknown keys are ignored. Omitted keys are unchanged. Set a value to `null` to remove it. - `eventTypeId` (string): If provided, the event must conform to the event type's schema. An empty string will remove the event type. **Responses**: - `200`: The updated event - `id` (string, required): ID of the event - `start` (string (date-time), required): Event start time (inclusive) - `end` (string (date-time), required): Event end time (inclusive) - `deviceId` (string, deprecated): ID of the device associated with the event. **deprecated**: Use `device.id` instead. - `device` (object (DeviceSummary)): ID and name of a device. - `metadata` (object, required): Any metadata associated with the event - `createdAt` (string (date-time), required): When the event was created - `updatedAt` (string (date-time), required): When the event was last updated - `eventTypeId` (string): ID of the event type. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this event. --- ## Event Types Event types help ensure data quality through validation, enable better filtering and analytics, and provide visual distinctions between categories of events. ### GET /event-types **Summary**: List event types **Required capabilities**: eventTypes.list **Responses**: - `200`: A list of event types - Type: array of object, with fields: - `id` (string, required): ID of the event type - `name` (string, required): Name of the event type - `createdAt` (string (date-time), required): When the event type was created - `updatedAt` (string (date-time), required): When the event type was last updated - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty)): Ordered array of custom properties associated with the event type --- ### POST /event-types **Summary**: Create an event type **Required capabilities**: eventTypes.create **Request body** (JSON): - `name` (string, required): Name of the event type - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty), required): Ordered array of custom properties associated with the event type - `id` (string, required): ID of the custom property - `required` (boolean, required): Whether the custom property is required for this event type **Responses**: - `200`: The created event type - `id` (string, required): ID of the event type - `name` (string, required): Name of the event type - `createdAt` (string (date-time), required): When the event type was created - `updatedAt` (string (date-time), required): When the event type was last updated - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty)): Ordered array of custom properties associated with the event type - `400`: Bad request: a validation failure, `customProperties` with duplicate IDs, or `customProperties` IDs that do not name an `event` custom property in the org. The error message for unknown properties lists the rejected IDs. --- ### GET /event-types/{id} **Summary**: Get an event type **Required capabilities**: eventTypes.list **Path parameters**: - `id` (string, required): ID of the event type **Responses**: - `200`: The event type - `id` (string, required): ID of the event type - `name` (string, required): Name of the event type - `createdAt` (string (date-time), required): When the event type was created - `updatedAt` (string (date-time), required): When the event type was last updated - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty)): Ordered array of custom properties associated with the event type --- ### PATCH /event-types/{id} **Summary**: Update an event type **Required capabilities**: eventTypes.update **Path parameters**: - `id` (string, required): ID of the event type **Request body** (JSON): - `name` (string): Name of the event type - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty)): Ordered array of custom properties associated with the event type. This will replace the existing customProperties list. - `id` (string, required): ID of the custom property - `required` (boolean, required): Whether the custom property is required for this event type **Responses**: - `200`: The updated event type - `id` (string, required): ID of the event type - `name` (string, required): Name of the event type - `createdAt` (string (date-time), required): When the event type was created - `updatedAt` (string (date-time), required): When the event type was last updated - `colorName` (string): Color name of the event type, e.g. "red" - `customProperties` (array of object (EventTypeCustomProperty)): Ordered array of custom properties associated with the event type --- ### DELETE /event-types/{id} **Summary**: Delete an event type **Required capabilities**: eventTypes.delete **Path parameters**: - `id` (string, required): ID of the event type **Responses**: - `200`: ID of the deleted event type - `id` (string, required): ID of the deleted event type --- ## Imports **The Imports endpoints are deprecated. Use the [Recordings](https://docs.foxglove.dev/api/recordings) endpoints instead.** Imports are recordings that are available at a Primary Site. ### GET /data/imports **DEPRECATED** **Summary**: List imports **This endpoint is deprecated. Use the [list recordings](https://docs.foxglove.dev/api/recordings/list-recordings) endpoint instead.** **Required capabilities**: data.imports.list **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, one of: "importId" | "deviceId" | "importTime" | "dataStart" | "dataEnd"): Sort by a single field of the import type - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: Success - Type: array of object (Import), with fields: - `id` (string, required): Opaque ID - `importId` (string, required, deprecated) - `orgId` (string, required) - `deviceId` (string) - `deviceName` (string) - `filename` (string, required) - `importTime` (string (date-time), required): Imported timestamp - `start` (string (date-time), required): Message log time start of imported data - `end` (string (date-time), required): 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) **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.get_imports() ``` --- ### DELETE /data/imports **DEPRECATED** **Summary**: Delete multiple imports 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._ **Required capabilities**: data.imports.delete **Query parameters**: - `id` (array of string, required): ID of import to delete. You can specify up to 50 IDs (for example, `?id=abc&id=def&...`). **Responses**: - `200`: Success - `deletionResults` (array of object, required) --- ### DELETE /data/imports/{importId} **DEPRECATED** **Summary**: Delete an import **This endpoint is deprecated. Use the [delete recording](https://docs.foxglove.dev/api/recordings/delete-a-recording) endpoint instead.** Deleting an import deletes all data associated with the import. **This action is permanent and cannot be undone.** **Required capabilities**: data.imports.delete **Path parameters**: - `importId` (string, required): The `importId` of an import **Responses**: - `200`: Success - `id` (string, required) **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.delete_import( device_id=device_id, import_id=import_id, ) ``` --- ## Lake files MCAP files stored in the lake bucket of a [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). You must have an Enterprise account to use lake file endpoints. ### GET /lake-files **Summary**: 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 specific 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 unless a recording or session selector is supplied. Queries for a specific recording or session do not require `start` and `end`, even when a device filter is supplied. The range expressed by `start` and `end` must not exceed 24h. **Required capabilities**: data.stream **Query parameters**: - `siteId` (string, required): 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 - `sessionId` (string): Filter to files for recordings in the session with this ID - `sessionKey` (string): Filter to files for recordings in the session with this key - `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**: - `200`: Success - Type: array of object, with fields: - `path` (string, required): The full path of the file in the lake bucket - `topics` (array of string, required): The topic names associated with this file --- ## Projects [Projects](https://docs.foxglove.dev/docs/projects) are a container for organizing data and resources in Foxglove. Your plan must support managing projects. ### GET /projects **Summary**: List projects List all projects available to the authorized client **Required capabilities**: projects.list **Responses**: - `200`: Success - Type: array of object (Project), with fields: - `id` (string, required) - `name` (string) - `orgMemberCount` (number): Number of org members that can access this project - `lastSeenAt` (string (date-time), deprecated): Deprecated. This value is no longer updated and does not reflect the latest recording uploaded to this project. - `isInviteOnly` (boolean, required): Whether this project is invite-only. If true, org members with the user role will need explicit permission to access the project --- ### PATCH /projects/{id}/members **Summary**: Add or remove project members Add organization members to a project, or remove them from it. `action` is `add` or `remove`. `memberIds` accepts at most 50 member IDs. A member who already has the requested access is left unchanged and omitted from `affectedMemberIds`. Members with the user role need this access to use an invite-only project. Organization admins can access every project. Members can access a project that is not invite-only without being added here. For `add`, every ID must belong to a member of the organization. If one ID is unknown, the request returns 404 and adds no members. For `remove`, unknown IDs are ignored. Repeated IDs are treated as one, and an empty list changes nothing. An API key limited to projects can change membership only for those projects. **Required capabilities**: projectMembers.update **Path parameters**: - `id` (string, required): Project ID **Request body** (JSON): - `action` (string, one of: "add" | "remove", required): Action to perform. - `memberIds` (array of string, required): Member IDs to add to or remove from this project. **Responses**: - `200`: Success - `affectedMemberIds` (array of string, required): Newly-added or -removed member IDs. - `404`: The project is not accessible, or an ID to add is not a member of the organization. No members are added. --- ## Recording Attachments A recording attachment resource represents information about an MCAP attachment imported to Foxglove. Attachments are available for individual download or with their recording. ### GET /recording-attachments **Summary**: List attachments **Required capabilities**: recordings.list **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 - `sortBy` (string, one of: "logTime"): Sort by a single field of the attachment - `projectId` (string): Filter attachments by project - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: Success - Type: array of object (RecordingAttachment), with fields: - `id` (string, required): ID of the attachment - `recordingId` (string, required): ID of the recording with which the attachment is associated - `siteId` (string, required): ID of the Primary Site where the attachment data is stored - `name` (string, required): Name field from the attachment record - `mediaType` (string, required): Media type from the attachment record - `logTime` (string, required): Log time field from the attachment record - `createTime` (string, required): Create time field from the attachment record - `crc` (number, required): CRC field from the attachment record as a decimal number - `dataOffset` (integer): Offset to the start of the attachment in bytes - `size` (integer, required): Size of the attachment in bytes - `fingerprint` (string, required): 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](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.get_attachments() ``` --- ### GET /recording-attachments/{id} **Summary**: Get an attachment **Required capabilities**: recordings.list **Path parameters**: - `id` (string, required): ID of the attachment **Responses**: - `200`: Success - `id` (string, required): ID of the attachment - `recordingId` (string, required): ID of the recording with which the attachment is associated - `siteId` (string, required): ID of the Primary Site where the attachment data is stored - `name` (string, required): Name field from the attachment record - `mediaType` (string, required): Media type from the attachment record - `logTime` (string, required): Log time field from the attachment record - `createTime` (string, required): Create time field from the attachment record - `crc` (number, required): CRC field from the attachment record as a decimal number - `dataOffset` (integer): Offset to the start of the attachment in bytes - `size` (integer, required): Size of the attachment in bytes - `fingerprint` (string, required): 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](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). --- ### GET /recording-attachments/{id}/download **Summary**: 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. **Required capabilities**: recordings.list **Path parameters**: - `id` (string, required): ID of the attachment to download **Responses**: - `302`: Found **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) bytes = client.download_attachment(id='att_0dHT6ZvqJhfwOcml') ``` --- ## Recordings A recording is a resource representing the content of an MCAP file or ROS bag managed by Data Platform. ### GET /recordings **Summary**: List recordings **Required capabilities**: recordings.list **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, empty string for those without any - `deviceName` (string): Filter response to recordings for the device with this name - `topic` (string): Filter response to recordings containing the topic - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete"): Filter response to recordings with this import status - `projectId` (string): Filter recordings by project - `sessionId` (string): Filter response to recordings in the session with this ID, or empty string for recordings with no associated session - `sessionKey` (string): Filter response to recordings in the session with this key (sessions group recordings from a specific device) - `metadataQuery` (string): 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. - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results - `sortBy` (string, one of: "deviceName" | "device.name" | "createdAt" | "start" | "end" | "duration" | "path" | "importedAt"): Sort returned recordings by a field in the response type. Specifying `duration` sorts by the duration between the recording `start` and `end` fields. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field **Responses**: - `200`: Success - Type: array of object (Recording), with fields: - `id` (string, required): ID of the recording - `projectId` (string, required): The project ID that the recording belongs to - `path` (string, required): The filepath of the recording as it was originally provided to Foxglove. For recordings originated at the edge, this is the full path of the recording file in the edge controller store. For recordings uploaded directly to Foxglove, this is the `filename` query arg provided to `/data/upload`. - `location` (object (RecordingObjectLocation)): The object-store location of a recording. Present only when the recording is indexed in a customer-managed bucket. Omitted for query-optimized sites, where the original object is not retained, and for recordings that have not yet been imported. - `size` (number (bigint), required): The size of the recording file, in bytes - `createdAt` (string (date-time), required): Timestamp when the recording file was added to Foxglove. - `importedAt` (string (date-time)): Timestamp when the recording was imported to a primary site. - `start` (string (date), required): The log time of the first message in the recording. - `end` (string (date), required): The log time of the last message in the recording. - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete", required): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. - `site` (object (PrimarySiteSummary)): The primary site for this recording. - `edgeSite` (object (EdgeSiteSummary)): The edge site for this recording. - `device` (object (DeviceSummary)): ID and name of a device. - `key` (string): The unique, user-specified key assigned to a recording in MCAP metadata or during the upload process. This can be used to identify the recording, in addition to its `id`. - `metadata` (array of object (RecordingMetadata)): The metadata records of the original MCAP file content - `sessionId` (string): The ID of the session this recording belongs to. **Example** (Python): ```python from foxglove.client import Client token = "" client = Client(token=token) client.get_recordings() ``` --- ### GET /recordings/{keyOrId} **Summary**: Get a recording Get details on a specific recording. **Required capabilities**: recordings.list **Path parameters**: - `keyOrId` (string, required): Recording Key or ID **Responses**: - `200`: A Recording - `id` (string, required): ID of the recording - `projectId` (string, required): The project ID that the recording belongs to - `path` (string, required): The filepath of the recording as it was originally provided to Foxglove. For recordings originated at the edge, this is the full path of the recording file in the edge controller store. For recordings uploaded directly to Foxglove, this is the `filename` query arg provided to `/data/upload`. - `location` (object (RecordingObjectLocation)): The object-store location of a recording. Present only when the recording is indexed in a customer-managed bucket. Omitted for query-optimized sites, where the original object is not retained, and for recordings that have not yet been imported. - `size` (number (bigint), required): The size of the recording file, in bytes - `createdAt` (string (date-time), required): Timestamp when the recording file was added to Foxglove. - `importedAt` (string (date-time)): Timestamp when the recording was imported to a primary site. - `start` (string (date), required): The log time of the first message in the recording. - `end` (string (date), required): The log time of the last message in the recording. - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete", required): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. - `site` (object (PrimarySiteSummary)): The primary site for this recording. - `edgeSite` (object (EdgeSiteSummary)): The edge site for this recording. - `device` (object (DeviceSummary)): ID and name of a device. - `key` (string): The unique, user-specified key assigned to a recording in MCAP metadata or during the upload process. This can be used to identify the recording, in addition to its `id`. - `metadata` (array of object (RecordingMetadata)): The metadata records of the original MCAP file content - `sessionId` (string): The ID of the session this recording belongs to. --- ### DELETE /recordings/{keyOrId} **Summary**: Delete a recording 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. **Required capabilities**: recordings.delete **Path parameters**: - `keyOrId` (string, required): Recording Key or ID **Responses**: - `200`: The deleted recording ID - `recordingId` (string, required): The recording ID - `400`: The recording has no imported data to delete. --- ### POST /recordings/{keyOrId}/import **Summary**: 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. **Required capabilities**: data.upload **Path parameters**: - `keyOrId` (string, required): Recording ID **Responses**: - `200`: Success - `id` (string): Recording ID - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete"): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. --- ### GET /data/pending-imports **Summary**: List pending imports List the pending imports. These are in-progress import jobs for newly uploaded recordings. **Required capabilities**: data.imports.pending.list **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 - `siteBackfillJobId` (string): Filter to pending imports enqueued by this site backfill job (`sbj_…`). - `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 - `projectId` (string): Filter pending imports by project - `sortBy` (string, one of: "createdAt" | "deviceId" | "deviceName" | "device.name" | "device.id" | "error" | "importId" | "requestId" | "updatedAt"): Sort by a single field of the import type - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: Success - Type: array of object (PendingImport), with fields: - `createdAt` (string (date-time), required): 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` (string, required): Filename of the import - `importId` (string): ID of import; undefined until status is "complete" - `orgId` (string, required): ID of org to which the import belongs - `pipelineStage` (string, required): stage in the import pipeline the import currently occupies - `requestId` (string, required): ID of the import request - `projectId` (string): ID of the project to which the import belongs - `siteId` (string, required): ID of Primary Site where import will be stored - `status` (string, one of: "received" | "processing" | "ready for indexing" | "error" | "complete"): Status of initiated import - `updatedAt` (string (date-time), required): When the pending import was last updated - `quarantinedAt` (string (date-time)): When the pending import was quarantined --- ### GET /data/import-errors **Summary**: List import errors List import errors. These are failed pending imports that have encountered errors during processing. **Required capabilities**: data.imports.pending.list **Query parameters**: - `deviceName` (string): Name of device associated with the import error - `filenameMatches` (string): Pattern to match against filename - `error` (string): A string to filter based on error messages - `siteBackfillJobId` (string): Filter to import errors offloaded from pending imports enqueued by this site backfill job (`sbj_…`). - `projectId` (string): Filter import errors by project - `sortBy` (string, one of: "createdAt" | "deviceName" | "error" | "requestId" | "updatedAt"): Sort by a single field - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: Success - Type: array of object (PendingImport), with fields: - `createdAt` (string (date-time), required): 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` (string, required): Filename of the import - `importId` (string): ID of import; undefined until status is "complete" - `orgId` (string, required): ID of org to which the import belongs - `pipelineStage` (string, required): stage in the import pipeline the import currently occupies - `requestId` (string, required): ID of the import request - `projectId` (string): ID of the project to which the import belongs - `siteId` (string, required): ID of Primary Site where import will be stored - `status` (string, one of: "received" | "processing" | "ready for indexing" | "error" | "complete"): Status of initiated import - `updatedAt` (string (date-time), required): When the pending import was last updated - `quarantinedAt` (string (date-time)): When the pending import was quarantined --- ### POST /data/upload **Summary**: Upload a recording Use this endpoint to upload data to your `foxglove-hosted` site. The upload is a two-request process. 1. Make a request to this upload endpoint to create an upload `link`. 2. 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](https://docs.foxglove.dev/docs/data/primary-sites/manage-data) for uploading data. #### Size considerations While we support processing very large files, we generally recommend avoiding large (50GB+) files to reduce the chance of upload failures or processing issues. If you have tooling that generates very large files, consider splitting them up into smaller chunks. **Required capabilities**: data.upload **Request body** (JSON): - `deviceId` (string): Foxglove ID of the associated device - `deviceName` (string): Unique name of the associated device. If no device exists with this name, the device will be created. A name that does not match an existing device must satisfy the same rules as `POST /devices`: at most 100 characters, containing only letters, numbers, underscores, periods, and hyphens. - `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` (string, required): Name of the file that will be uploaded - `key` (string): A unique key to identify the recording - `projectId` (string): The project ID that the recording belongs to. Required for multi-project orgs if an existing device is not provided - `sessionId` (string): ID of an existing session to associate the upload with. - `sessionKey` (string): Key of a session to associate the upload with. If no session exists with this key, a new session will be created using the provided device. **Responses**: - `200`: Upload details - `link` (string, required): A signed upload URL. Upload your data to this URL using a PUT request. - `requestId` (string, required) **Example** (Python): ```python from foxglove.client import Client from pathlib import Path token = "" client = Client(token=token) with Path("my_mcap_data.mcap").open("rb") as byte_stream: client.upload_data( device_id=device_id, filename="my_mcap_data.mcap", data=byte_stream, callback=lambda size, progress: print(size, progress), project_id="", ) ``` --- ## Sessions 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. ### GET /sessions **Summary**: List sessions 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). **Required capabilities**: sessions.list **Query parameters**: - `projectId` (string): Filter sessions by project - `deviceId` (string): Filter sessions by device ID - `deviceName` (string): Filter sessions by device name - `keyMatches` (string): Partial match on session key (case-insensitive) - `start` (string (date-time)): Start of an inclusive time range - `end` (string (date-time)): End of an inclusive time range - `sortBy` (string, one of: "id" | "createdAt" | "updatedAt"): Field to sort items by ("id", "createdAt", "updatedAt") - `query` (string): Space-separated query string for session custom properties. Each custom property key must be valid. See above for syntax and examples. - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: List of recording sessions - Type: array of object (RecordingSessionListItem), with fields: - `id` (string, required): ID of the recording session - `projectId` (string, required): The project ID that the session belongs to - `device` (object (DeviceSummary), required): ID and name of a device. - `key` (string): A user-supplied identifier, unique within the project. - `createdAt` (string (date-time), required): Timestamp when the session was created. - `updatedAt` (string (date-time), required): Timestamp when the session was last updated. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this session. - `recordings` (array of object, required): Recordings associated with this session. - `recordingCount` (number, required): Number of recordings associated with this session. - `recordingStart` (string (date-time)): Earliest log time among visible recordings associated with this session. - `recordingEnd` (string (date-time)): Latest log time among visible recordings associated with this session. --- ### POST /sessions **Summary**: Create a session 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. If the request includes a `projectId`, it must match the device's project; otherwise the API returns 400. **Required capabilities**: sessions.create **Request body** (JSON): - `deviceId` (string): The ID of the device to associate with the session. If omitted, inferred from `recordingIds`. - `key` (string): A user-supplied identifier, unique within the project. - `recordingIds` (array of string): IDs of recordings to associate with the new session. All recordings must belong to the same device and project. - `properties` (object (CustomPropertyValues)): 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. **Responses**: - `200`: The newly created session - `id` (string, required): ID of the recording session - `projectId` (string, required): The project ID that the session belongs to - `device` (object (DeviceSummary), required): ID and name of a device. - `key` (string): A user-supplied identifier, unique within the project. - `createdAt` (string (date-time), required): Timestamp when the session was created. - `updatedAt` (string (date-time), required): Timestamp when the session was last updated. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this session. - `recordings` (array of object, required): Recordings associated with this session. --- ### GET /sessions/{keyOrId} **Summary**: Get a session Get details on a specific session. **Required capabilities**: sessions.list **Path parameters**: - `keyOrId` (string, required): Recording Session Key or ID **Query parameters**: - `projectId` (string): Filter sessions by project. Required for multi-project orgs. **Responses**: - `200`: Success - `id` (string, required): ID of the recording session - `projectId` (string, required): The project ID that the session belongs to - `device` (object (DeviceSummary), required): ID and name of a device. - `key` (string): A user-supplied identifier, unique within the project. - `createdAt` (string (date-time), required): Timestamp when the session was created. - `updatedAt` (string (date-time), required): Timestamp when the session was last updated. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this session. - `recordings` (array of object, required): Recordings associated with this session. --- ### PATCH /sessions/{keyOrId} **Summary**: Update a session Update a session's key, custom properties, or associated recordings. All recordings must belong to the same device and project. Session keys must be unique within the project. **Required capabilities**: sessions.update **Path parameters**: - `keyOrId` (string, required): Recording Session Key or ID **Query parameters**: - `projectId` (string): Filter sessions by project. Required for multi-project orgs. **Request body** (JSON): - `key` (string, nullable): A user-supplied identifier, unique within the project. Pass `null` to clear an existing key. - `addRecordingIds` (array of string): Recording display IDs to add to the session. - `removeRecordingIds` (array of string): Recording display IDs to remove from the session. - `properties` (object): A key-value map from session custom property keys to their values. Omitted keys are unchanged. Set a value to `null` to remove it. **Responses**: - `200`: Updated session - `id` (string, required): ID of the recording session - `projectId` (string, required): The project ID that the session belongs to - `device` (object (DeviceSummary), required): ID and name of a device. - `key` (string): A user-supplied identifier, unique within the project. - `createdAt` (string (date-time), required): Timestamp when the session was created. - `updatedAt` (string (date-time), required): Timestamp when the session was last updated. - `properties` (object (CustomPropertyValues)): A key-value map of the custom properties associated with this session. - `recordings` (array of object, required): Recordings associated with this session. --- ### DELETE /sessions/{keyOrId} **Summary**: Delete a session Soft-delete a recording session and unlink all recordings from it. Does not delete recording data. **Required capabilities**: sessions.delete **Path parameters**: - `keyOrId` (string, required): Recording Session Key or ID **Query parameters**: - `projectId` (string): Filter sessions by project. Required for multi-project orgs. **Responses**: - `200`: Success - `id` (string, required): The ID of the deleted session --- ## Site Tokens Site tokens are credentials a [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises) or [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites) use to communicate with the Foxglove API. ### GET /site-tokens **Summary**: List site tokens **Required capabilities**: siteTokens.list **Query parameters**: - `siteId` (string): Filter by site ID **Responses**: - `200`: List of site tokens - Type: array of object (SiteToken), with fields: - `id` (string, required): ID of the site token - `createdAt` (string (date-time), required): Timestamp of the site token's creation - `siteId` (string, required): ID of the associated Primary or Edge Site --- ### POST /site-tokens **Summary**: Create a site token **Required capabilities**: siteTokens.create **Request body** (JSON): - `siteId` (string, required): Site associated with the newly created token **Responses**: - `200`: A new site token - `id` (string, required): ID of the site token - `createdAt` (string (date-time), required): Timestamp of the site token's creation - `siteId` (string, required): ID of the associated Primary or Edge Site - `token` (string): Generated token. This is only available on creation. --- ### DELETE /site-tokens/{id} **Summary**: Delete a site token **Required capabilities**: siteTokens.delete **Path parameters**: - `id` (string, required): Site token ID **Responses**: - `200`: success - `success` (boolean, value: true, required) --- ## Site Inbox Notification Tokens Site inbox notification tokens are credentials used to authenticate bucket notifications for a [Primary Site](https://docs.foxglove.dev/docs/data/primary-sites) (self-managed or BYOS) to the Foxglove API. ### GET /site-inbox-notification-tokens **Summary**: List inbox notification tokens **Required capabilities**: siteInboxNotificationTokens.list **Query parameters**: - `siteId` (string): Restrict responses to site with this ID **Responses**: - `200`: List of inbox notification tokens - Type: array of object (InboxNotificationToken), with fields: - `id` (string, required) - `orgId` (string, required) - `createdAt` (string (date-time), required): Timestamp of the inbox notification token's creation - `siteId` (string, required): ID of the associated Primary Site --- ### POST /site-inbox-notification-tokens **Summary**: Create a site inbox notification token Create a token that authenticates bucket notifications for a Primary Site in your org (self-managed or BYOS). See the [Primary Site Installation](https://docs.foxglove.dev/docs/data/primary-sites/installation#bucket-push-notifications) documentation for more details. **Required capabilities**: siteInboxNotificationTokens.create **Request body** (JSON): - `siteId` (string, required): Site associated with the newly created token **Responses**: - `200`: The newly created inbox notification token - `id` (string, required) - `orgId` (string, required) - `createdAt` (string (date-time), required): Timestamp of the inbox notification token's creation - `siteId` (string, required): ID of the associated Primary Site - `token` (string): Generated token. This is only available on creation. --- ### DELETE /site-inbox-notification-tokens/{id} **Summary**: Delete an inbox notification token **Required capabilities**: siteInboxNotificationTokens.delete **Path parameters**: - `id` (string, required): Inbox notification token ID **Responses**: - `200`: ID of the deleted token - `id` (string, required): ID of the deleted inbox notification token --- ## Sites A site is a logical grouping of storage and compute for storing Recording data. ### GET /sites **Summary**: List sites Retrieve a list of sites. **Required capabilities**: sites.list **Responses**: - `200`: List of sites - Type: array of object (Site), with fields: - `id` (string, required): Unique identifier for this site - `name` (string, required): Name for this site - `type` (string, one of: "foxglove-hosted" | "self-hosted" | "edge" | "byob", required): The type of the site. - `foxglove-hosted`: A [Foxglove-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud). - `self-hosted`: A [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). - `edge`: An [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites). - `byob`: A [Bring Your Own Storage Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud-bring-your-own-storage). - `url` (string): The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites). - `retainRecordingsSeconds` (number): An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites) --- ### POST /sites **Summary**: Create a Site Create a new site. **Required capabilities**: sites.create **Request body** (JSON): - `name` (string, required): A name for this site - `type` (string, one of: "self-hosted" | "edge", required): The type of site to create. - `retainRecordingsSeconds` (number): 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**: - `200`: The new site - `id` (string, required): Unique identifier for this site - `name` (string, required): Name for this site - `type` (string, one of: "foxglove-hosted" | "self-hosted" | "edge" | "byob", required): The type of the site. - `foxglove-hosted`: A [Foxglove-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud). - `self-hosted`: A [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). - `edge`: An [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites). - `byob`: A [Bring Your Own Storage Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud-bring-your-own-storage). - `url` (string): The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites). - `retainRecordingsSeconds` (number): An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites) --- ### GET /sites/{id} **Summary**: Get site details Get details for a specific site. **Required capabilities**: sites.list **Path parameters**: - `id` (string, required): Site ID **Responses**: - `200`: Site - `id` (string, required): Unique identifier for this site - `name` (string, required): Name for this site - `type` (string, one of: "foxglove-hosted" | "self-hosted" | "edge" | "byob", required): The type of the site. - `foxglove-hosted`: A [Foxglove-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud). - `self-hosted`: A [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). - `edge`: An [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites). - `byob`: A [Bring Your Own Storage Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud-bring-your-own-storage). - `url` (string): The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites). - `retainRecordingsSeconds` (number): An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites) --- ### PATCH /sites/{id} **Summary**: Update site details Update the name or retention period for a Site. **Required capabilities**: sites.update **Path parameters**: - `id` (string, required): Site ID **Request body** (JSON): - `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](https://docs.foxglove.dev/docs/data/primary-sites/installation#configure-site-url) for details. **Responses**: - `200`: Updated site - `id` (string, required): Unique identifier for this site - `name` (string, required): Name for this site - `type` (string, one of: "foxglove-hosted" | "self-hosted" | "edge" | "byob", required): The type of the site. - `foxglove-hosted`: A [Foxglove-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud). - `self-hosted`: A [self-hosted Primary Site](https://docs.foxglove.dev/docs/data/primary-sites#on-premises). - `edge`: An [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites). - `byob`: A [Bring Your Own Storage Site](https://docs.foxglove.dev/docs/data/primary-sites#foxglove-cloud-bring-your-own-storage). - `url` (string): The REST API endpoint your site deployment exposes (only available for self-hosted Primary Sites). - `retainRecordingsSeconds` (number): An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites) --- ### DELETE /sites/{id} **Summary**: 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. **Required capabilities**: sites.delete **Path parameters**: - `id` (string, required): Site ID **Responses**: - `200`: Success - `id` (string, required): ID of the deleted site --- ### GET /sites/{id}/ingest-path-policy **Summary**: Get the latest site ingest path policy Return the latest ingest path policy for a site. An empty `rules` list is a saved default-ignore policy for every path; it is distinct from an unconfigured policy. **Required capabilities**: sites.list **Path parameters**: - `id` (string, required): Site ID **Responses**: - `200`: Latest ingest path policy revision - `revision` (integer, required): Monotonic per-site revision. The highest value is current. - `createdAt` (string (date-time), required) - `policy` (object (IngestPathPolicy), required): Authored ingest path-policy document. First matching rule wins. An empty `rules` list ignores every path (v1 default-ignore). Constant `nameTemplate` rules stay stored as authored templates. - `204`: No policy revision has been saved - `404`: Site not found --- ### POST /sites/{id}/ingest-path-policy **Summary**: Save a site ingest path policy Save an ingest path policy for a site. If the resolved policy differs from the current policy, append a revision. If it matches, return the current revision without appending. Allowed only on BYOS sites. Stores the authored rules without rewriting constant `nameTemplate` rules to device IDs and without creating devices. An empty `rules` list is legal and ignores every path. **Required capabilities**: sites.update **Path parameters**: - `id` (string, required): Site ID **Request body** (JSON): - `schemaVersion` (integer, value: 1, required): Policy document version. Must be 1. - `rules` (array of object (IngestPathRule), required) - `pattern` (string, required): RE2 regular expression matched against the object key (substring search). - `action` (one of: object with type = "ignore" | object with type = "import", device: object (IngestPathDeviceNameTemplateRef), projectId: string | object with type = "import", device: object (IngestPathDeviceIdRef), projectId: string, required): Path-policy action. `ignore` claims the path without importing it, so no later rule is consulted; placed ahead of a broad rule, it carves a subtree out of that rule's reach. `import` admits the path and may assert device and/or project. Device and project assignments override object metadata and MCAP metadata; metadata supplies omitted values. Explicit device and project values in a `/site-bucket-notifications` request take precedence over rule assignments. `projectId` is required when `device.type` is `nameTemplate`. - `previousRevision` (integer): Optional revision that was current when the policy was edited. The request returns 409 if it does not match the current revision and the submitted policy differs from the current policy. Use 0 when the site has no saved policy. **Responses**: - `200`: The saved ingest path policy revision - `revision` (integer, required): Monotonic per-site revision. The highest value is current. - `createdAt` (string (date-time), required) - `policy` (object (IngestPathPolicy), required): Authored ingest path-policy document. First matching rule wins. An empty `rules` list ignores every path (v1 default-ignore). Constant `nameTemplate` rules stay stored as authored templates. - `400`: Invalid policy document, unknown project or device, device/project mismatch, or the site is not a BYOS site - `404`: Site not found - `409`: Conflict reasons: - `StalePolicyRevision`: the submitted previous revision is no longer current and the submitted policy differs from the current policy - `SiteBackfillActive`: a site backfill is active - `503`: Workflow processing is unavailable --- ### POST /site-bucket-notifications **Summary**: Notify object created or removed Notify your primary site that an object in its bucket was created or removed. Most users should set up [bucket notifications](https://docs.foxglove.dev/docs/data/primary-sites/installation#bucket-push-notifications) instead. When `storageProvider` is `azure` for a bring-your-own-storage site, `azureStorageAccountName` is required. For bring-your-own-storage sites, the site's ingest path policy still determines whether an object is indexed. Explicit device and project values in this request override assignments from the policy; omitted values fall back to the matched rule. This endpoint requires a Site Bucket Notification Token as bearer token in the Authorization header: ``` Authorization: Bearer fox_snt_1234... ``` **Request body** (JSON): - `messageId` (string, required): Unique message identifier. Ingest notifications are deduplicated on this value. `object_removed` does not use it for deduplication. A repeated removal for the same bucket and object path is idempotent. - `fileName` (string, required): The name of the recording file in the bucket. - `bucketName` (string, required): Bucket name - `storageProvider` (string, one of: "google_cloud" | "aws" | "azure" | "s3_compatible", required): Storage provider used for the bucket. This must match the storage provider configured for your primary site's inbox bucket or indexed bucket. - `azureStorageAccountName` (string): Azure storage account that contains the container. Required when `storageProvider` is `azure` for a bring-your-own-storage site. Omit this field for other storage providers and for other site types. - `notificationType` (string, one of: "object_created" | "object_removed"): Kind of object event this notification reports. If not provided, defaults to `object_created`. `deviceId`, `deviceName`, `projectId`, `sessionId`, and `sessionKey` apply only to `object_created`. Sending any of them with `object_removed` returns 400. `object_removed` on a query-optimized site also returns 400. - `deviceId` (string): Device to associate with the recording. This takes precedence over assignments from the site's ingest path policy and values provided in [object metadata or MCAP metadata](https://docs.foxglove.dev/docs/data/primary-sites/manage-data#adding-metadata-to-imports). - `deviceName` (string): Name of the device to associate with the recording. The device is looked up by name and created if it does not already exist. `deviceId` takes precedence over `deviceName` when both are provided. An existing device with a unique name resolves without a `projectId`. Provide `projectId` to disambiguate when the name matches devices in multiple projects, or to choose which project a new device is created in when your organization has multiple projects. This takes precedence over assignments from the site's ingest path policy and values provided in [object metadata or MCAP metadata](https://docs.foxglove.dev/docs/data/primary-sites/manage-data#adding-metadata-to-imports). A name that does not match an existing device must satisfy the same rules as `POST /devices`: at most 100 characters, containing only letters, numbers, underscores, periods, and hyphens. - `projectId` (string): Project to associate with the recording. This takes precedence over assignments from the site's ingest path policy and values provided in [object metadata or MCAP metadata](https://docs.foxglove.dev/docs/data/primary-sites/manage-data#adding-metadata-to-imports). - `sessionId` (string): ID of an existing session to associate with the recording. Takes precedence over sessionKey and session values in object metadata or MCAP metadata. The session supplies omitted project and device IDs. Project and device values supplied in the request must match the session's associations. Omit deviceId and deviceName when the session has no device. Self-hosted Primary Sites must have reported a valid version of 0.0.108 or later to use this field. - `sessionKey` (string): Key of a session to associate with the recording. Keys are unique within a project. During ingestion, Foxglove looks up the session or creates it if enough project and device context is available. Ignored when sessionId is provided. This takes precedence over session values in object metadata or MCAP metadata. Self-hosted Primary Sites must have reported a valid version of 0.0.108 or later to use this field. **Responses**: - `200`: success - `success` (boolean, value: true, required) - `400`: Invalid notification parameters or an unsupported Primary Site version. For example, the bucket does not belong to the site, the Azure storage account is missing for a BYOS site, `azureStorageAccountName` is not valid for the storage provider, `object_removed` was sent for a query-optimized site, or `deviceId`, `deviceName`, `projectId`, `sessionId`, or `sessionKey` was sent with `object_removed`. - `404`: Session not found. - `409`: The session key already exists with a different device association. --- ## Stream data ### POST /data/stream **Summary**: Download data This endpoint returns a `link` URL where you can download your data as an `.mcap` or `.bag` file. To download your data: 1. Make a request to this endpoint. 2. Make a `GET` request to the `link` URL. One of `recordingId`, `key`, `importId` (deprecated) or all three of `deviceId`/`deviceName`, `start`, and `end` must be specified. _Note: You can only export a `.bag` file if you originally uploaded a `.bag` file._ **Required capabilities**: data.stream **Request body** (JSON): - `topics` (array of string): List of topics to include in the exported file (defaults to all topics) - `outputFormat` (string, one of: "bag1" | "mcap" | "mcap0"): Output file format. * `bag1` - output a .bag file * `mcap` - output a .mcap file * `mcap0` - Deprecated. Use `mcap`. - `compressionFormat` (string, one of: "" | "zstd" | "lz4"): Output compression format for chunks. Only valid if `outputFormat` is `mcap`. * `""` - no compression * `zstd` - zstd compression * `lz4` - LZ4 compression (default) - `includeAttachments` (boolean): Include attachments in streamed data. One of `recordingId` or `importId` (deprecated) must also be set. Only valid for mcap outputFormat. - `isHosted` (boolean): true if the import is hosted - `replayPolicy` (string, one of: "lastPerChannel" | ""): If set to "lastPerChannel", then the stream will include the most recent message on each channel, even if it comes before the requested `start`, as long as it is within the window of `replayLookbackSeconds` seconds before `start`. The default, `""` (no policy), means no messages before `start` are included. - `replayLookbackSeconds` (integer): Maximum lookback before `start`, in whole seconds. Used only when `replayPolicy` is `lastPerChannel`. - `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 - `sessionId` (string): ID of a session to stream - `sessionKey` (string): Key of a session to stream. Ensure projectId is provided if streaming by sessionKey. - `episodeVersion` (integer): Episode version to stream. Requires `episodeId`. If omitted, the latest version is selected when the stream link is signed. The signed link continues to use that version. - `episodeId` (string): ID of an episode to stream. `start` and `end` default to the episode's time window when omitted and may each be overridden independently. - `projectId` (string): ID of a project to scope the streaming to. Recommended when streaming by deviceName. Required if the device name exists in multiple projects. Required when streaming by sessionKey. **Responses**: - `200`: Success - `link` (string, required): A signed url to access the data. This link expires after 15 seconds. - `404`: The requested data was not found. A `code` of `NoStreamableRecordings` means the session or episode exists, but no Primary Site holds data for any of its recordings. **Example** (Python): ```python from foxglove.client import Client, CompressionFormat, OutputFormat from datetime import datetime, timedelta token = "" client = Client(token=token) bytes = client.download_data( device_id=device_id, start=datetime.now() - timedelta(hours=3), end=datetime.now() - timedelta(hours=1), topics=["/clock", "/tracked_objects"], output_format=OutputFormat.mcap, compression_format=CompressionFormat.lz4, callback=lambda progress: print(".", end=""), ) # Or, to download using a recording ID: bytes = client.download_recording_data(id="rec_0dHT6g6cOfff9m5U") ``` --- ## Topics Topics provide schema information for messages in the data source. ### GET /data/topics **Summary**: 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. Topics for not-imported recordings are only returned if no parameter is provided besides recordingId or recordingKey. This is because most parameters need the imported files to filter, and can only return an empty list if imports are unavailable. **Required capabilities**: data.topics.list **Query parameters**: - `start` (string (date-time)): Return all topics appearing in recordings ending on or after `start` - `end` (string (date-time)): Return topics from recordings that start on or before `end`. - `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 - `deviceName` (string): Name of device being queried - `sessionId` (string): ID of a recording session to list topics from - `sessionKey` (string): Key of a recording session to list topics from - `episodeVersion` (integer): Episode version to list topics from. Requires `episodeId`. If omitted, uses the latest episode version. - `episodeId` (string): ID of an episode to list topics from - `includeSchemas` (boolean, default: false): Whether full schemas should be included in the response - `sortBy` (string, one of: "topic" | "version"): Sort by a single field of the topic type ("topic" or "version") - `projectId` (string): Filter topics matching project ID - `sortOrder` (string, one of: "asc" | "desc"): Sort order for the `sortBy` field - `limit` (number, default: 2000): Maximum number of items to return - `offset` (integer, default: 0): Number of items to skip before returning the results **Responses**: - `200`: List of topics - Type: array of object (Topic), with fields: - `encoding` (string, required): Encoding of the topic - `schema` (string): Full schema, base-64 encoded; included only if the request's includeSchemas is true - `schemaEncoding` (string, required): Encoding of the topic schema - `schemaName` (string, required): Name of the topic schema - `topic` (string, required): Topic name - `version` (string, required): Topic version **Example** (Python): ```python from foxglove.client import Client from datetime import datetime, timedelta token = "" client = Client(token=token) client.get_topics( device_id=device_id, start=datetime.now() - timedelta(hours=3), end=datetime.now() - timedelta(hours=1), ) ``` --- # Webhooks ## Webhook Payloads [Webhooks](https://docs.foxglove.dev/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. ### WEBHOOK recording.created **Summary**: recording.created `recording.created` events occur when a recording is created. Recordings are created when a file is [uploaded](https://docs.foxglove.dev/api/recordings/upload-a-recording), added to [Edge Site](https://docs.foxglove.dev/docs/data/edge-sites) storage, or created on a device that runs [Foxlet](https://docs.foxglove.dev/docs/fleet/foxlet). **Request body** (JSON): - `type` (string, value: "recording.created", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `recording` (object, required) - `id` (string, required): Recording ID - `key` (string): User-assigned key (if specified during recording upload) - `sessionId` (string): ID of the session associated with this recording - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete", required): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. - `path` (string, required): The filepath the recording was created with - `location` (object (RecordingObjectLocation)): The object-store location of a recording. Present only when the recording is indexed in a customer-managed bucket. Omitted for query-optimized sites, where the original object is not retained, and for recordings that have not yet been imported. - `scheme` (string, one of: "gs" | "s3" | "https" | "file" | "az", required): The storage scheme for this object: `gs` for Google Cloud Storage, `s3` for Amazon S3, `az` for Azure Blob Storage, `https` for S3-compatible storage, or `file` for local file storage. - `path` (string, required): The full object key of the recording in the indexed bucket. For recordings that originate on a device this may include a `recordingId=/` prefix that is not present in the recording's `path` field. - `bucket` (string, required): The name of the bucket that stores the recording. For Azure-backed sites this is the container name. - `azureStorageAccountName` (string): The Azure storage account that contains the bucket, for Azure-backed sites. - `device` (object (DeviceSummary)): ID and name of a device. - `id` (string, required) - `name` (string, required) - `edgeSite` (object (EdgeSiteSummary)): ID and name of an edge site. - `id` (string, required) - `name` (string, required) - `site` (object (PrimarySiteSummary)): ID and name of a primary site. - `id` (string, required) - `name` (string, required) - `indexingStrategy` (string, one of: "split-files" | "index-in-place", required) - `projectId` (string, required): The ID of the project this recording belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK recording.imported **Summary**: recording.imported `recording.imported` events occur when a recording is [imported](https://docs.foxglove.dev/docs/data/importing-data) and is ready for streaming. **Request body** (JSON): - `type` (string, value: "recording.imported", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `recording` (object, required) - `id` (string, required): Recording ID - `key` (string): User-assigned key (if specified during recording upload) - `sessionId` (string): ID of the session associated with this recording - `importStatus` (string, one of: "none" | "pending" | "importing" | "failed" | "complete", required): The import status of recordings. Status will be one of: - `none`: The recording has not yet been imported, and import has not been requested. - `pending`: Foxglove has received a request to import this recording. - `importing`: The recording data is being processed for access via Foxglove. - `failed`: The recording data could not be imported. - `complete`: The contents of the recording are available for access via Foxglove. Note: `none` and `pending` statuses are applicable only to recordings originating from an Edge Site or a device running Foxlet. The set of `importStatus` values may expand in the future. - `path` (string, required): The filepath the recording was created with - `location` (object (RecordingObjectLocation)): The object-store location of a recording. Present only when the recording is indexed in a customer-managed bucket. Omitted for query-optimized sites, where the original object is not retained, and for recordings that have not yet been imported. - `scheme` (string, one of: "gs" | "s3" | "https" | "file" | "az", required): The storage scheme for this object: `gs` for Google Cloud Storage, `s3` for Amazon S3, `az` for Azure Blob Storage, `https` for S3-compatible storage, or `file` for local file storage. - `path` (string, required): The full object key of the recording in the indexed bucket. For recordings that originate on a device this may include a `recordingId=/` prefix that is not present in the recording's `path` field. - `bucket` (string, required): The name of the bucket that stores the recording. For Azure-backed sites this is the container name. - `azureStorageAccountName` (string): The Azure storage account that contains the bucket, for Azure-backed sites. - `device` (object (DeviceSummary)): ID and name of a device. - `id` (string, required) - `name` (string, required) - `edgeSite` (object (EdgeSiteSummary)): ID and name of an edge site. - `id` (string, required) - `name` (string, required) - `site` (object (PrimarySiteSummary)): ID and name of a primary site. - `id` (string, required) - `name` (string, required) - `indexingStrategy` (string, one of: "split-files" | "index-in-place", required) - `projectId` (string, required): The ID of the project this recording belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK session.created **Summary**: session.created `session.created` events occur when a new [Session](https://docs.foxglove.dev/docs/data/sessions) is created. Sessions group related recordings and can be created via the API or when recordings are associated with a session. **Request body** (JSON): - `type` (string, required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `session` (object, required) - `id` (string, required): Session ID - `device` (object (DeviceSummary)): ID and name of a device. - `id` (string, required) - `name` (string, required) - `key` (string): User-assigned key (if specified) - `projectId` (string, required): The ID of the project this session belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK device.created **Summary**: device.created `device.created` events occur when a new [Device](https://docs.foxglove.dev/docs/data/importing-data#optional-add-devices) is created. **Request body** (JSON): - `type` (string, required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `device` (object, required) - `id` (string, required): Device ID - `projectId` (string, required): The ID of the project this device belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK device.updated **Summary**: device.updated `device.updated` events occur when a [Device](https://docs.foxglove.dev/docs/data/importing-data#optional-add-devices) is updated. **Request body** (JSON): - `type` (string, required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `device` (object, required) - `id` (string, required): Device ID - `projectId` (string, required): The ID of the project this device belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK event.created **Summary**: event.created `event.created` events occur when a new [Event](https://docs.foxglove.dev/docs/data/events) is created in Foxglove. **Request body** (JSON): - `type` (string, required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `event` (object, required) - `id` (string, required): Event ID - `projectId` (string, required): The ID of the project this event belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK event.updated **Summary**: event.updated `event.updated` events occur when an [Event](https://docs.foxglove.dev/docs/data/events) is updated. **Request body** (JSON): - `type` (string, required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `event` (object, required) - `id` (string, required): Event ID - `projectId` (string, required): The ID of the project this event belongs to **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK dataset.version.committed **Summary**: dataset.version.committed A dataset draft is committed. Use the dataset ID and version in this payload to read that version’s manifest and its pinned episode versions. **Request body** (JSON): - `type` (string, value: "dataset.version.committed", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `dataset` (object, required) - `id` (string, required) - `name` (string, required) - `version` (integer, required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK dataset.created **Summary**: dataset.created A dataset is created. **Request body** (JSON): - `type` (string, value: "dataset.created", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `dataset` (object, required) - `id` (string, required) - `name` (string, required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK dataset.updated **Summary**: dataset.updated A dataset’s name or description changes. No-op updates do not emit an event. **Request body** (JSON): - `type` (string, value: "dataset.updated", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `dataset` (object, required) - `id` (string, required) - `name` (string, required) - `changedFields` (array of string, one of: "name" | "description", required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK dataset.deleted **Summary**: dataset.deleted A dataset is deleted. The payload retains its ID and name for reconciliation. **Request body** (JSON): - `type` (string, value: "dataset.deleted", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `dataset` (object, required) - `id` (string, required) - `name` (string, required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK episode.created **Summary**: episode.created An episode is created at version 1. **Request body** (JSON): - `type` (string, value: "episode.created", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `episode` (object, required) - `id` (string, required) - `version` (integer, required) - `changedFields` (array of string, one of: "startTime" | "endTime" | "recordings" | "properties", required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK episode.updated **Summary**: episode.updated An effective episode edit creates a subsequent version. Adding an existing episode to a dataset does not emit this event. **Request body** (JSON): - `type` (string, value: "episode.updated", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `episode` (object, required) - `id` (string, required) - `version` (integer, required) - `changedFields` (array of string, one of: "startTime" | "endTime" | "recordings" | "properties", required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK episode.deleted **Summary**: episode.deleted An episode is deleted. The payload retains its ID for reconciliation. **Request body** (JSON): - `type` (string, value: "episode.deleted", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required) - `episode` (object, required) - `id` (string, required) **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK automation_run.finished **Summary**: automation_run.finished `automation_run.finished` events occur when an [automation](https://docs.foxglove.dev/docs/automations) run finishes, whether it succeeded or failed. A run that is deleted before it finishes does not send this event. This event is available to organizations with Automations enabled. **Request body** (JSON): - `type` (string, value: "automation_run.finished", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `projectId` (string, required): The ID of the project the automation belongs to - `automationRun` (object, required) - `id` (string, required): Automation run ID - `automationId` (string, required): The ID of the automation that ran - `status` (string, one of: "succeeded" | "failed", required): The status the run finished with - `errorKind` (string, one of: "rejected" | "stopped" | "error"): Why the run failed. Present only when `status` is `failed`. `rejected` is a run that did not start or could not do its task, `stopped` is a run whose worker stopped before it completed, and `error` is a system failure. **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- ### WEBHOOK ping **Summary**: ping The `ping` event type is used to test webhook connectivity. **Request body** (JSON): - `type` (string, value: "ping", required): The event type - `timestamp` (string (date-time), required): When the webhook event occurred - `attemptedAt` (string (date-time), required): When the delivery was attempted - `webhookEventId` (string, required): ID of the associated webhook event - `webhookId` (string, required): ID of the webhook that notified your endpoint - `webhook` (object, required) - `id` (string, required): Webhook ID **Responses**: - `2XX`: Return a 2XX status to acknowledge the event. --- # Visualization ## Extensions ### POST /extension-upload **Summary**: Publish an extension **Available on Free, Pro, and Enterprise plans** Publish a new [Foxglove extension](https://docs.foxglove.dev/docs/extensions) 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`](https://github.com/foxglove/create-foxglove-extension/) for more information on how to create an extension. Read the [docs](https://docs.foxglove.dev/docs/extensions) for more information on Foxglove extensions. **Required capabilities**: extensions.create **Request body** (`application/octet-stream`) **Responses**: - `200`: Extension ID - `id` (string, required) - `409`: Conflict with package name and version --- ### GET /extensions **Summary**: List extensions Organization admins can share and manage Foxglove extensions. Check out the [docs](https://docs.foxglove.dev/docs/extensions) to learn more. **Required capabilities**: extensions.list **Responses**: - `200`: List of extensions - Type: array of object (Extension), with fields: - `id` (string, required): Assigned by backend - `name` (string, required): Name as it appears in your package.json - `publisher` (string, required): Publisher as it appears in your package.json - `displayName` (string, required): Display name as it appears in your package.json - `description` (string, required, nullable): Description as it appears in the active version's package.json - `activeVersion` (string, required, nullable): Version string as it appears in the active version's package.json - `sha256Sum` (string, required, nullable): SHA-256 sum of the active version contents, encoded as hex --- ### GET /extensions/{id} **Summary**: Get an extension **Required capabilities**: extensions.list **Path parameters**: - `id` (string, required): Extension ID **Responses**: - `200`: Extension details - `id` (string, required): Assigned by backend - `name` (string, required): Name as it appears in your package.json - `publisher` (string, required): Publisher as it appears in your package.json - `displayName` (string, required): Display name as it appears in your package.json - `description` (string, required, nullable): Description as it appears in the active version's package.json - `activeVersion` (string, required, nullable): Version string as it appears in the active version's package.json - `sha256Sum` (string, required, nullable): SHA-256 sum of the active version contents, encoded as hex - `foxe` (string, required): Signed download link for the extension --- ### DELETE /extensions/{id} **Summary**: Delete an extension Once deleted, the extension will no longer be available within your organization. **Required capabilities**: extensions.delete **Path parameters**: - `id` (string, required): Extension ID **Responses**: - `200`: Success - `id` (string, required): The ID of the deleted extension --- ## Layouts ### GET /layouts **Summary**: List layouts List the org layouts. Note: Only layouts shared with the org are returned in the response; no personal layouts are returned. **Required capabilities**: layouts.list **Query parameters**: - `updatedSince` (string (date-time)): Return only layouts updated since this time. - `includeData` (boolean, default: true): When set to false, the `data` field is omitted from the response items. This can be used to limit bandwidth when querying many Layouts. **Responses**: - `200`: List of org layouts - Type: array of object (Layout), with fields: - `id` (string, required): ID of the layout - `name` (string, required): Name of the layout - `createdAt` (string (date-time), required): Timestamp when the layout was created on the server - `updatedAt` (string (date-time), required): 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` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE", required) - `data` (object): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. --- ### POST /layouts **Summary**: Create a layout Creates a layout. API keys can only create shared layouts. **Required capabilities**: layouts.create **Request body** (JSON): - `id` (string) - `name` (string, required) - `savedAt` (string (date-time)) - `folderName` (string): The folder name used to organize layouts in the UI. It cannot contain forward slashes. - `permission` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE", required) - `data` (object, required): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. **Responses**: - `200`: Success - `id` (string, required): ID of the layout - `name` (string, required): Name of the layout - `createdAt` (string (date-time), required): Timestamp when the layout was created on the server - `updatedAt` (string (date-time), required): 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` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE", required) - `data` (object): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. - `400`: Invalid request - `409`: Conflict with ID --- ### GET /layouts/{id} **Summary**: Get a layout **Required capabilities**: layouts.list **Path parameters**: - `id` (string, required): Layout ID **Query parameters**: - `includeData` (boolean, default: false): Include data in response **Responses**: - `200`: Success - `id` (string, required): ID of the layout - `name` (string, required): Name of the layout - `createdAt` (string (date-time), required): Timestamp when the layout was created on the server - `updatedAt` (string (date-time), required): 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` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE", required) - `data` (object): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. - `404`: Not found --- ### DELETE /layouts/{id} **Summary**: Delete a layout Soft-deletes a layout. API keys can only delete shared layouts. **Required capabilities**: layouts.delete **Path parameters**: - `id` (string, required): Layout ID **Responses**: - `200`: Success - `success` (boolean, value: true, required) - `403`: Caller is not permitted to delete this layout. - `404`: Not found --- ### PATCH /layouts/{id} **Summary**: Update a layout Updates an existing layout. API keys can only update shared layouts. **Required capabilities**: layouts.update **Path parameters**: - `id` (string, required): Layout ID **Request body** (JSON): - `name` (string) - `folderName` (string): The folder name used to organize layouts in the UI. It cannot contain forward slashes. "" will unset the folderName. - `permission` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE") - `data` (object): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. **Responses**: - `200`: Success - `id` (string, required): ID of the layout - `name` (string, required): Name of the layout - `createdAt` (string (date-time), required): Timestamp when the layout was created on the server - `updatedAt` (string (date-time), required): 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` (string, one of: "CREATOR_WRITE" | "ORG_READ" | "ORG_WRITE", required) - `data` (object): Layout contents. The format may change. Treat it as opaque and preserve values returned by the API. - `400`: Invalid request - `403`: Caller is not permitted to update this layout. - `404`: Not found - `409`: Conflict --- ### POST /layouts/{id}/restore **Summary**: Restore a layout Restores a soft-deleted layout. API keys can only restore shared layouts. **Required capabilities**: layouts.delete **Path parameters**: - `id` (string, required): Layout ID **Responses**: - `200`: Success - `success` (boolean, value: true, required) - `403`: Caller is not permitted to restore this layout. - `404`: Not found ---