flags

Creates, updates, deletes, gets or lists a flags resource.

Overview

Name	flags
Type	Resource
Id	vercel.feature_flags.flags

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string
owner_id	string	(wire: ownerId)
project_id	string	(wire: projectId)
type_name	string	(flag) (wire: typeName)
created_at	number	(wire: createdAt)
created_by	string	(wire: createdBy)
description	string
environments	object
kind	string	(boolean, json, number, string)
maintainer_ids	array	(wire: maintainerIds)
metadata	object
permanent	boolean	(false, true)
revision	number
seed	number
slug	string
state	string	(active, archived)
tags	array
updated_at	number	(wire: updatedAt)
updated_by	string	(wire: updatedBy)
variants	array

list

Name	Datatype	Description

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	project_id_or_name, flag_id_or_slug	if_match, with_metadata, team_id, slug	Retrieve a specific feature flag by its ID or slug.
list	select	project_id_or_name	state, limit, cursor, search, tags, created_by, maintainer_ids, include_marketplace_flags, team_id, slug	Retrieve feature flags for a project. Returns an opaque cursor for pagination.
create	insert	project_id_or_name, slug, kind, environments	team_id	Create a new feature flag for a project. The flag must have a unique slug within the project and specify its kind (boolean, string, number, or json).
update	update	project_id_or_name, flag_id_or_slug	if_match, with_metadata, team_id, slug	Update an existing feature flag. This endpoint supports partial updates, allowing you to modify specific properties like variants, environments, or state without providing the full flag configuration.
delete	delete	project_id_or_name, flag_id_or_slug	if_match, with_metadata, team_id, slug	Permanently delete a feature flag from the project. This action cannot be undone. Consider archiving the flag instead if you may need it in the future.
list_v1	exec	project_id_or_name	state, withMetadata, limit, cursor, search, tags, teamId, slug	Retrieve feature flags for a project. The list can be filtered by state and supports pagination.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
flag_id_or_slug	string	The flag id or name
project_id_or_name	string	The project id or name
created_by	string	Filter flags by the id of the entity that created them (a user or team id). (wire: createdBy)
cursor	string	Pagination cursor to continue from.
if_match	string	Etag to match, can be used interchangeably with the if-match header (wire: ifMatch)
include_marketplace_flags	boolean	Whether to include Marketplace experimentation items in the paginated response. Defaults to false. (wire: includeMarketplaceFlags)
limit	integer	Maximum number of flags to return. When not set, all flags are returned.
maintainer_ids	array	Filter flags by maintainer user id. Repeat the parameter for multiple maintainers (any may match). (wire: maintainerIds)
search	string	Search flags by their slug or description. Case-insensitive.
slug	string	The Team slug to perform the request on behalf of.
state	string	The state of the flags to retrieve. Defaults to active.
tags	array	Filter flags by tag. Repeat the parameter for multiple tags (all must match).
teamId	string	The Team identifier to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)
withMetadata	boolean	Deprecated. Whether to include creator metadata in each flag in the response. Resolve creator identity client-side (e.g. via the team members endpoint) instead; this parameter will be removed in a future release. Use GET /v1/projects/:id/feature-flags/flags/:flagIdOrSlug?withMetadata=true for single-flag lookups that need creator metadata.
with_metadata	boolean	Whether to include metadata in the response (wire: withMetadata)

SELECT examples

get

Retrieve a specific feature flag by its ID or slug.

SELECT
id,
owner_id,
project_id,
type_name,
created_at,
created_by,
description,
environments,
kind,
maintainer_ids,
metadata,
permanent,
revision,
seed,
slug,
state,
tags,
updated_at,
updated_by,
variants
FROM vercel.feature_flags.flags
WHERE project_id_or_name = '{{ project_id_or_name }}' -- required
AND flag_id_or_slug = '{{ flag_id_or_slug }}' -- required
AND if_match = '{{ if_match }}'
AND with_metadata = '{{ with_metadata }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieve feature flags for a project. Returns an opaque cursor for pagination.

SELECT
*
FROM vercel.feature_flags.flags
WHERE project_id_or_name = '{{ project_id_or_name }}' -- required
AND state = '{{ state }}'
AND limit = '{{ limit }}'
AND cursor = '{{ cursor }}'
AND search = '{{ search }}'
AND tags = '{{ tags }}'
AND created_by = '{{ created_by }}'
AND maintainer_ids = '{{ maintainer_ids }}'
AND include_marketplace_flags = '{{ include_marketplace_flags }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

INSERT examples

create

Create a new feature flag for a project. The flag must have a unique slug within the project and specify its kind (boolean, string, number, or json).

INSERT INTO vercel.feature_flags.flags (
slug,
kind,
variants,
environments,
seed,
description,
state,
maintainer_ids,
permanent,
tags,
project_id_or_name,
team_id
)
SELECT 
'{{ slug }}' /* required */,
'{{ kind }}' /* required */,
'{{ variants }}',
'{{ environments }}' /* required */,
{{ seed }},
'{{ description }}',
'{{ state }}',
'{{ maintainer_ids }}',
{{ permanent }},
'{{ tags }}',
'{{ project_id_or_name }}',
'{{ team_id }}'
RETURNING
id,
owner_id,
project_id,
type_name,
created_at,
created_by,
description,
environments,
kind,
maintainer_ids,
permanent,
revision,
seed,
slug,
state,
tags,
updated_at,
updated_by,
variants
;

Manifest

# Description fields are for documentation purposes
- name: flags
props:
  - name: project_id_or_name
    value: "{{ project_id_or_name }}"
    description: Required parameter for the flags resource.
  - name: slug
    value: "{{ slug }}"
    description: |
      A unique (per project) key for the flag, composed of letters, numbers, dashes, and underscores
  - name: kind
    value: "{{ kind }}"
    description: |
      The kind of flag
    valid_values: ['boolean', 'string', 'number', 'json']
  - name: variants
    description: |
      The variants of the flag
    value:
      - id: "{{ id }}"
        label: "{{ label }}"
        description: "{{ description }}"
        value: "{{ value }}"
  - name: environments
    value: "{{ environments }}"
    description: |
      The configuration for the flag in different environments
  - name: seed
    value: {{ seed }}
    description: |
      A random seed to prevent split points in different flags from having the same targets
  - name: description
    value: "{{ description }}"
    description: |
      A description of the flag
  - name: state
    value: "{{ state }}"
    valid_values: ['active', 'archived']
  - name: maintainer_ids
    value:
      - "{{ maintainer_ids }}"
    description: |
      The user ids of the maintainers of the flag
  - name: permanent
    value: {{ permanent }}
    description: |
      Whether this flag is marked as permanent, indicating it should not be removed
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      Tags for categorizing the flag
  - name: team_id
    value: "{{ team_id }}"
    description: The Team identifier to perform the request on behalf of.
    description: The Team identifier to perform the request on behalf of.

UPDATE examples

update

Update an existing feature flag. This endpoint supports partial updates, allowing you to modify specific properties like variants, environments, or state without providing the full flag configuration.

UPDATE vercel.feature_flags.flags
SET 
created_by = '{{ created_by }}',
message = '{{ message }}',
variants = '{{ variants }}',
environments = '{{ environments }}',
seed = {{ seed }},
description = '{{ description }}',
state = '{{ state }}',
maintainer_ids = '{{ maintainer_ids }}',
permanent = {{ permanent }},
tags = '{{ tags }}'
WHERE 
project_id_or_name = '{{ project_id_or_name }}' --required
AND flag_id_or_slug = '{{ flag_id_or_slug }}' --required
AND if_match = '{{ if_match}}'
AND with_metadata = {{ with_metadata}}
AND team_id = '{{ team_id}}'
AND slug = '{{ slug}}'
RETURNING
id,
owner_id,
project_id,
type_name,
created_at,
created_by,
description,
environments,
kind,
maintainer_ids,
metadata,
permanent,
revision,
seed,
slug,
state,
tags,
updated_at,
updated_by,
variants;

DELETE examples

delete

Permanently delete a feature flag from the project. This action cannot be undone. Consider archiving the flag instead if you may need it in the future.

DELETE FROM vercel.feature_flags.flags
WHERE project_id_or_name = '{{ project_id_or_name }}' --required
AND flag_id_or_slug = '{{ flag_id_or_slug }}' --required
AND if_match = '{{ if_match }}'
AND with_metadata = '{{ with_metadata }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

list_v1

Retrieve feature flags for a project. The list can be filtered by state and supports pagination.

EXEC vercel.feature_flags.flags.list_v1 
@project_id_or_name='{{ project_id_or_name }}' --required, 
@state='{{ state }}', 
@withMetadata={{ withMetadata }}, 
@limit='{{ limit }}', 
@cursor='{{ cursor }}', 
@search='{{ search }}', 
@tags='{{ tags }}', 
@teamId='{{ teamId }}', 
@slug='{{ slug }}'
;