FlagPal API (1.0.0)

Download OpenAPI specification:

Feature flagging and A/B experimentation API following the JSON:API specification.

Authentication

All endpoints require a project-specific Bearer token supplied in the Authorization header. You can generate the token by visiting the project settings page in you FlagPal dashboard.

JSON:API conventions

All request and response bodies use Content-Type: application/vnd.api+json.
Resources are identified by ULID (unless noted otherwise).
Attribute names use snake_case.
Filtering: filter[field]=value or filter[field][]=value1&filter[field][]=value2 for arrays.
Pagination: page[number] and page[size].
Sorting: comma-separated field names, prefix with - for descending (e.g. sort=-created_at,name).
Sparse fieldsets: fields[type]=field1,field2.
Sideloading: include=relationship1,relationship2.

Features

Feature flags definitions for a project.

List features

Returns a paginated collection of feature flags scoped to the authenticated project.

Authorizations:

bearerAuth

query Parameters

filter[id][]	Array of strings Filter by one or more ULIDs.
filter[name][]	Array of strings Example: filter[name][]=dark-mode Filter by one or more feature names.
filter[kind][]	Array of strings Items Enum: "string" "integer" "boolean" "array" "date" Filter by one or more feature kinds.
sort	string Example: sort=name Comma-separated sort fields. Sortable: `name`, `created_at`, `updated_at`. Prefix with `-` for descending (e.g. `-created_at`).
page[number]	integer >= 1 Default: 1
page[size]	integer [ 1 .. 1000 ] Default: 1000
fields[features]	string Example: fields[features]=name,kind Comma-separated list of attributes to return (sparse fieldsets).

Responses

Response samples

200
401

Content type

application/vnd.api+json

{"data": [{"type": "features",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "dark-mode",
"description": "Enables the dark colour scheme.",
"kind": "boolean",
"rules": [{"rule": "equals",
"value": true
}
],
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"links": {"self": "http://example.com"
}
}
],
"links": {"first": "http://example.com",
"last": "http://example.com",
"prev": "http://example.com",
"next": "http://example.com"
},
"meta": {"page": {"currentPage": 1,
"from": 1,
"lastPage": 3,
"perPage": 100,
"to": 100,
"total": 250
}
}
}

Get a feature

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Feature ULID.

query Parameters

fields[features]

string

Comma-separated list of attributes to return.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": {"type": "features",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "dark-mode",
"description": "Enables the dark colour scheme.",
"kind": "boolean",
"rules": [{"rule": "equals",
"value": true
}
],
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"links": {"self": "http://example.com"
}
}
}

Funnels

Funnels split traffic into variants (feature sets). A funnel can be an experience (feature flag rollout) or an experiment (A/B test).

List funnels

Returns a paginated collection of funnels (experiences and experiments) scoped to the authenticated project.

Default sort order is kind, -weight.

Authorizations:

bearerAuth

query Parameters

filter[id][]	Array of strings Filter by one or more ULIDs.
filter[active]	boolean Example: filter[active]=true Filter by active status.
filter[kind]	string Enum: "experience" "experiment" Example: filter[kind]=experiment Filter by funnel kind.
sort	string Example: sort=kind,-weight Comma-separated sort fields. Sortable: `kind`, `weight`, `created_at`, `updated_at`. Default: `kind,-weight`. Prefix with `-` for descending.
page[number]	integer >= 1 Default: 1
page[size]	integer [ 1 .. 1000 ] Default: 1000
include	string Example: include=featureSets,metrics Comma-separated relationships to sideload. Supports `featureSets` and `metrics`.
fields[funnels]	string Comma-separated list of funnel attributes to return.
fields[feature-sets]	string Comma-separated list of feature-set attributes to return (when using `include=featureSets`).
fields[metrics]	string Comma-separated list of metric attributes to return (when using `include=metrics`).

Responses

Response samples

200
401

Content type

application/vnd.api+json

{"data": [{"type": "funnels",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"active": true,
"kind": "experiment",
"weight": 100,
"percent": 50,
"name": "Dark Mode Theme",
"description": "Hypothesis - Dark Mode theme increases conversion rate.",
"rules": [{"feature": "dark-mode",
"rule": "equals",
"value": null
}
],
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"featureSets": {"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
},
"metrics": {"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
}
],
"links": {"first": "http://example.com",
"last": "http://example.com",
"prev": "http://example.com",
"next": "http://example.com"
},
"meta": {"page": {"currentPage": 1,
"from": 1,
"lastPage": 3,
"perPage": 100,
"to": 100,
"total": 250
}
},
"included": [{"type": "feature-sets",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "Dark Mode Enabled",
"weight": 50,
"features": {"dark-mode": true,
"button-color": "blue"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"funnel": {"data": {"type": "string",
"id": "string"
},
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
}
]
}

Get a funnel

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

query Parameters

include	string Example: include=featureSets,metrics Comma-separated relationships to sideload. Supports `featureSets` and `metrics`.
fields[funnels]	string
fields[feature-sets]	string
fields[metrics]	string

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": {"type": "funnels",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"active": true,
"kind": "experiment",
"weight": 100,
"percent": 50,
"name": "Dark Mode Theme",
"description": "Hypothesis - Dark Mode theme increases conversion rate.",
"rules": [{"feature": "dark-mode",
"rule": "equals",
"value": null
}
],
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"featureSets": {"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
},
"metrics": {"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
},
"included": [{"type": "feature-sets",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "Dark Mode Enabled",
"weight": 50,
"features": {"dark-mode": true,
"button-color": "blue"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"funnel": {"data": {"type": "string",
"id": "string"
},
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
}
]
}

Get a funnel's feature sets

Returns the collection of variants (feature sets) that belong to a funnel.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "feature-sets",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "Dark Mode Enabled",
"weight": 50,
"features": {"dark-mode": true,
"button-color": "blue"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"funnel": {"data": {"type": "string",
"id": "string"
},
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
}
]
}

Get funnel → feature-sets relationship linkage

Returns only the resource identifiers for the funnel's feature-sets relationship.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}

Get a funnel's metrics

Returns the metrics tracked for an experiment funnel.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "metrics",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"kind": "count",
"name": "Checkout Conversions",
"description": "Number of completed checkouts."
},
"links": {"self": "http://example.com"
}
}
]
}

Get funnel → metrics relationship linkage

Returns only the resource identifiers for the funnel's metrics relationship.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "string",
"id": "string"
}
],
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}

Feature Sets

Variants within a funnel, each with a set of feature flag values. Feature sets can have custom traffic weight.

Get a funnel's feature sets

Returns the collection of variants (feature sets) that belong to a funnel.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "feature-sets",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"name": "Dark Mode Enabled",
"weight": 50,
"features": {"dark-mode": true,
"button-color": "blue"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"relationships": {"funnel": {"data": {"type": "string",
"id": "string"
},
"links": {"self": "http://example.com",
"related": "http://example.com"
}
}
},
"links": {"self": "http://example.com"
}
}
]
}

Metrics

Measurable outcomes available for tracking within experiments (A/B tests).

Get a funnel's metrics

Returns the metrics tracked for an experiment funnel.

Authorizations:

bearerAuth

path Parameters

id

required

string (Ulid)

Example: 01HQ5Z2K3VF9A8BPXTNEC7RD4M

Funnel ULID.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": [{"type": "metrics",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M",
"attributes": {"kind": "count",
"name": "Checkout Conversions",
"description": "Number of completed checkouts."
},
"links": {"self": "http://example.com"
}
}
]
}

Metric Time Series

Individual metric data points recorded against a feature set variant.

Record a metric value

Records a metric data point for a specific feature set variant in an experiment.

Processing is asynchronous — returns 202 Accepted immediately; the value is written in the background.

Constraints:

The metric must be attached to the experiment that owns the featureSet.
Both metric and featureSet must belong to the authenticated project.

Authorizations:

bearerAuth

Request Body schema: application/vnd.api+json
required

required

object

Responses

Request samples

Payload

Content type

application/vnd.api+json

{"data": {"type": "metric-time-series",
"attributes": {"time_segment": "2024-06-01T12:00:00Z",
"value": 42
},
"relationships": {"metric": {"data": {"type": "metrics",
"id": "01HQ5Z2K3VF9A8BPXTNEC7RD4M"
}
},
"featureSet": {"data": {"type": "feature-sets",
"id": "01HR7Y4MNPXE2CQVB8DFGJW93K"
}
}
}
}
}

Response samples

202
400
401
404
422

Content type

application/vnd.api+json

{"data": [null
],
"meta": {"message": "The metric value will be recorded asynchronously."
}
}

Actors

Entities (users, sessions, devices) assigned feature flag values.

Create or update an actor

Creates a new actor or updates an existing actor's feature flag assignments (upsert).

Provide a client-chosen id (e.g. a user ID, session token) to upsert by a stable reference.
If id is omitted, a ULID is auto-generated and a new actor is always created.
The features map uses feature names as keys. Unknown feature names are silently ignored.

Returns 201 Created when a new actor is created, 200 OK when an existing actor is updated.

Authorizations:

bearerAuth

Request Body schema: application/vnd.api+json
required

required

object

Responses

Request samples

Payload

Content type

application/vnd.api+json

Example

Upsert actor by known reference

{"data": {"type": "actors",
"id": "user_12345",
"attributes": {"features": {"dark-mode": true,
"max-items": 10
}
}
}
}

Response samples

200
201
401
422

Content type

application/vnd.api+json

{"data": {"type": "actors",
"id": "user_12345",
"attributes": {"features": {"dark-mode": true,
"max-items": 10
},
"created_at": "2024-03-10T09:00:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"links": {"self": "http://example.com"
}
}
}

Get an actor

Returns an actor and their current feature flag assignments.

Authorizations:

bearerAuth

path Parameters

id

required

string

Example: user_12345

The actor's reference identifier.

Responses

Response samples

200
401
404

Content type

application/vnd.api+json

{"data": {"type": "actors",
"id": "user_12345",
"attributes": {"features": {"dark-mode": true,
"max-items": 10
},
"created_at": "2024-03-10T09:00:00.000000Z",
"updated_at": "2024-06-01T08:00:00.000000Z"
},
"links": {"self": "http://example.com"
}
}
}

FlagPal API (1.0.0)

Authentication

JSON:API conventions

Features

List features

Authorizations:

query Parameters

Responses

Response samples

Get a feature

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Funnels

List funnels

Authorizations:

query Parameters

Responses

Response samples

Get a funnel

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Get a funnel's feature sets

Authorizations:

path Parameters

Responses

Response samples

Get funnel → feature-sets relationship linkage

Authorizations:

path Parameters

Responses

Response samples

Get a funnel's metrics

Authorizations:

path Parameters

Responses

Response samples

Get funnel → metrics relationship linkage

Authorizations:

path Parameters

Responses

Response samples

Feature Sets

Get a funnel's feature sets

Authorizations:

path Parameters

Responses

Response samples

Metrics

Get a funnel's metrics

Authorizations:

path Parameters

Responses

Response samples

Metric Time Series

Record a metric value

Authorizations:

Request Body schema: application/vnd.api+jsonrequired

Responses

Request samples

Response samples

Actors

Create or update an actor

Authorizations:

Request Body schema: application/vnd.api+jsonrequired

Responses

Request samples

Response samples

Get an actor

Authorizations:

path Parameters

Responses

Response samples

Request Body schema: application/vnd.api+json
required

Request Body schema: application/vnd.api+json
required