openapi: 3.2.0
info:
  description: 'This page documents how to use the Optimizely FX API.

    With this API you can view and manage Feature Flags and all of their

    related entities including Variables, Variations, Rules, and Reports.


    The base URL is https://api.optimizely.com/flags/v1. Append any paths

    listed in these docs onto that url in order to make requests to the API.'
  title: Optimizely Feature Experimentation Custom Fields API
  version: 0.3.7
  x-logo:
    url: https://app.optimizely.com/static/img/rebrand/logo.svg
servers:
- url: https://api.optimizely.com/flags/v1/
security:
- apiKey: []
- OAuth2:
  - read
  - write
tags:
- description: APIs to manage Custom Field definitions for organizing and annotating flags
  name: Custom Fields
paths:
  /projects/{project_id}/custom_fields:
    get:
      description: Get a list of Custom Fields within a Project.
      operationId: list_custom_fields
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/pageWindow'
      - description: 'Substring search across `key`, `name` and `description` (case-insensitive).

          '
        in: query
        name: query
        required: false
        schema:
          type: string
      - allowReserved: true
        description: 'Sort the custom fields based on the attributes from left to right.

          '
        in: query
        name: sort
        required: false
        schema:
          items:
            enum:
            - name:asc
            - name:desc
            - key:asc
            - key:desc
            - created_time:asc
            - created_time:desc
            - updated_time:asc
            - updated_time:desc
            type: string
          type: array
      - description: 'Filter the custom fields by archived. A custom field can be either archived (archived=true) or unarchived (archived=false)

          '
        in: query
        name: archived
        required: false
        schema:
          type: boolean
      - description: 'Filter the custom fields by key.

          '
        in: query
        name: key
        required: false
        schema:
          type: string
      - description: 'Filter the custom fields by entity type.

          '
        in: query
        name: entity_type
        required: false
        schema:
          enum:
          - flag
          type: string
      - description: 'Filter the custom fields by field type.

          '
        in: query
        name: field_type
        required: false
        schema:
          enum:
          - text
          - number
          - boolean
          - link
          - label
          type: string
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldsListSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      summary: List Custom Fields for a project
      tags:
      - Custom Fields
    post:
      description: Creates a new custom field within the specified project.
      operationId: create_custom_field
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        $ref: '#/components/requestBodies/CustomFieldRequest'
      responses:
        '201':
          $ref: '#/components/responses/CustomFieldSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
      summary: Create a new Custom Field
      tags:
      - Custom Fields
  /projects/{project_id}/custom_fields/{id}:
    patch:
      description: Update fields of a custom field within the specified project.
      operationId: update_custom_field
      parameters:
      - $ref: '#/components/parameters/projectId'
      - description: ID of the custom field to update.
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/CustomFieldUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      summary: Update an existing Custom Field
      tags:
      - Custom Fields
  /projects/{project_id}/custom_fields/{id}/archived:
    post:
      description: Archive a custom field within the specified project. Also sets `required=false`.
      operationId: archive_custom_field
      parameters:
      - $ref: '#/components/parameters/projectId'
      - description: ID of the custom field to archive.
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      summary: Archive a Custom Field
      tags:
      - Custom Fields
  /projects/{project_id}/custom_fields/{id}/unarchived:
    post:
      description: Unarchive a custom field within the specified project.
      operationId: unarchive_custom_field
      parameters:
      - $ref: '#/components/parameters/projectId'
      - description: ID of the custom field to unarchive.
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      summary: Unarchive a Custom Field
      tags:
      - Custom Fields
components:
  parameters:
    projectId:
      description: The project identifier
      example: 12345
      in: path
      name: project_id
      required: true
      schema:
        type: integer
    pageWindow:
      description: Number of previous and next page links to supply for the request (defaults to 1).
      in: query
      name: page_window
      schema:
        type: integer
    pageToken:
      description: Pagination page token. Implements prev, next, last, first
      in: query
      name: page_token
      schema:
        type: string
    perPage:
      description: The max number of items to include per page or results.
      in: query
      name: per_page
      schema:
        format: int64
        type: integer
  schemas:
    CustomField:
      properties:
        archive_url:
          description: URL to archive this custom field
          readOnly: true
          type: string
        archived:
          description: Whether the custom field is archived
          example: false
          type: boolean
        created_time:
          description: Timestamp when the custom field was created
          example: '2019-05-08T00:00:00.000Z'
          format: date-time
          readOnly: true
          type: string
        description:
          description: Description of the custom field
          example: Custom field for tracking feature category
          type: string
        entity_type:
          description: Type of entity this custom field applies to
          enum:
          - flag
          example: flag
          type: string
        field_type:
          description: The data type of the custom field
          enum:
          - text
          - number
          - boolean
          - link
          - label
          example: text
          type: string
        id:
          description: Unique identifier for the custom field
          example: 12345
          format: int64
          readOnly: true
          type: integer
        key:
          description: Unique key for the custom field
          example: feature_category
          type: string
        name:
          description: Display name of the custom field
          example: Feature Category
          type: string
        project_id:
          description: ID of the project this custom field belongs to
          example: 12345
          format: int64
          type: integer
        required:
          description: Whether this custom field is required
          example: false
          type: boolean
        unarchive_url:
          description: URL to unarchive this custom field
          readOnly: true
          type: string
        update_url:
          description: URL to update this custom field
          readOnly: true
          type: string
        updated_time:
          description: Timestamp when the custom field was last updated
          example: '2019-05-08T00:00:00.000Z'
          format: date-time
          readOnly: true
          type: string
        url:
          description: URL to this custom field resource
          readOnly: true
          type: string
      required:
      - id
      - key
      - name
      - field_type
      - entity_type
      - project_id
      type: object
    CustomFieldRequestBody:
      properties:
        description:
          description: Description of the custom field
          type: string
        entity_type:
          description: Type of entity this custom field applies to
          enum:
          - flag
          type: string
        field_type:
          description: The data type of the custom field
          enum:
          - text
          - number
          - boolean
          - link
          - label
          type: string
        key:
          description: Unique key for the custom field
          type: string
        name:
          description: Display name of the custom field
          type: string
        required:
          description: Whether this custom field is required
          type: boolean
      required:
      - key
      - name
      - field_type
      - entity_type
      type: object
    ProblemDetail:
      additionalProperties: true
      description: https://tools.ietf.org/html/rfc7807#section-3.1
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        status:
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI reference [RFC3986] that identifies the problem type. Contains 'about:blank' if unspecified.
          type: string
        uuid:
          description: Error reference for customer support
          type: string
      required:
      - detail
      - status
      - title
      - type
      type: object
    CustomFieldUpdateRequestBody:
      properties:
        description:
          description: Description of the custom field
          type: string
        name:
          description: Display name of the custom field
          type: string
        required:
          description: Whether this custom field is required
          type: boolean
      type: object
    CustomFieldsList:
      properties:
        count:
          description: Number of items on this page
          example: 10
          type: integer
        first_url:
          description: Link to the first page
          type: string
        items:
          description: Array of custom fields
          items:
            $ref: '#/components/schemas/CustomField'
          type: array
        last_url:
          description: Link to the last page
          type: string
        next_url:
          description: Link to the next page
          type: string
        page:
          description: Current page number
          example: 1
          type: integer
        prev_url:
          description: Link to the previous page
          type: string
        total_count:
          description: Total number of custom fields
          example: 100
          type: integer
        total_pages:
          description: Total number of pages
          example: 10
          type: integer
        url:
          description: Link to self
          type: string
      required:
      - url
      - first_url
      - last_url
      - count
      - page
      - total_count
      - total_pages
      - items
      type: object
  requestBodies:
    CustomFieldRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomFieldRequestBody'
      required: true
    CustomFieldUpdateRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomFieldUpdateRequestBody'
      required: true
  responses:
    UnauthorizedResponse:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Invalid credentials
    BadRequestResponse:
      content:
        application/problem+json:
          example:
            detail: Another entity already exists with this same key
            status: 400
            title: Key example_entity already exists"
            uuid: 42c4c855-42f2-4c9a-8544-37b3dff706d2
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Malformed requests and invalid parameter names and types
    NotFoundResponse:
      description: Not found. No content
    ForbiddenResponse:
      content:
        application/problem+json:
          example:
            detail: Permission denied
            status: 403
            title: Forbidden
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Do not have permission to perform the operation
    CustomFieldsListSuccessResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomFieldsList'
      description: 'Successful retrieval of a page of Custom Fields.


        The response includes RESTful JSON (https://restfuljson.org/) styled links and pagination metadata.

        Objects in this API MAY include a url property for a link to itself and MAY append _url to properties for related links.

        If a link is not present in the response, it indicates a user is not authorized to access the related resource.

        '
    CustomFieldSuccessResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomField'
      description: 'Successful retrieval, creation or update of a Custom Field.


        The response includes RESTful JSON (https://restfuljson.org/) styled links. If a

        link is not present in the response, it indicates a user is not authorized to access

        the related resource.

        '
  securitySchemes:
    BearerAuth:
      description: To get a personal token, see https://docs.developers.optimizely.com/web/docs/personal-token
      scheme: bearer
      type: http
    OAuth2:
      description: Write applications that authenticate with the REST API via OAuth 2.0.
      flows:
        authorizationCode:
          authorizationUrl: https://app.optimizely.com/oauth2/authorize
          scopes:
            all: Grants all access
          tokenUrl: https://app.optimizely.com/oauth2/token
      type: oauth2
    apiKey:
      scheme: bearer
      type: http