Unleash Context API

openapi: 3.2.0
info:
  title: Unleash Admin Context API
  version: 7.4.1
  description: Create, update, and delete context fields that Unleash is aware of.
servers:
- url: https://app.unleash-instance.example.com
  description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Context
  description: Create, update, and delete context fields that Unleash is aware of.
paths:
  /api/admin/context:
    get:
      tags:
      - Context
      summary: Gets Configured Context Fields
      description: Returns all configured Context fields that have been created.
      operationId: getContextFields
      responses:
        '200':
          description: contextFieldsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldsSchema'
      parameters:
      - name: include
        schema:
          type: string
          example: project
        description: Whether the response should include project-specific or root context fields in addition to the fields in the default response. When querying the root context API, `include=project` will yield a response that includes all project-specific context fields in addition to all root context fields. Conversely, when querying a project-specific context API, using `include=root` will yield a response that includes all root context fields in addition to the project-specific context fields. The other combinations have no effect, because the responses already include those fields. When including project-specific context fields via the root-level API, context fields in private projects the user does not have access to will be omitted.
        in: query
    post:
      tags:
      - Context
      operationId: createContextField
      summary: Create a Context Field
      description: Endpoint that allows creation of custom context fields
      requestBody:
        description: createContextFieldSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createContextFieldSchema'
      responses:
        '201':
          headers:
            location:
              description: The location of the newly created resource.
              schema:
                type: string
                format: uri
          description: The resource was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldSchema'
  /api/admin/context/{contextField}:
    get:
      tags:
      - Context
      summary: Gets Context Field
      description: Returns specific context field identified by the name in the path
      operationId: getContextField
      responses:
        '200':
          description: contextFieldSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldSchema'
      parameters:
      - name: contextField
        in: path
        required: true
        schema:
          type: string
    put:
      tags:
      - Context
      summary: Update an Existing Context Field
      description: Endpoint that allows updating a custom context field. Used to toggle stickiness and add/remove legal values for this context field
      operationId: updateContextField
      requestBody:
        description: updateContextFieldSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateContextFieldSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: contextField
        in: path
        required: true
        schema:
          type: string
    delete:
      tags:
      - Context
      summary: Delete an Existing Context Field
      description: Endpoint that allows deletion of a custom context field. Does not validate that context field is not in use, but since context field configuration is stored in a json blob for the strategy, existing strategies are safe.
      operationId: deleteContextField
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: contextField
        in: path
        required: true
        schema:
          type: string
  /api/admin/context/{contextField}/legal-values:
    post:
      tags:
      - Context
      summary: Add or Update Legal Value for the Context Field
      description: Endpoint that allows adding or updating a single custom context field legal value. If the legal value already exists, it will be updated with the new description
      operationId: updateContextFieldLegalValue
      requestBody:
        description: legalValueSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/legalValueSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: contextField
        in: path
        required: true
        schema:
          type: string
  /api/admin/context/{contextField}/legal-values/{legalValue}:
    delete:
      tags:
      - Context
      summary: Delete Legal Value for the Context Field
      description: Removes the specified custom context field legal value. Does not validate that the legal value is not in use and does not remove usage from constraints that use it.
      operationId: deleteContextFieldLegalValue
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: contextField
        in: path
        required: true
        schema:
          type: string
      - name: legalValue
        in: path
        required: true
        schema:
          type: string
  /api/admin/context/validate:
    post:
      tags:
      - Context
      summary: Validate a Context Field
      description: Check whether the provided data can be used to create a context field. If the data is not valid, returns a 400 status code with the reason why it is not valid.
      operationId: validateContextFieldName
      requestBody:
        description: nameSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nameSchema'
      responses:
        '200':
          description: This response has no body.
  /api/admin/projects/{projectId}/context:
    get:
      tags:
      - Context
      summary: Gets Configured Context Fields
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Returns all configured Context fields that have been created.'
      operationId: getContextFieldsForProject
      responses:
        '200':
          description: contextFieldsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldsSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: include
        schema:
          type: string
          example: project
        description: Whether the response should include project-specific or root context fields in addition to the fields in the default response. When querying the root context API, `include=project` will yield a response that includes all project-specific context fields in addition to all root context fields. Conversely, when querying a project-specific context API, using `include=root` will yield a response that includes all root context fields in addition to the project-specific context fields. The other combinations have no effect, because the responses already include those fields. When including project-specific context fields via the root-level API, context fields in private projects the user does not have access to will be omitted.
        in: query
    post:
      tags:
      - Context
      operationId: createContextFieldForProject
      summary: Create a Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Endpoint that allows creation of custom context fields'
      requestBody:
        description: createContextFieldSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createContextFieldSchema'
      responses:
        '201':
          headers:
            location:
              description: The location of the newly created resource.
              schema:
                type: string
                format: uri
          description: The resource was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/context/{contextField}:
    get:
      tags:
      - Context
      summary: Gets Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Returns specific context field identified by the name in the path'
      operationId: getContextFieldForProject
      responses:
        '200':
          description: contextFieldSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextFieldSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: contextField
        in: path
        required: true
        schema:
          type: string
    put:
      tags:
      - Context
      summary: Update an Existing Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Endpoint that allows updating a custom context field. Used to toggle stickiness and add/remove legal values for this context field'
      operationId: updateContextFieldForProject
      requestBody:
        description: updateContextFieldSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateContextFieldSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: contextField
        in: path
        required: true
        schema:
          type: string
    delete:
      tags:
      - Context
      summary: Delete an Existing Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Endpoint that allows deletion of a custom context field. Does not validate that context field is not in use, but since context field configuration is stored in a json blob for the strategy, existing strategies are safe.'
      operationId: deleteContextFieldForProject
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: contextField
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/context/{contextField}/legal-values:
    post:
      tags:
      - Context
      summary: Add or Update Legal Value for the Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Endpoint that allows adding or updating a single custom context field legal value. If the legal value already exists, it will be updated with the new description'
      operationId: updateContextFieldLegalValueForProject
      requestBody:
        description: legalValueSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/legalValueSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: contextField
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/context/{contextField}/legal-values/{legalValue}:
    delete:
      tags:
      - Context
      summary: Delete Legal Value for the Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Removes the specified custom context field legal value. Does not validate that the legal value is not in use and does not remove usage from constraints that use it.'
      operationId: deleteContextFieldLegalValueForProject
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: contextField
        in: path
        required: true
        schema:
          type: string
      - name: legalValue
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/context/validate:
    post:
      tags:
      - Context
      summary: Validate a Context Field
      description: 'This is a beta endpoint and it may change or be removed in the future.


        Check whether the provided data can be used to create a context field. If the data is not valid, returns a 400 status code with the reason why it is not valid.'
      operationId: validateContextFieldNameForProject
      requestBody:
        description: nameSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nameSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
components:
  schemas:
    contextFieldsSchema:
      type: array
      description: A list of context fields
      items:
        $ref: '#/components/schemas/contextFieldSchema'
    updateContextFieldSchema:
      type: object
      description: Data to update an existing context field configuration.
      properties:
        description:
          type: string
          description: A description of the context field
          example: The user's subscription tier
        stickiness:
          type: boolean
          description: '`true` if this field should be available for use with [custom stickiness](https://docs.getunleash.io/concepts/stickiness#custom-stickiness), otherwise `false`'
          example: false
        sortOrder:
          type: integer
          description: How this context field should be sorted if no other sort order is selected
          example: 2
        legalValues:
          type: array
          description: A list of allowed values for this context field
          example:
          - value: gold
          - value: silver
          - value: crystal
          items:
            $ref: '#/components/schemas/legalValueSchema'
        project:
          description: The project this context field belongs to (if it is project-specific)
          type: string
          example: my-project
    legalValueSchema:
      type: object
      additionalProperties: false
      description: Describes a legal value. Typically used to limit possible values for contextFields or strategy properties
      required:
      - value
      properties:
        value:
          description: The valid value
          type: string
          example: '#c154c1'
        description:
          description: Describes this specific legal value
          type: string
          example: Deep fuchsia
    contextFieldSchema:
      type: object
      additionalProperties: false
      description: A representation of a [context field](https://docs.getunleash.io/concepts/unleash-context).
      required:
      - name
      properties:
        name:
          description: The name of the context field
          type: string
          example: userId
        description:
          description: The description of the context field.
          type:
          - string
          - 'null'
          example: Used to uniquely identify users
        stickiness:
          description: Does this context field support being used for [stickiness](https://docs.getunleash.io/concepts/stickiness) calculations
          type: boolean
          example: true
        sortOrder:
          description: Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.
          type: integer
          example: 900
        createdAt:
          description: When this context field was created
          type:
          - string
          - 'null'
          format: date-time
          example: '2023-06-29T10:19:00.000Z'
        usedInFeatures:
          type:
          - integer
          - 'null'
          description: Number of projects where this context field is used in
          example: 3
          minimum: 0
        usedInProjects:
          type:
          - integer
          - 'null'
          description: Number of projects where this context field is used in
          example: 2
          minimum: 0
        legalValues:
          description: Allowed values for this context field schema. Can be used to narrow down accepted input
          type: array
          items:
            $ref: '#/components/schemas/legalValueSchema'
        project:
          description: The project this context field belongs to (if it is project-specific)
          type: string
          example: my-project
    nameSchema:
      type: object
      additionalProperties: false
      required:
      - name
      description: An object with a name
      properties:
        name:
          description: The name of the represented object.
          example: betaUser
          type: string
    createContextFieldSchema:
      type: object
      description: Data used to create a context field configuration.
      properties:
        description:
          type: string
          description: A description of the context field
          example: The user's subscription tier
        stickiness:
          type: boolean
          description: '`true` if this field should be available for use with [custom stickiness](https://docs.getunleash.io/concepts/stickiness#custom-stickiness), otherwise `false`'
          example: false
        sortOrder:
          type: integer
          description: How this context field should be sorted if no other sort order is selected
          example: 2
        legalValues:
          type: array
          description: A list of allowed values for this context field
          example:
          - value: gold
          - value: silver
          - value: crystal
          items:
            $ref: '#/components/schemas/legalValueSchema'
        project:
          description: The project this context field belongs to (if it is project-specific)
          type: string
          example: my-project
        name:
          description: The name of the context field.
          type: string
          example: subscriptionTier
      required:
      - name
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key needed to access this API
    bearerToken:
      type: http
      scheme: bearer
      description: API key needed to access this API, in Bearer token format