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

# Introduction

> Real-time user segmentation based on events and cohort definitions

The Custom Cohort Segmentation (CCS) API enables real-time user segmentation by processing events against your workspace's cohort definitions. This API is designed for server-side integrations where you need to determine a user's cohort membership in real-time.

## Overview

The CCS API provides two main endpoints:

<CardGroup cols={2}>
  <Card title="Segmentation" icon="users" href="./segmentation">
    Segment a user based on events and persist state for future requests.
  </Card>

  <Card title="Stateless Segmentation" icon="bolt" href="./segmentation-stateless">
    Segment a user without persisting state - ideal for testing and high-performance scenarios.
  </Card>
</CardGroup>

## Use Cases

* **Server-side targeting**: Determine user cohorts server-side before making ad requests
* **Real-time personalization**: Segment users in real-time based on their actions
* **SDK-less integrations**: Integrate with Permutive without using client-side SDKs
* **AMP pages**: Segment users on AMP pages where JavaScript SDK cannot run

## Authentication

All endpoints require API key authentication. You can provide your API key in one of two ways:

* **Query parameter**: `?k=your-api-key`
* **Header**: `X-Api-Key: your-api-key`

<Info>
  You can find your API key in the [Permutive Dashboard](https://dash.permutive.com) under Settings.
</Info>

## Base URL

All API requests should be made to:

```
https://api.permutive.app
```

## Rate Limits

The CCS API is designed for high-throughput scenarios. Contact your Permutive representative for specific rate limit information for your workspace.

## Batch Size

Each request can include up to **10 events**. For larger batches, split your events across multiple requests.