api

package
v2.0.0-beta.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrPlanGated = errors.New("not available on your organisation's current plan")

ErrPlanGated marks a self-serve plan limit a user lifts by upgrading — seats, a payment problem, or no subscription. The error's own message is the API's specific reason.

View Source 
var ErrQuotaExceeded = errors.New("resource limit reached on your organisation's current plan")

ErrQuotaExceeded marks a resource cap that is raised on request rather than by self-serve upgrade — the feature, segment, and segment-override limits, which enterprise plans can relax. Telling the two apart is by message text only (see classifyLimit); Flagsmith ships no machine-readable error code.

View Source 
var ErrWorkflowGated = fmt.Errorf("this environment uses change-request workflows; direct updates are disabled")

ErrWorkflowGated is returned when update-flag-v2 refuses because the environment has change-request workflows enabled.

Functions

This section is empty.

Types

type APIKey 

type APIKey string

APIKey authenticates with an organisation Master API key.

func (APIKey) Apply 

func (k APIKey) Apply(req *http.Request)

type Auth 

type Auth interface {
	Apply(req *http.Request)
}

Auth applies an Authorization scheme to a request.

type Bearer 

type Bearer string

Bearer authenticates with an OAuth access token.

func (Bearer) Apply 

func (b Bearer) Apply(req *http.Request)

type Client 

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

Client is the Flagsmith Admin API client.

func NewClient 

func NewClient(baseURL string, auth Auth, opts ...Option) *Client

NewClient builds a Client for one instance base URL and auth scheme. The base URL's trailing slash is trimmed so paths join cleanly.

func (*Client) CloneEnvironment 

func (c *Client) CloneEnvironment(ctx context.Context, apiKey string, body map[string]any) (*Environment, error)

CloneEnvironment clones an environment into a new one named by body["name"].

func (*Client) CoreIdentityOverrides 

func (c *Client) CoreIdentityOverrides(ctx context.Context, envKey string, featureID int) ([]IdentityOverrideRow, error)

CoreIdentityOverrides lists every core (Postgres) identity override for a feature, via the environment featurestates list's identity mode.

func (*Client) CreateEnvironment 

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

CreateEnvironment creates an environment from a flat field body (name + project required). The client-side api_key is minted server-side.

func (*Client) CreateEnvironmentAPIKey 

func (c *Client) CreateEnvironmentAPIKey(ctx context.Context, envKey string, body map[string]any) (*EnvironmentAPIKey, error)

CreateEnvironmentAPIKey mints a server-side key; the response includes the full key value (shown once).

func (*Client) CreateFeature 

func (c *Client) CreateFeature(ctx context.Context, projectID int, in FeatureWrite) (*Feature, error)

CreateFeature creates a project feature (project taken from the URL).

func (*Client) CreateIdentity 

func (c *Client) CreateIdentity(ctx context.Context, envKey, identifier string) (int, error)

func (*Client) CreateMVOption 

func (c *Client) CreateMVOption(ctx context.Context, projectID, featureID int, in MultivariateOption) (*MultivariateOption, error)

CreateMVOption adds a multivariate option (variant) to a feature.

func (*Client) CreateOrganisation 

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

CreateOrganisation creates an organisation from a flat field body.

func (*Client) CreateProject 

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

CreateProject creates a project from a flat field body (name + organisation required).

A project-cap denial arrives as a bare 403, identical to an RBAC "you lack CREATE_PROJECT" denial, so a 403 is only reported as ErrPlanGated once the org is confirmed to be at its plan's project limit.

func (*Client) CreateSegment 

func (c *Client) CreateSegment(ctx context.Context, projectID int, in Segment) (*Segment, error)

CreateSegment creates a segment.

func (*Client) DeleteEdgeIdentityOverride 

func (c *Client) DeleteEdgeIdentityOverride(ctx context.Context, envKey, identifier string, featureID int) error

func (*Client) DeleteEnvironment 

func (c *Client) DeleteEnvironment(ctx context.Context, apiKey string) error

DeleteEnvironment removes an environment by api_key.

func (*Client) DeleteEnvironmentAPIKey 

func (c *Client) DeleteEnvironmentAPIKey(ctx context.Context, envKey string, keyID int) error

func (*Client) DeleteFeature 

func (c *Client) DeleteFeature(ctx context.Context, projectID, featureID int) error

func (*Client) DeleteIdentityOverride 

func (c *Client) DeleteIdentityOverride(ctx context.Context, envKey string, identityID, fsID int) error

DeleteIdentityOverride removes a core identity override by feature-state id.

func (*Client) DeleteMVOption 

func (c *Client) DeleteMVOption(ctx context.Context, projectID, featureID, optionID int) error

func (*Client) DeleteOrganisation 

func (c *Client) DeleteOrganisation(ctx context.Context, orgID int) error

func (*Client) DeleteProject 

func (c *Client) DeleteProject(ctx context.Context, projectID int) error

func (*Client) DeleteSegment 

func (c *Client) DeleteSegment(ctx context.Context, projectID, segmentID int) error

func (*Client) DeleteSegmentOverride 

func (c *Client) DeleteSegmentOverride(ctx context.Context, environmentKey string, feature FeatureRef, segmentID int) error

DeleteSegmentOverride removes a feature's override for one segment, via the experimental delete-segment-override endpoint keyed by the environment key.

func (*Client) EdgeIdentityOverride 

func (c *Client) EdgeIdentityOverride(ctx context.Context, envKey, identityUUID string, featureID int) (*IdentityFeatureState, error)

EdgeIdentityOverride returns an edge identity's override for a feature, or nil. It is keyed by the identity uuid (the identifier endpoint has no GET).

func (*Client) EdgeIdentityOverrides 

func (c *Client) EdgeIdentityOverrides(ctx context.Context, envKey string, featureID int) ([]IdentityOverrideRow, error)

EdgeIdentityOverrides lists every edge (DynamoDB) identity override for a feature. The endpoint has no trailing slash and no pagination — replicated verbatim.

func (*Client) EdgeIdentityUUID 

func (c *Client) EdgeIdentityUUID(ctx context.Context, envKey, identifier string) (uuid string, found bool, err error)

EdgeIdentityUUID resolves an identifier to its edge identity uuid, or found false when none exists yet.

func (*Client) EnvironmentAPIKeys 

func (c *Client) EnvironmentAPIKeys(ctx context.Context, envKey string) ([]EnvironmentAPIKey, error)

func (*Client) EnvironmentDocument 

func (c *Client) EnvironmentDocument(ctx context.Context, apiKey string) (json.RawMessage, error)

EnvironmentDocument fetches the environment document (the offline-evaluation payload) as raw JSON, via the admin document action.

func (*Client) Environments 

func (c *Client) Environments(ctx context.Context, projectID int) ([]Environment, error)

func (*Client) FeatureSegments 

func (c *Client) FeatureSegments(ctx context.Context, environmentID, featureID int) ([]FeatureSegment, error)

FeatureSegments lists a feature's segment overrides in one environment, in priority order. Both filters are required by the endpoint.

func (*Client) FeatureStates 

func (c *Client) FeatureStates(ctx context.Context, environmentID, featureID int) ([]EnvironmentFeatureState, error)

FeatureStates lists a feature's live states in one environment.

func (*Client) Features 

func (c *Client) Features(ctx context.Context, projectID, environmentID, segmentID int, search string) ([]Feature, error)

Features lists a project's features with their state in one environment, identified by its numeric ID. When segmentID is non-zero, each feature also carries its segment_feature_state for that segment. A non-empty search narrows the list server-side: a contains match on the name, not an exact one.

func (*Client) GetEnvironment 

func (c *Client) GetEnvironment(ctx context.Context, apiKey string) (*Environment, error)

GetEnvironment fetches one environment by its client-side api_key.

func (*Client) GetFeature 

func (c *Client) GetFeature(ctx context.Context, projectID, featureID int) (*Feature, error)

GetFeature fetches one project feature (with its multivariate options).

func (*Client) GetOrganisation 

func (c *Client) GetOrganisation(ctx context.Context, orgID int) (*Organisation, error)

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, projectID int) (*Project, error)

func (*Client) GetSegment 

func (c *Client) GetSegment(ctx context.Context, projectID, segmentID int) (*Segment, error)

GetSegment fetches one segment with its full rule tree.

func (*Client) GetSubscriptionMetadata 

func (c *Client) GetSubscriptionMetadata(ctx context.Context, orgID int) (*SubscriptionMetadata, error)

func (*Client) IdentityByIdentifier 

func (c *Client) IdentityByIdentifier(ctx context.Context, envKey, identifier string) (id int, found bool, err error)

IdentityByIdentifier resolves an identifier to its numeric identity id via the core Admin API. found is false when no identity matches.

func (*Client) IdentityOverride 

func (c *Client) IdentityOverride(ctx context.Context, envKey string, identityID, featureID int) (*IdentityFeatureState, error)

IdentityOverride returns a core identity's override for a feature, or nil.

func (*Client) Organisations 

func (c *Client) Organisations(ctx context.Context) ([]Organisation, error)

func (*Client) ProjectFeatures 

func (c *Client) ProjectFeatures(ctx context.Context, projectID int, includeArchived bool) ([]Feature, error)

ProjectFeatures lists a project's features. includeArchived controls whether archived features are returned.

func (*Client) Projects 

func (c *Client) Projects(ctx context.Context, organisationID int) ([]Project, error)

Projects lists an organisation's projects. organisationID 0 lists all accessible projects (the endpoint's organisation filter is optional).

func (*Client) Segments 

func (c *Client) Segments(ctx context.Context, projectID int, include bool) ([]Segment, error)

Segments lists a project's segments. include controls whether feature-specific segments are returned.

func (*Client) SetEdgeIdentityOverride 

func (c *Client) SetEdgeIdentityOverride(ctx context.Context, envKey, identifier string, featureID int, enabled bool, value any) error

SetEdgeIdentityOverride creates-or-updates an edge identity override in one call (the identity is created if it does not exist). value is a native scalar.

func (*Client) SetIdentityOverride 

func (c *Client) SetIdentityOverride(ctx context.Context, envKey string, identityID, featureID, fsID int, enabled bool, value any) error

SetIdentityOverride creates (fsID == 0) or updates a core identity override. value is a native scalar (string/int/bool); the server infers its type.

func (*Client) UpdateEnvironment 

func (c *Client) UpdateEnvironment(ctx context.Context, apiKey string, body map[string]any) (*Environment, error)

UpdateEnvironment patches an environment (project is immutable and ignored).

func (*Client) UpdateFeature 

func (c *Client) UpdateFeature(ctx context.Context, projectID, featureID int, in FeatureWrite) (*Feature, error)

UpdateFeature patches the mutable fields of a feature (name, initial value, and default-enabled are read-only server-side and ignored if sent).

func (*Client) UpdateFlag 

func (c *Client) UpdateFlag(ctx context.Context, environmentKey string, in UpdateFlagRequest) error

UpdateFlag applies an environment-default change via the experimental update-flag-v2 endpoint, keyed by the environment's client-side key. The endpoint returns 204 No Content on success.

func (*Client) UpdateMVOption 

func (c *Client) UpdateMVOption(ctx context.Context, projectID, featureID, optionID int, in MultivariateOption) (*MultivariateOption, error)

UpdateMVOption patches a multivariate option in place (preserving the id, so per-environment weight overrides survive).

func (*Client) UpdateOrganisation 

func (c *Client) UpdateOrganisation(ctx context.Context, orgID int, body map[string]any) (*Organisation, error)

func (*Client) UpdateProject 

func (c *Client) UpdateProject(ctx context.Context, projectID int, body map[string]any) (*Project, error)

UpdateProject patches a project's fields (organisation is immutable and ignored if sent).

func (*Client) UpdateSegment 

func (c *Client) UpdateSegment(ctx context.Context, projectID, segmentID int, in Segment) (*Segment, error)

UpdateSegment replaces a segment's rule tree and fields.

func (*Client) UsersMe 

func (c *Client) UsersMe(ctx context.Context) (*User, error)

type CodeReferenceCount 

type CodeReferenceCount struct {
	Count int `json:"count"`
}

CodeReferenceCount is a per-repository count of code references to a feature.

type Environment 

type Environment struct {
	ID                     int    `json:"id"`
	Name                   string `json:"name"`
	APIKey                 string `json:"api_key"`
	Project                int    `json:"project"`
	Description            string `json:"description"`
	UseV2FeatureVersioning bool   `json:"use_v2_feature_versioning"`
	// contains filtered or unexported fields
}

Environment carries the curated fields plus the raw API item, so JSON output mirrors the server's full field set. Identified by APIKey, not id.

func (Environment) MarshalJSON 

func (e Environment) MarshalJSON() ([]byte, error)

func (*Environment) UnmarshalJSON 

func (e *Environment) UnmarshalJSON(b []byte) error

type EnvironmentAPIKey 

type EnvironmentAPIKey struct {
	ID        int     `json:"id"`
	Key       string  `json:"key,omitempty"`
	Name      string  `json:"name"`
	Active    bool    `json:"active"`
	CreatedAt string  `json:"created_at"`
	ExpiresAt *string `json:"expires_at"`
}

EnvironmentAPIKey is a server-side (ser.) SDK key for an environment. Key is returned in full only on create.

type EnvironmentDefault 

type EnvironmentDefault struct {
	Enabled bool         `json:"enabled"`
	Value   FeatureValue `json:"value"`
}

EnvironmentDefault is the environment-wide state update-flag-v2 requires in full on every call.

type EnvironmentFeatureState 

type EnvironmentFeatureState struct {
	ID             int        `json:"id"`
	Enabled        bool       `json:"enabled"`
	FeatureSegment *int       `json:"feature_segment"`
	Identity       *int       `json:"identity"`
	Value          TypedValue `json:"feature_state_value"`
}

EnvironmentFeatureState is one row of the admin featurestates list: a feature's state for the environment default (feature_segment null), one segment override, or (in v2-versioned environments) an identity override.

type Feature 

type Feature struct {
	ID                   int                  `json:"id"`
	Name                 string               `json:"name"`
	Type                 string               `json:"type"`
	Description          string               `json:"description"`
	NumSegmentOverrides  int                  `json:"num_segment_overrides"`
	NumIdentityOverrides *int                 `json:"num_identity_overrides"`
	LifecycleStage       string               `json:"lifecycle_stage"`
	CodeReferencesCounts []CodeReferenceCount `json:"code_references_counts"`
	EnvironmentState     *FeatureState        `json:"environment_feature_state"`
	SegmentState         *FeatureState        `json:"segment_feature_state"`

	// Project-level definition fields.
	InitialValue        *string              `json:"initial_value"`
	DefaultEnabled      bool                 `json:"default_enabled"`
	IsArchived          bool                 `json:"is_archived"`
	MultivariateOptions []MultivariateOption `json:"multivariate_options"`
}

Feature is a project feature with its state in the requested environment.

func (Feature) CodeReferences 

func (f Feature) CodeReferences() int

CodeReferences totals the per-repository code reference counts.

type FeatureRef 

type FeatureRef struct {
	Name string `json:"name,omitempty"`
	ID   int    `json:"id,omitempty"`
}

FeatureRef targets a feature by name or id (exactly one) in update-flag-v2.

type FeatureSegment 

type FeatureSegment struct {
	ID          int    `json:"id"`
	Segment     int    `json:"segment"`
	SegmentName string `json:"segment_name"`
	Priority    int    `json:"priority"`
}

FeatureSegment links a feature to one segment override in an environment: the override's priority plus the segment's id and name. The endpoint returns rows in priority order and reflects the live version transparently.

type FeatureState 

type FeatureState struct {
	Enabled bool `json:"enabled"`
	Value   any  `json:"feature_state_value"`
}

FeatureState is a feature's state in one environment. In the project features list, feature_state_value is a bare scalar.

type FeatureValue 

type FeatureValue struct {
	Type  string `json:"type"`  // "integer" | "string" | "boolean"
	Value string `json:"value"` // always a string; parsed server-side per type
}

FeatureValue is a typed flag value in the update-flag-v2 wire form: the type as a word and the value always as a string.

type FeatureWrite 

type FeatureWrite struct {
	Name                string               `json:"name,omitempty"`
	Description         *string              `json:"description,omitempty"`
	InitialValue        *string              `json:"initial_value,omitempty"`
	DefaultEnabled      *bool                `json:"default_enabled,omitempty"`
	IsArchived          *bool                `json:"is_archived,omitempty"`
	MultivariateOptions []MultivariateOption `json:"multivariate_options,omitempty"`
}

FeatureWrite is the create/update body. Pointer fields distinguish "unset" from a zero value; the API ignores fields that are read-only for the action.

type IdentityFeatureState 

type IdentityFeatureState struct {
	ID      int  `json:"id"`
	Enabled bool `json:"enabled"`
	Value   any  `json:"feature_state_value"`
	Feature int  `json:"feature"`
}

IdentityFeatureState is a feature's override for one identity. ID is the feature-state id used to update/delete it; it is unset for edge reads.

type IdentityOverrideRow 

type IdentityOverrideRow struct {
	Identifier string
	Enabled    bool
	Value      any
}

IdentityOverrideRow is one identity's override of a feature, as listed by the core or edge override endpoints. Value is a bare scalar.

type MultivariateOption 

type MultivariateOption struct {
	ID                          int      `json:"id,omitempty"`
	Type                        string   `json:"type,omitempty"`
	StringValue                 *string  `json:"string_value,omitempty"`
	IntegerValue                *int     `json:"integer_value,omitempty"`
	BooleanValue                *bool    `json:"boolean_value,omitempty"`
	DefaultPercentageAllocation *float64 `json:"default_percentage_allocation,omitempty"`
	Key                         string   `json:"key,omitempty"`
	Feature                     int      `json:"feature,omitempty"`
}

MultivariateOption is a variant of a multivariate feature. The value is a typed struct (type is "unicode"/"int"/"bool"); default_percentage_allocation is the variant's weight.

type Option 

type Option func(*Client)

Option configures a Client.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient injects the underlying *http.Client. Defaults to httpx.New with the client's User-Agent.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent sent on every request.

type Organisation 

type Organisation struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	// contains filtered or unexported fields
}

Organisation carries the id/name plus the raw API item, so JSON output mirrors the server's full field set.

func (Organisation) MarshalJSON 

func (o Organisation) MarshalJSON() ([]byte, error)

func (*Organisation) UnmarshalJSON 

func (o *Organisation) UnmarshalJSON(b []byte) error

type Project 

type Project struct {
	ID                int    `json:"id"`
	Name              string `json:"name"`
	Organisation      int    `json:"organisation"`
	UseEdgeIdentities bool   `json:"use_edge_identities"`
	// contains filtered or unexported fields
}

Project carries the curated fields plus the raw API item, so JSON output mirrors the server's full field set. UseEdgeIdentities decides whether identity overrides live on the core or the edge endpoints.

func (Project) MarshalJSON 

func (p Project) MarshalJSON() ([]byte, error)

func (*Project) UnmarshalJSON 

func (p *Project) UnmarshalJSON(b []byte) error

type Segment 

type Segment struct {
	ID          int           `json:"id,omitempty"`
	Name        string        `json:"name"`
	Description string        `json:"description,omitempty"`
	Project     int           `json:"project,omitempty"`
	Feature     *int          `json:"feature,omitempty"`
	Rules       []SegmentRule `json:"rules"`
}

Segment is a project segment. Feature is set for feature-specific segments.

type SegmentCondition 

type SegmentCondition struct {
	Property string `json:"property,omitempty"`
	Operator string `json:"operator"`
	Value    any    `json:"value"`
}

SegmentCondition is one condition in a segment rule. On the wire `value` is a plain string (or null); IN arrays are carried as a JSON-array string.

type SegmentOverride 

type SegmentOverride struct {
	SegmentID int          `json:"segment_id"`
	Enabled   bool         `json:"enabled"`
	Value     FeatureValue `json:"value"`
	Priority  *int         `json:"priority,omitempty"`
}

SegmentOverride is one segment's state in the update-flag-v2 body. Priority, when set, moves the override to that position — the server renumbers the others around it, preserving their relative order.

type SegmentRule 

type SegmentRule struct {
	Type       string             `json:"type"`
	Conditions []SegmentCondition `json:"conditions,omitempty"`
	Rules      []SegmentRule      `json:"rules,omitempty"`
}

SegmentRule is a node in a segment's rule tree (ALL/ANY/NONE over conditions and sub-rules).

type SubscriptionMetadata 

type SubscriptionMetadata struct {
	MaxSeats    *int `json:"max_seats"`
	MaxAPICalls *int `json:"max_api_calls"`
	MaxProjects *int `json:"max_projects"`
}

SubscriptionMetadata is an organisation's plan limits. A nil field means the plan sets no limit for it.

type TypedValue 

type TypedValue struct {
	Type         string  `json:"type"`
	StringValue  *string `json:"string_value"`
	IntegerValue *int    `json:"integer_value"`
	BooleanValue *bool   `json:"boolean_value"`
}

TypedValue is the nested feature_state_value wire form the admin featurestates endpoints return: {type, string_value, integer_value, boolean_value} with type one of "unicode", "int", "bool".

func (TypedValue) Scalar 

func (v TypedValue) Scalar() any

Scalar converts the typed wire form to a bare scalar.

type UpdateFlagRequest 

type UpdateFlagRequest struct {
	Feature            FeatureRef         `json:"feature"`
	EnvironmentDefault EnvironmentDefault `json:"environment_default"`
	SegmentOverrides   []SegmentOverride  `json:"segment_overrides,omitempty"`
}

UpdateFlagRequest is the update-flag-v2 body. environment_default is always required; segment_overrides only creates/updates the segments listed and never removes others. This endpoint does not manage identity overrides.

type User 

type User struct {
	Email     string `json:"email"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
	UUID      string `json:"uuid"`
}

User is a subset of GET /api/v1/auth/users/me/.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.