> ## 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.

# Stateless Segmentation

> This endpoint accepts a list of events for a given user and optionally some pre-existing state for the user. It uses these to determine the full list of cohorts of which they are a member, and returns these along with the updated state for the user. State is not persisted, so will not be used in the next request unless it is passed back in as part of that request.

It is likely that this endpoint is more performant than the stateful segmentation endpoint, since it does not need to read state for the user from a database. It is also useful for testing purposes.

Events provided to this endpoint are published to the Permutive Events API, meaning that they will be reflected in other areas of Permutive, for example Insights.


<Info>
  This endpoint does not persist state. If you need state persistence, use the [Segmentation](./segmentation) endpoint instead.
</Info>

## When to Use Stateless Segmentation

The stateless endpoint is ideal for:

* **Testing and debugging**: Verify cohort logic without affecting production state
* **High-performance scenarios**: Skip database reads/writes for faster response times
* **Client-managed state**: When you want to manage user state in your own systems

## User State

You can optionally provide pre-existing user state in the request. The response will include the updated state that you should store and pass back in subsequent requests.

<Warning>
  The `state` field format is internal to Permutive and should not be parsed or modified. Treat it as an opaque blob.
</Warning>

## Example Usage

### First Request (No State)

```bash theme={"dark"}
curl -X POST "https://api.permutive.app/ccs/v1/segmentation/stateless?k=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
    "events": [
      {
        "name": "Pageview",
        "time": "2024-01-15T10:30:00Z",
        "properties": {
          "category": "technology"
        }
      }
    ]
  }'
```

### Subsequent Request (With State)

```bash theme={"dark"}
curl -X POST "https://api.permutive.app/ccs/v1/segmentation/stateless?k=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
    "events": [
      {
        "name": "Pageview",
        "time": "2024-01-15T10:35:00Z",
        "properties": {
          "category": "sports"
        }
      }
    ],
    "state": {
      "internal_state": { ... },
      "external_state": { ... },
      "cohorts": ["12345", "67890"]
    }
  }'
```

## Response

The response includes:

* `user_id`: The Permutive User ID
* `state`: The updated user state (including cohort memberships)

Store the returned `state` and include it in your next request to maintain continuity.


## OpenAPI

````yaml POST /ccs/v1/segmentation/stateless
openapi: 3.1.0
info:
  title: Custom Cohort Segmentation API
  version: v1
servers:
  - url: https://api.permutive.app
security: []
paths:
  /ccs/v1/segmentation/stateless:
    post:
      tags:
        - API version 1
      summary: Segment user based on provided events and state only
      description: >
        This endpoint accepts a list of events for a given user and optionally
        some pre-existing state for the user. It uses these to determine the
        full list of cohorts of which they are a member, and returns these along
        with the updated state for the user. State is not persisted, so will not
        be used in the next request unless it is passed back in as part of that
        request.


        It is likely that this endpoint is more performant than the stateful
        segmentation endpoint, since it does not need to read state for the user
        from a database. It is also useful for testing purposes.


        Events provided to this endpoint are published to the Permutive Events
        API, meaning that they will be reflected in other areas of Permutive,
        for example Insights.
      operationId: postCcsV1SegmentationStateless
      parameters:
        - name: synchronous-validation
          in: query
          description: >-
            Validate provided event(s) against their schema before proceeding
            with segmentation.


            By default validation is performed asynchronously after segmentation
            has been performed and the response has been returned. This can make
            it difficult to debug issues with invalid events.


            It is recommended to use this option only during development and
            debugging, as validation can be expensive and slow.
          required: false
          schema:
            default: false
            type: boolean
      requestBody:
        description: >
          A user identifier and a list of events to be used for segmentation,
          plus optional pre-existing state for the user.


          The user identifier must be either a `user_id`, an `alias`, or a list
          of prioritised aliases.


          The largest number of events that can currently be included in a
          single request is 10.


          State is in the JSON format returned by this endpoint. It is not
          intended to be parsed or understood outside the context of this API or
          a Permutive SDK.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentationRequestWithState'
            example:
              user_id: 2008c38f-dece-4570-976d-87593ed001c3
              alias: null
              aliases: null
              events:
                - name: Pageview
                  time: '2022-06-22T19:40:43.179Z'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_property: interesting
                - name: Pageview
                  time: '2022-06-22T19:40:45.152Z'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_object:
                      inner_property: 42
              state:
                internal_state:
                  '12345':
                    0c8b70cdb7:
                      - p
                      - 1
                external_state:
                  '67890':
                    0c8b70cdb7:
                      - p
                      - 1
                cohorts:
                  - '12345'
                  - '67890'
        required: true
      responses:
        '200':
          description: >-
            The Permutive User ID and the user's state (including the list of
            cohorts of which they are a member).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationResponseWithState'
              example:
                user_id: 2008c38f-dece-4570-976d-87593ed001c3
                state:
                  internal_state:
                    '12345':
                      0c8b70cdb7:
                        - p
                        - 1
                  external_state:
                    '67890':
                      0c8b70cdb7:
                        - p
                        - 1
                  cohorts:
                    - '12345'
                    - '67890'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
      security:
        - apiKeyAuth: []
        - apiKeyAuth1: []
components:
  schemas:
    SegmentationRequestWithState:
      title: SegmentationRequestWithState
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        alias:
          $ref: '#/components/schemas/Alias'
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritisedAlias'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        state:
          $ref: '#/components/schemas/UserState'
    SegmentationResponseWithState:
      title: SegmentationResponseWithState
      type: object
      required:
        - user_id
        - state
      properties:
        user_id:
          type: string
          format: uuid
        state:
          $ref: '#/components/schemas/UserState'
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
        - request_id
        - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          required:
            - type
            - status_code
            - status
            - code
            - message
            - docs
          properties:
            type:
              type: string
            status_code:
              type: integer
              format: int32
            status:
              type: string
            code:
              type: integer
              format: int32
            message:
              type: string
            docs:
              type: string
            cause:
              type: string
    Alias:
      title: Alias
      type: object
      required:
        - tag
        - id
      properties:
        tag:
          type: string
        id:
          type: string
    PrioritisedAlias:
      title: PrioritisedAlias
      type: object
      required:
        - priority
        - tag
        - id
      properties:
        priority:
          type: integer
          format: int32
        tag:
          type: string
        id:
          type: string
    Event:
      title: Event
      type: object
      required:
        - name
        - time
        - properties
      properties:
        name:
          type: string
        time:
          type: string
          format: date-time
        view_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        properties:
          $ref: '#/components/schemas/JsonObject'
    UserState:
      title: UserState
      type: object
      required:
        - internal_state
        - external_state
      properties:
        internal_state:
          $ref: '#/components/schemas/DeviceState'
        external_state:
          $ref: '#/components/schemas/DeviceState'
        cohorts:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CohortId'
    RequestId:
      title: RequestId
      oneOf:
        - type: string
        - type: string
        - type: string
          format: uuid
    JsonObject:
      title: JsonObject
      type: object
    DeviceState:
      title: DeviceState
      examples:
        - '12345':
            0c8b70cdb7:
              - p
              - 1
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ChecksummedState'
    CohortId:
      title: CohortId
      examples:
        - 12345
      type: string
    ChecksummedState:
      title: ChecksummedState
      examples:
        - 0c8b70cdb7:
            - p
            - 1
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CohortState'
    CohortState:
      title: CohortState
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: k
      in: query
    apiKeyAuth1:
      type: apiKey
      name: X-Api-Key
      in: header

````