> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a cohort

> This endpoint allows updating an existing cohort. Depending on the access level of the provided API key, it can update cohorts owned by the requesting workspace, or also by child workspaces below the requesting workspace in the organization hierarchy. Lookalike-based cohorts cannot be updated via the Cohort API.

Any top level fields for which no value is provided in the request body will remain unchanged. Optional fields (currently only `description`) can be deleted by explicitly specifying `null` as the value.



## OpenAPI

````yaml PATCH /v2/cohorts/{cohortId}
openapi: 3.0.1
info:
  title: Cohorts API
  version: '1'
  description: Programmatically view and maintain cohort definitions
servers:
  - url: https://api.permutive.app/cohorts-api
security: []
paths:
  /v2/cohorts/{cohortId}:
    patch:
      tags:
        - v2
      summary: Update cohort
      description: >-
        This endpoint allows updating an existing cohort. Depending on the
        access level of the provided API key, it can update cohorts owned by the
        requesting workspace, or also by child workspaces below the requesting
        workspace in the organization hierarchy. Lookalike-based cohorts cannot
        be updated via the Cohort API.


        Any top level fields for which no value is provided in the request body
        will remain unchanged. Optional fields (currently only `description`)
        can be deleted by explicitly specifying `null` as the value.
      operationId: patchV2CohortsCohortid
      parameters:
        - name: cohortId
          in: path
          description: Cohort UUID
          required: true
          schema:
            type: string
          example: 38470a62-9837-4c86-bbf3-45dd6d52dd83
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSegmentV2'
            examples:
              update all fields:
                value:
                  name: New Segment Name
                  description: New Segment Description
                  query:
                    event: Pageview
                    frequency:
                      greater_than_or_equal_to: 2
                    where:
                      property: properties.client.url
                      condition:
                        contains: football
                    during:
                      the_last:
                        value: 30
                        unit: days
                  tags:
                    - tag_d
                    - tag_e
              update a single field:
                value:
                  name: New Segment Name
              delete the cohort description:
                value:
                  description: null
        required: true
      responses:
        '200':
          description: Cohort in full (including query)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentQueryApiV2'
              example:
                id: 38470a62-9837-4c86-bbf3-45dd6d52dd83
                code: 12345
                name: Example Segment A
                description: This segment is an example for documentation purposes
                query:
                  event: Pageview
                  frequency:
                    greater_than_or_equal_to: 2
                  where:
                    property: properties.client.url
                    condition:
                      contains: football
                  during:
                    the_last:
                      value: 30
                      unit: days
                tags:
                  - tag_a
                  - tag_b
                state: Enabled
                segment_type: real_time
                created_at: '2022-09-22T15:44:29.518935935Z'
                last_updated_at: '2022-09-22T15:44:29.518937018Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                  status_code: 400
                  status: Bad Request
                  code: 1002
                  message: The provided request body was not structured as expected.
                  docs: https://developer.permutive.com/reference#errors
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7235#section-3.1
                  status_code: 401
                  status: Unauthorized
                  code: 2005
                  message: The supplied authentication is invalid.
                  docs: https://developer.permutive.com/reference#errors
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7231#section-6.5.3
                  status_code: 403
                  status: Forbidden
                  code: 2001
                  message: >-
                    The API key provided does not provide access to the request
                    operation or resource.
                  docs: https://developer.permutive.com/reference#errors
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7231#section-6.5.4
                  status_code: 404
                  status: Not Found
                  code: 3000
                  message: The requested resource does not exist.
                  docs: https://developer.permutive.com/reference#errors
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7231#section-6.5.8
                  status_code: 409
                  status: Conflict
                  code: 4000
                  message: A resource with this identifier already exists.
                  docs: https://developer.permutive.com/reference#errors
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
                error:
                  type: https://tools.ietf.org/html/rfc7231#section-6.6.1
                  status_code: 500
                  status: Internal Server Error
                  code: 5000
                  message: >-
                    An error of unspecified nature was encountered while
                    processing your request. Feel free to get in touch with us
                    at support@permutive.com referencing the Request ID.
                  docs: https://developer.permutive.com/reference#errors
      security:
        - apiKeyAuth: []
components:
  schemas:
    UpdateSegmentV2:
      type: object
      properties:
        name:
          type: string
        description:
          $ref: '#/components/schemas/UpdateOrDelete_String'
        query:
          $ref: '#/components/schemas/Json'
        tags:
          type: array
          items:
            type: string
        state:
          type: string
          enum:
            - Enabled
            - Disabled
    SegmentQueryApiV2:
      required:
        - id
        - code
        - name
        - query
        - state
        - segmentType
        - createdAt
        - lastUpdatedAt
      type: object
      properties:
        id:
          type: string
        code:
          type: integer
        name:
          type: string
        description:
          type: string
        query:
          $ref: '#/components/schemas/Json'
        tags:
          type: array
          items:
            type: string
        state:
          type: string
          enum:
            - Enabled
            - Disabled
        workspaceId:
          type: string
        segmentType:
          $ref: '#/components/schemas/SegmentType'
        createdAt:
          type: string
          format: date-time
        lastUpdatedAt:
          type: string
          format: date-time
    HttpErrorResponse:
      required:
        - requestId
        - error
      type: object
      properties:
        requestId:
          type: string
        error:
          $ref: '#/components/schemas/HttpError'
    UpdateOrDelete_String:
      type: string
      nullable: true
    Json: {}
    SegmentType:
      oneOf:
        - $ref: '#/components/schemas/Offline'
        - $ref: '#/components/schemas/RealTime'
    HttpError:
      required:
        - status
        - code
        - message
      type: object
      properties:
        status:
          $ref: '#/components/schemas/HttpStatus'
        code:
          type: integer
        message:
          type: string
        cause:
          type: string
    Offline:
      type: object
    RealTime:
      type: object
    HttpStatus:
      required:
        - code
      type: object
      properties:
        code:
          type: integer
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: k
      in: query

````