Jira Feature Flags API

openapi: 3.2.0
info:
  contact:
    url: https://getsupport.atlassian.com
  description: Jira Software Cloud REST API documentation
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://atlassian.com/terms/
  title: Jira Software Cloud Feature Flags API
  version: 1001.0.0
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Feature Flags
  description: APIs related to integrating feature flags with Jira Software.
paths:
  /rest/featureflags/0.1/bulk:
    parameters:
    - name: Authorization
      in: header
      description: 'All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.


        If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.


        See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

        '
      required: true
      schema:
        type: string
        pattern: JWT \S+
    post:
      operationId: submitFeatureFlags
      summary: Submit Feature Flag data
      tags:
      - Feature Flags
      description: '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.'
      requestBody:
        content:
          application/json:
            schema:
              title: SubmitFeatureFlagRequest
              description: The payload used to submit (update / insert) Feature Flag data.
              required:
              - flags
              properties:
                properties:
                  title: Properties
                  description: '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 ''_''.

                    '
                  type: object
                  additionalProperties:
                    type: string
                    maxLength: 255
                  maxProperties: 5
                  example:
                    accountId: account-234
                    projectId: project-123
                flags:
                  description: '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.

                    '
                  type: array
                  items:
                    title: FeatureFlagData
                    description: 'Data related to a single Feature Flag, across any Environment that the flag is present in.

                      '
                    required:
                    - id
                    - key
                    - summary
                    - details
                    - updateSequenceId
                    properties:
                      schemaVersion:
                        description: "The FeatureFlagData schema version used for this flag data. \n\nPlaceholder to support potential schema changes in the future.\n"
                        type: string
                        enum:
                        - '1.0'
                        default: '1.0'
                        example: '1.0'
                      id:
                        description: 'The identifier for the Feature Flag. Must be unique for a given Provider.

                          '
                        type: string
                        maxLength: 255
                        example: 111-222-333
                      key:
                        description: '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.

                          '
                        type: string
                        maxLength: 255
                        example: my-awesome-feature
                      updateSequenceId:
                        description: '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.

                          '
                        type: integer
                        format: int64
                        example: 1523494301448
                      displayName:
                        description: 'The human-readable name for the Feature Flag. Will be shown in the UI.


                          If not provided, will use the ID for display.

                          '
                        type: string
                        maxLength: 255
                        example: Enable awesome feature
                      issueKeys:
                        description: 'The Jira issue keys to associate the Feature Flag information with.

                          '
                        type: array
                        items:
                          title: IssueKey
                          description: 'An issue key that references an issue in Jira.

                            '
                          type: string
                          pattern: ^\w{1,255}-\d{1,255}$
                          example: ISSUE-123
                        minItems: 1
                        maxItems: 100
                        deprecated: true
                      associations:
                        description: The Jira issue keys or IDs to associate the feature flag with.
                        type: array
                        items:
                          $ref: '#/components/schemas/IssueIdOrKeysAssociation'
                      summary:
                        title: FeatureFlagSummary
                        description: '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.

                          '
                        required:
                        - status
                        - lastUpdated
                        properties:
                          url:
                            description: '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).

                              '
                            type: string
                            format: uri
                            maxLength: 2000
                            example: https://example.com/project/feature-123/summary
                          status:
                            title: FeatureFlagStatus
                            description: 'Status information about a single Feature Flag.

                              '
                            required:
                            - enabled
                            properties:
                              enabled:
                                description: '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.

                                  '
                                type: boolean
                              defaultValue:
                                description: '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.

                                  '
                                type: string
                                maxLength: 255
                                example: Disabled
                              rollout:
                                title: FeatureFlagRollout
                                description: '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.

                                  '
                                properties:
                                  percentage:
                                    description: 'If the Feature Flag rollout is a simple percentage rollout

                                      '
                                    type: number
                                    minimum: 0
                                    maximum: 100
                                  text:
                                    description: 'A text status to display that represents the rollout. This could be e.g. a named cohort.

                                      '
                                    type: string
                                    maxLength: 255
                                  rules:
                                    description: 'A count of the number of rules active for this Feature Flag in an environment.

                                      '
                                    type: integer
                                    minimum: 0
                                example:
                                  percentage: 80
                          lastUpdated:
                            description: '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.

                              '
                            type: string
                            format: date-time
                            example: '2018-01-20T23:27:25.000Z'
                      details:
                        description: '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.

                          '
                        type: array
                        items:
                          title: FeatureFlagDetails
                          description: Details of a Feature Flag for a single environment.
                          required:
                          - url
                          - lastUpdated
                          - environment
                          - status
                          properties:
                            url:
                              description: 'A URL users can use to link to this Feature Flag, in this environment.

                                '
                              type: string
                              format: uri
                              maxLength: 2000
                              example: https://example.com/project/feature-123/production
                            lastUpdated:
                              description: 'The last-updated timestamp for this Feature Flag, in this environment.


                                Expected format is an RFC3339 formatted string.

                                '
                              type: string
                              format: date-time
                              example: '2018-01-20T23:27:25.000Z'
                            environment:
                              title: EnvironmentDetails
                              description: '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.

                                '
                              required:
                              - name
                              properties:
                                name:
                                  description: The name of the environment.
                                  type: string
                                  maxLength: 255
                                type:
                                  description: The 'type' or 'category' of environment this environment belongs to.
                                  type: string
                                  enum:
                                  - development
                                  - testing
                                  - staging
                                  - production
                              example:
                                name: prod-us-west
                                type: production
                            status:
                              title: FeatureFlagStatus
                              description: 'Status information about a single Feature Flag.

                                '
                              required:
                              - enabled
                              properties:
                                enabled:
                                  description: '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.

                                    '
                                  type: boolean
                                defaultValue:
                                  description: '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.

                                    '
                                  type: string
                                  maxLength: 255
                                  example: Disabled
                                rollout:
                                  title: FeatureFlagRollout
                                  description: '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.

                                    '
                                  properties:
                                    percentage:
                                      description: 'If the Feature Flag rollout is a simple percentage rollout

                                        '
                                      type: number
                                      minimum: 0
                                      maximum: 100
                                    text:
                                      description: 'A text status to display that represents the rollout. This could be e.g. a named cohort.

                                        '
                                      type: string
                                      maxLength: 255
                                    rules:
                                      description: 'A count of the number of rules active for this Feature Flag in an environment.

                                        '
                                      type: integer
                                      minimum: 0
                                  example:
                                    percentage: 80
                        minItems: 1
                  minItems: 1
                  maxItems: 100
                providerMetadata:
                  title: ProviderMetadata
                  description: '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.

                    '
                  type: object
                  properties:
                    product:
                      type: string
                      description: An optional name of the source of the feature flags.
                      example: Atlassian Release Platform 2.1.0
        description: 'Feature Flag data to submit.

          '
        required: true
      responses:
        '202':
          description: '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.

            '
          content:
            application/json:
              schema:
                title: SubmitFeatureFlagsResponse
                description: 'The result of a successful submitFeatureFlags request.

                  '
                properties:
                  acceptedFeatureFlags:
                    description: '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.

                      '
                    type: array
                    items:
                      type: string
                    example:
                    - 111-222-333
                    - 444-555-666
                  failedFeatureFlags:
                    description: '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.

                      '
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        title: ErrorMessage
                        description: A message supplied in the case of an error.
                        required:
                        - message
                        properties:
                          message:
                            type: string
                            description: A human-readable message describing the error.
                          errorTraceId:
                            type: string
                            description: An optional trace ID that can be used by Jira developers to locate the source of the error.
                  unknownIssueKeys:
                    description: "Issue keys that are not known on this Jira instance (if any). \n\nThese 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.\n\nIf a Feature Flag has been associated with issue keys other than those in this array it will still be stored against those valid keys.\nIf a Feature Flag was only associated with issue keys deemed to be invalid it won't be persisted.\n"
                    type: array
                    items:
                      title: IssueKey
                      description: 'An issue key that references an issue in Jira.

                        '
                      type: string
                      pattern: ^\w{1,255}-\d{1,255}$
                      example: ISSUE-123
                  unknownAssociations:
                    description: '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.

                      '
                    type: array
                    items:
                      $ref: '#/components/schemas/IssueIdOrKeysAssociation'
        '400':
          description: '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.

            '
          content:
            application/json:
              schema:
                title: ErrorMessages
                description: Messages supplied in the case of an error.
                type: array
                minItems: 1
                items:
                  title: ErrorMessage
                  description: A message supplied in the case of an error.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      description: A human-readable message describing the error.
                    errorTraceId:
                      type: string
                      description: An optional trace ID that can be used by Jira developers to locate the source of the error.
        '401':
          description: 'Missing a JWT token, or token is invalid.

            '
        '403':
          description: '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':
          description: 'Data is too large. Submit fewer Feature Flags in each payload.

            '
          content:
            application/json:
              schema:
                title: ErrorMessages
                description: Messages supplied in the case of an error.
                type: array
                minItems: 1
                items:
                  title: ErrorMessage
                  description: A message supplied in the case of an error.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      description: A human-readable message describing the error.
                    errorTraceId:
                      type: string
                      description: An optional trace ID that can be used by Jira developers to locate the source of the error.
        '429':
          description: 'API rate limit has been exceeded.

            '
        '503':
          description: 'Service is unavailable due to maintenance or other reasons.

            '
        default:
          description: 'An unknown error has occurred.

            '
          content:
            application/json:
              schema:
                title: ErrorMessages
                description: Messages supplied in the case of an error.
                type: array
                minItems: 1
                items:
                  title: ErrorMessage
                  description: A message supplied in the case of an error.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      description: A human-readable message describing the error.
                    errorTraceId:
                      type: string
                      description: An optional trace ID that can be used by Jira developers to locate the source of the error.
      security:
      - basicAuth: []
      - OAuth2:
        - write:feature-flag-info:jira
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
  /rest/featureflags/0.1/bulkByProperties:
    parameters:
    - name: Authorization
      in: header
      description: 'All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.


        If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.


        See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

        '
      required: true
      schema:
        type: string
        pattern: JWT \S+
    delete:
      operationId: deleteFeatureFlagsByProperty
      summary: Delete Feature Flags by Property
      tags:
      - Feature Flags
      description: 'Bulk delete all Feature Flags that match the given request.


        One or more query params must be supplied to specify Properties to delete by. Optional param `_updateSequenceId` is no longer supported.

        If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND).

        See the documentation for the submitFeatureFlags operation for more details.


        e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456


        Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed).'
      parameters:
      - name: _updateSequenceId
        in: query
        deprecated: true
        description: 'This parameter usage is no longer supported.


          An optional `_updateSequenceId` to use to control deletion.


          Only stored data with an `updateSequenceId` less than or equal to that provided will be deleted.

          This can be used help ensure submit/delete requests are applied correctly if issued close together.


          If not provided, all stored data that matches the request will be deleted.

          '
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '202':
          description: 'Delete accepted. Data will eventually be removed from Jira.

            '
        '400':
          description: 'Request has incorrect format (e.g. missing at least one Property param).

            '
          content:
            application/json:
              schema:
                title: ErrorMessages
                description: Messages supplied in the case of an error.
                type: array
                minItems: 1
                items:
                  title: ErrorMessage
                  description: A message supplied in the case of an error.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      description: A human-readable message describing the error.
                    errorTraceId:
                      type: string
                      description: An optional trace ID that can be used by Jira developers to locate the source of the error.
        '401':
          description: 'Missing a JWT token, or token is invalid.

            '
        '403':
          description: 'The JWT token used does not correspond to an app that defines the Feature Flags module,

            or the app does not define the ''DELETE'' scope.

            '
        '429':
          description: 'API rate limit has been exceeded.

            '
        '503':
          description: 'Service is unavailable due to maintenance or other reasons.

            '
        default:
          description: 'An unknown error has occurred.

            '
          content:
            application/json:
              schema:
                title: ErrorMessages
                description: Messages supplied in the case of an error.
                type: array
                minItems: 1
                items:
                  title: ErrorMessage
                  description: A message supplied in the case of an error.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      description: A human-readable message describing the error.
                    errorTraceId:
                      type: string
                      description: An optional trace ID that can be used by Jira developers to locate the source of the error.
      security:
      - basicAuth: []
      - OAuth2:
        - delete:feature-flag-info:jira
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: DELETE
  /rest/featureflags/0.1/flag/{featureFlagId}:
    parameters:
    - name: Authorization
      in: header
      description: 'All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.


        If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.


        See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

        '
      required: true
      schema:
        type: string
        pattern: JWT \S+
    get:
      operationId: getFeatureFlagById
      summary: Get a Feature Flag by ID
      tags:
      - Feature Flags
      description: 'Retrieve the currently stored Feature Flag data for the given ID.


        The result will be what is currently stored, ignoring any pending updates or deletes.'
      parameters:
      - name: featureFlagId
        in: path
        description: 'The ID of the Feature Flag to fetch.

          '
        required: true
        schema:
          type: string
          maxLength: 255
      responses:
        '200':
          description: 'The Feature Flag data currently stored for the given ID.

            '
          content:
            application/json:
              schema:
                title: FeatureFlagData
                description: 'Data related to a single Feature Flag, across any Environment that the flag is present in.

                  '
                required:
                - id
                - key
                - summary
                - details
                - updateSequenceId
                properties:
                  schemaVersion:


# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jira/refs/heads/main/openapi/jira-feature-flags-api-openapi.yml