api

Documentation

Overview

Package api provides a read-only Fleet REST API client. It only performs GET requests and enforces this at the type level -- there are no exported methods that perform writes. This is intentional and permanent.

Index

• type Client
  • func NewClient(baseURL, token string) (*Client, error)
  • func (c *Client) FetchAll(ctx context.Context, fetchGlobal ...bool) (*FleetState, error)
  • func (c *Client) GetConfig(ctx context.Context) (map[string]any, error)
  • func (c *Client) GetFleetMaintainedApps(ctx context.Context) ([]FleetMaintainedApp, error)
  • func (c *Client) GetLabels(ctx context.Context) ([]Label, error)
  • func (c *Client) GetPolicies(ctx context.Context, teamID uint) ([]Policy, error)
  • func (c *Client) GetProfiles(ctx context.Context, teamID uint) ([]Profile, error)
  • func (c *Client) GetQueries(ctx context.Context, teamID uint) ([]Query, error)
  • func (c *Client) GetSoftware(ctx context.Context, teamID uint) ([]SoftwareTitle, error)
  • func (c *Client) GetTeams(ctx context.Context) ([]Team, error)
• type FleetMaintainedApp
• type FleetState
• type HTTPError
  • func (e *HTTPError) Error() string
• type Label
• type Policy
• type Profile
• type Query
• type SoftwareTitle
• type SoftwareTitleAppStore
• type SoftwareTitlePackageMeta
• type Team
• type TeamAppStoreApp
• type TeamFleetApp
• type TeamSoftware
• type TeamSoftwarePackage

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a read-only Fleet REST API client.

func NewClient

func NewClient(baseURL, token string) (*Client, error)

NewClient creates a new read-only Fleet API client. Returns an error if the URL uses plain HTTP (token would be sent in cleartext).

func (*Client) FetchAll

func (c *Client) FetchAll(ctx context.Context, fetchGlobal ...bool) (*FleetState, error)

FetchAll concurrently fetches the complete Fleet state. Uses errgroup for parallel requests. If fetchGlobal is true, also fetches global config, policies, and queries (for default.yml diffing).

func (*Client) GetConfig

func (c *Client) GetConfig(ctx context.Context) (map[string]any, error)

GetConfig fetches the Fleet server configuration (org_settings, agent_options, etc.).

func (*Client) GetFleetMaintainedApps

func (c *Client) GetFleetMaintainedApps(ctx context.Context) ([]FleetMaintainedApp, error)

GetFleetMaintainedApps fetches Fleet's maintained-app catalog.

func (*Client) GetLabels

func (c *Client) GetLabels(ctx context.Context) ([]Label, error)

GetLabels fetches all labels with pagination.

func (*Client) GetPolicies

func (c *Client) GetPolicies(ctx context.Context, teamID uint) ([]Policy, error)

GetPolicies fetches policies for a team (0 = global) with pagination.

func (*Client) GetProfiles

func (c *Client) GetProfiles(ctx context.Context, teamID uint) ([]Profile, error)

GetProfiles fetches MDM profiles for a team.

func (*Client) GetQueries

func (c *Client) GetQueries(ctx context.Context, teamID uint) ([]Query, error)

GetQueries fetches queries, optionally filtered by team, with pagination.

func (*Client) GetSoftware

func (c *Client) GetSoftware(ctx context.Context, teamID uint) ([]SoftwareTitle, error)

GetSoftware fetches managed (available_for_install) software titles for a team. Uses available_for_install=true to exclude detected-only titles (OS packages, browser extensions, etc.) and only return software deployed via Fleet/GitOps. Paginates to collect all results.

func (*Client) GetTeams

func (c *Client) GetTeams(ctx context.Context) ([]Team, error)

GetTeams fetches all teams with pagination.

type FleetMaintainedApp

type FleetMaintainedApp struct {
	ID              uint   `json:"id"`
	SoftwareTitleID uint   `json:"software_title_id"`
	Slug            string `json:"slug"`
	Name            string `json:"name"`
	Platform        string `json:"platform"`
}

FleetMaintainedApp is an entry from Fleet's maintained-app catalog.

type FleetState

type FleetState struct {
	Teams                  []Team
	Labels                 []Label
	FleetMaintainedCatalog []FleetMaintainedApp
	Config                 map[string]any // from GET /api/v1/fleet/config
	GlobalPolicies         []Policy       // from GET /api/v1/fleet/policies (teamID=0)
	GlobalQueries          []Query        // from GET /api/v1/fleet/queries (teamID=0)
}

FleetState holds the complete current state fetched from the Fleet API.

type HTTPError

type HTTPError struct {
	StatusCode int
	URL        string
	Body       string
}

HTTPError represents a non-200 HTTP response.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type Label

type Label struct {
	ID        uint   `json:"id"`
	Name      string `json:"name"`
	Query     string `json:"query"`
	Platform  string `json:"platform"`
	HostCount uint   `json:"host_count"`
}

Label represents a Fleet label.

type Policy

type Policy struct {
	ID               uint     `json:"id"`
	Name             string   `json:"name"`
	Query            string   `json:"query"`
	Description      string   `json:"description"`
	Resolution       string   `json:"resolution"`
	Platform         string   `json:"platform"`
	Critical         bool     `json:"critical"`
	PassingHostCount uint     `json:"passing_host_count"`
	FailingHostCount uint     `json:"failing_host_count"`
	LabelsIncludeAny []string `json:"-"` // normalized from API response
	LabelsExcludeAny []string `json:"-"`
}

Policy represents a Fleet policy as returned by the API.

type Profile

type Profile struct {
	ProfileUUID string `json:"profile_uuid"`
	Name        string `json:"name"`
	Platform    string `json:"platform"`
}

Profile represents an MDM configuration profile.

type Query

type Query struct {
	ID       uint   `json:"id"`
	Name     string `json:"name"`
	Query    string `json:"query"`
	Interval uint   `json:"interval"`
	Platform string `json:"platform"`
	Logging  string `json:"logging"`
}

Query represents a Fleet query.

type SoftwareTitle

type SoftwareTitle struct {
	ID              uint                      `json:"id"`
	Name            string                    `json:"name"`
	Source          string                    `json:"source"`
	HostCount       uint                      `json:"hosts_count"`
	AppStoreApp     *SoftwareTitleAppStore    `json:"app_store_app"`
	SoftwarePackage *SoftwareTitlePackageMeta `json:"software_package"`
}

SoftwareTitle represents a software title in Fleet.

type SoftwareTitleAppStore

type SoftwareTitleAppStore struct {
	AppStoreID  string `json:"app_store_id"`
	SelfService bool   `json:"self_service"`
	Platform    string `json:"platform"`
}

SoftwareTitleAppStore contains app-store-specific metadata for a title.

type SoftwareTitlePackageMeta

type SoftwareTitlePackageMeta struct {
	Name        string `json:"name"`
	PackageURL  string `json:"package_url"`
	SelfService bool   `json:"self_service"`
	Platform    string `json:"platform"`
}

SoftwareTitlePackageMeta contains package metadata for a title.

type Team

type Team struct {
	ID             uint         `json:"id"`
	Name           string       `json:"name"`
	Software       TeamSoftware `json:"software"`
	Policies       []Policy
	Queries        []Query
	Profiles       []Profile // populated by GetProfiles
	SoftwareTitles []SoftwareTitle
}

Team represents a Fleet team with its associated resources. Policies/queries/profiles are fetched via separate endpoints. Managed software definitions come directly from /teams[].software.

type TeamAppStoreApp

type TeamAppStoreApp struct {
	AppStoreID  string `json:"app_store_id"`
	SelfService bool   `json:"self_service"`
}

type TeamFleetApp

type TeamFleetApp struct {
	Slug        string `json:"slug"`
	SelfService bool   `json:"self_service"`
}

type TeamSoftware

type TeamSoftware struct {
	Packages        []TeamSoftwarePackage `json:"packages"`
	FleetMaintained []TeamFleetApp        `json:"fleet_maintained_apps"`
	AppStoreApps    []TeamAppStoreApp     `json:"app_store_apps"`
}

TeamSoftware mirrors /api/v1/fleet/teams[].software for managed software definitions configured in Fleet/GitOps.

type TeamSoftwarePackage

type TeamSoftwarePackage struct {
	URL                string `json:"url"`
	HashSHA256         string `json:"hash_sha256"`
	SelfService        bool   `json:"self_service"`
	ReferencedYAMLPath string `json:"referenced_yaml_path"`
}