---
title: "Submit Feature Flag data"
method: POST
path: "/rest/featureflags/0.1/bulk"
tags: ["Feature Flags"]
---

# Submit Feature Flag data

`POST /rest/featureflags/0.1/bulk`

Update / insert Feature Flag data.

Feature Flags are identified by their ID, and existing Feature Flag data for the same ID will be replaced if it exists and the updateSequenceId of existing data is less than the incoming data.

Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The getFeatureFlagById operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple Feature Flags being submitted in one request, each is validated individually prior to submission. Details of which Feature Flags failed submission (if any) are available in the response object.

## Request body

- object — The payload used to submit (update / insert) Feature Flag data.
  - `properties` object — Properties assigned to Feature Flag data that can then be used for delete / query operations. Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system. Note that these properties will never be returned with Feature Flag data. They are not intended for use as metadata to associate with a Feature Flag. Internally they are stored as a hash so that personal information etc. is never stored within Jira. Properties are supplied as key/value pairs, a maximum of 5 properties can be supplied, and keys must not contain ':' or start with '_'.
  - `flags` object[], required — A list of Feature Flags to submit to Jira. Each Feature Flag may be associated with 1 or more Jira issue keys, and will be associated with any properties included in this request.
    - `schemaVersion` '1.0' — The FeatureFlagData schema version used for this flag data. Placeholder to support potential schema changes in the future.
    - `id` string, required — The identifier for the Feature Flag. Must be unique for a given Provider.
    - `key` string, required — The identifier that users would use to reference the Feature Flag in their source code etc. Will be made available via the UI for users to copy into their source code etc.
    - `updateSequenceId` integer, required — An ID used to apply an ordering to updates for this Feature Flag in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the Provider system, but other alternatives are valid (e.g. a Provider could store a counter against each Feature Flag and increment that on each update to Jira). Updates for a Feature Flag that are received with an updateSqeuenceId lower than what is currently stored will be ignored.
    - `displayName` string — The human-readable name for the Feature Flag. Will be shown in the UI. If not provided, will use the ID for display.
    - `issueKeys` string[] — The Jira issue keys to associate the Feature Flag information with.
    - `associations` IssueIdOrKeysAssociation[] — The Jira issue keys or IDs to associate the feature flag with.
      - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
      - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
    - `summary` object, required — Summary information for a single Feature Flag. Providers may elect to provide information from a specific environment, or they may choose to 'roll up' information from across multiple environments - whatever makes most sense in the Provider system. This is the summary information that will be presented to the user on e.g. the Jira issue screen.
      - `url` string, uri — A URL users can use to link to a summary view of this flag, if appropriate. This could be any location that makes sense in the Provider system (e.g. if the summary information comes from a specific environment, it might make sense to link the user to the flag in that environment).
      - `status` object, required — Status information about a single Feature Flag.
        - `enabled` boolean, required — Whether the Feature Flag is enabled in the given environment (or in summary). Enabled may imply a partial rollout, which can be described using the 'rollout' field.
        - `defaultValue` string — The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate. This value may be presented to the user in the UI.
        - `rollout` object — Information about the rollout of a Feature Flag in an environment (or in summary). Only one of 'percentage', 'text', or 'rules' should be provided. They will be used in that order if multiple are present. This information may be presented to the user in the UI.
          - `percentage` number — If the Feature Flag rollout is a simple percentage rollout
          - `text` string — A text status to display that represents the rollout. This could be e.g. a named cohort.
          - `rules` integer — A count of the number of rules active for this Feature Flag in an environment.
      - `lastUpdated` string, date-time, required — The last-updated timestamp to present to the user as a summary of the state of the Feature Flag. Providers may choose to supply the last-updated timestamp from a specific environment, or the 'most recent' last-updated timestamp across all environments - whatever makes sense in the Provider system. Expected format is an RFC3339 formatted string.
    - `details` object[], required — Detail information for this Feature Flag. This may be information for each environment the Feature Flag is defined in or a selection of environments made by the user, as appropriate.
      - `url` string, uri, required — A URL users can use to link to this Feature Flag, in this environment.
      - `lastUpdated` string, date-time, required — The last-updated timestamp for this Feature Flag, in this environment. Expected format is an RFC3339 formatted string.
      - `environment` object, required — Details of a single environment. At the simplest this must be the name of the environment. Ideally there is also type information which may be used to group data from multiple Feature Flags and other entities for visualisation in the UI.
        - `name` string, required — The name of the environment.
        - `type` 'development' | 'testing' | 'staging' | 'production' — The 'type' or 'category' of environment this environment belongs to.
      - `status` object, required — Status information about a single Feature Flag.
        - `enabled` boolean, required — Whether the Feature Flag is enabled in the given environment (or in summary). Enabled may imply a partial rollout, which can be described using the 'rollout' field.
        - `defaultValue` string — The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate. This value may be presented to the user in the UI.
        - `rollout` object — Information about the rollout of a Feature Flag in an environment (or in summary). Only one of 'percentage', 'text', or 'rules' should be provided. They will be used in that order if multiple are present. This information may be presented to the user in the UI.
          - `percentage` number — If the Feature Flag rollout is a simple percentage rollout
          - `text` string — A text status to display that represents the rollout. This could be e.g. a named cohort.
          - `rules` integer — A count of the number of rules active for this Feature Flag in an environment.
  - `providerMetadata` object — Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. It is not considered private information. Hence, it may not contain personally identifiable information.
    - `product` string — An optional name of the source of the feature flags.

## Response `202`

Submission accepted. Each submitted Feature Flag that is of a valid format will be eventually available in Jira.

Details of which Feature Flags were submitted and which failed submission (due to data format problems etc.) are available in the response object.

- object — The result of a successful submitFeatureFlags request.
  - `acceptedFeatureFlags` string[] — The IDs of Feature Flags that have been accepted for submission. A Feature Flag may be rejected if it was only associated with unknown issue keys. Note that a Feature Flag that isn't updated due to it's updateSequenceId being out of order is not considered a failed submission.
  - `failedFeatureFlags` object — Details of Feature Flags that have not been accepted for submission, usually due to a problem with the request data. The object (if present) will be keyed by Feature Flag ID and include any errors associated with that Feature Flag that have prevented it being submitted.
  - `unknownIssueKeys` string[] — Issue keys that are not known on this Jira instance (if any). These may be invalid keys (e.g. `UTF-8` is sometimes incorrectly identified as a Jira issue key), or they may be for projects that no longer exist. If a Feature Flag has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a Feature Flag was only associated with issue keys deemed to be invalid it won't be persisted.
  - `unknownAssociations` IssueIdOrKeysAssociation[] — Associations that are not known on this Jira instance (if any). These may be invalid keys (e.g. `UTF-8` is sometimes incorrectly identified as a Jira issue key), or they may be for projects that no longer exist. If a feature flag has been associated with any other association other than those in this array it will still be stored against those valid associations. If a feature flag was only associated with the associations in this array, it is deemed to be invalid and it won't be persisted.
    - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
    - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.

## Other responses

- `400` — Request has incorrect format. Note that in the case of an individual Feature Flag having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid Feature Flag will be contained in the response object.
- `401` — Missing a JWT token, or token is invalid.
- `403` — The JWT token used does not correspond to an app that defines the Feature Flags module, or the app does not define the 'WRITE' scope.
- `413` — Data is too large. Submit fewer Feature Flags in each payload.
- `429` — API rate limit has been exceeded.
- `503` — Service is unavailable due to maintenance or other reasons.
- `default` — An unknown error has occurred.

---

[API](https://skmtc.net/atlassian/apis/jira-software-cloud-api.md) · [All operations](https://skmtc.net/atlassian/apis/jira-software-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/jira-software-cloud-api/revisions/4e108d54b990/schema)