Foxglove Technologies Sites API

openapi: 3.2.0
info:
  title: Foxglove Sites API
  version: v1
  x-logo:
    url: https://foxglove.dev/images/logo-icon-round.png
  description: '# Python client


    Foxglove provides a Python client library (`foxglove-client`) to more easily interact with the Foxglove API.'
servers:
- url: https://api.foxglove.dev/v1
  description: Production
security: []
tags:
- name: Sites
  description: A site is a logical grouping of storage and compute for storing Recording data.
paths:
  /sites:
    get:
      tags:
      - Sites
      summary: List sites
      description: Retrieve a list of sites.
      security:
      - ApiKey:
        - sites.list
      responses:
        '200':
          description: List of sites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Site'
      operationId: getSites
      x-operation-id-source: derived
    post:
      tags:
      - Sites
      summary: Create a Site
      description: Create a new site.
      security:
      - ApiKey:
        - sites.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A name for this site
                type:
                  type: string
                  description: 'The type of site to create.

                    '
                  enum:
                  - self-hosted
                  - edge
                retainRecordingsSeconds:
                  type: number
                  minimum: 0
                  description: 'Optionally set a retention period for recordings created at

                    this site. If set to zero, recordings are retained indefinitely.

                    (only available on Edge Sites)

                    '
              required:
              - name
              - type
      responses:
        '200':
          description: The new site
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
      operationId: postSites
      x-operation-id-source: derived
  /sites/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: Site ID
    get:
      tags:
      - Sites
      summary: Get site details
      security:
      - ApiKey:
        - sites.list
      description: Get details for a specific site.
      responses:
        '200':
          description: Site
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
      operationId: getSitesById
      x-operation-id-source: derived
    patch:
      tags:
      - Sites
      summary: Update site details
      description: Update the name or retention period for a Site.
      security:
      - ApiKey:
        - sites.update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A name for this site
                retainRecordingsSeconds:
                  type: number
                  description: '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:
                  type: string
                  description: 'The URL a self-hosted Primary Site exposes for accessing available data.

                    See [The self-hosting installation guide](https://docs.foxglove.dev/docs/primary-sites/self-hosting/installation#configure-foxglove)

                    for details.

                    '
      responses:
        '200':
          description: Updated site
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
      operationId: patchSitesById
      x-operation-id-source: derived
    delete:
      tags:
      - Sites
      summary: Delete a site
      security:
      - ApiKey:
        - sites.delete
      description: '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.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: ID of the deleted site
                required:
                - id
      operationId: deleteSitesById
      x-operation-id-source: derived
  /site-bucket-notifications:
    post:
      tags:
      - Sites
      summary: Notify new recording
      description: 'Notify your primary site of a new recording to ingest. Most users should set up Bucket

        notifications

        instead.


        This endpoint requires a Site Bucket Notification Token as bearer token in the Authorization header:


        ```

        Authorization: Bearer fox_snt_1234...

        ```'
      security:
      - SiteBucketNotificationBearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messageId:
                  type: string
                  description: Unique message identifier. Notifications will be deduplicated based on this value.
                fileName:
                  type: string
                  description: The name of the recording file in the bucket.
                  minLength: 1
                bucketName:
                  type: string
                  description: Bucket name
                  minLength: 1
                storageProvider:
                  type: string
                  enum:
                  - google_cloud
                  - aws
                  - azure
                  - s3_compatible
                  description: 'Storage provider used for the bucket. This must match the storage provider

                    configured for your primary site''s inbox bucket or indexed bucket.

                    '
                deviceId:
                  type: string
                  description: 'Device to associate with the recording. This takes precedence over values

                    provided in [object metadata or MCAP metadata](/docs/primary-sites/self-hosting/manage-data#adding-metadata-to-imports).

                    '
                  minLength: 1
                deviceName:
                  type: string
                  description: '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 values provided in

                    [object metadata or MCAP metadata](/docs/primary-sites/self-hosting/manage-data#adding-metadata-to-imports).

                    '
                  minLength: 1
                projectId:
                  type: string
                  description: 'Project to associate with the recording. This takes precedence over values

                    provided in [object metadata or MCAP metadata](/docs/primary-sites/self-hosting/manage-data#adding-metadata-to-imports).

                    '
                  minLength: 1
              required:
              - messageId
              - fileName
              - bucketName
              - storageProvider
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
      operationId: postSiteBucketNotifications
      x-operation-id-source: derived
components:
  schemas:
    Site:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this site
        name:
          type: string
          description: Name for this site
        type:
          type: string
          description: 'The type of the site.

            - `foxglove-hosted`: A [Foxglove-hosted Primary Site](https://docs.foxglove.dev/docs/primary-sites#foxglove-hosted).

            - `self-hosted`: A [self-hosted Primary Site](https://docs.foxglove.dev/docs/primary-sites#self-hosted).

            - `edge`: An [Edge Site](https://docs.foxglove.dev/docs/edge-sites).

            - `byob`: A [Bring Your Own Storage Site](https://docs.foxglove.dev/docs/primary-sites#bring-your-own-storage).

            '
          enum:
          - foxglove-hosted
          - self-hosted
          - edge
          - byob
        url:
          type: string
          description: 'The REST API endpoint your site deployment exposes

            (only available for self-hosted Primary Sites).

            '
        retainRecordingsSeconds:
          type: number
          minimum: 0
          description: 'An optional retention period for recordings created at this site. If set to zero, recordings are retained indefinitely. (only available on Edge Sites)

            '
      required:
      - id
      - name
      - type
    GenericSuccess:
      type: object
      properties:
        success:
          type: boolean
          const: true
      required:
      - success
  securitySchemes:
    Session:
      type: apiKey
      in: cookie
      name: fox.session
      description: User permissions when signed into the website
    ApiKey:
      type: http
      scheme: bearer
      description: API key authentication using HTTP Bearer auth
    SiteBucketNotificationBearerToken:
      type: http
      scheme: bearer
      description: Site bucket notification authentication using HTTP Bearer auth
x-tagGroups:
- name: Data Platform
  tags:
  - Coverage
  - Custom Properties
  - Device Tokens
  - Devices
  - Events
  - Event Types
  - Imports
  - Lake files
  - Projects
  - Recording Attachments
  - Recordings
  - Sessions
  - Site Tokens
  - Site Inbox Notification Tokens
  - Sites
  - Stream data
  - Topics
- name: Webhooks
  tags:
  - Webhook Payloads
- name: Visualization
  tags:
  - Extensions
  - Layouts