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

> Programmatically manage cohorts

The Cohorts API allows for the programmatic creation, mutation, and deletion of cohorts for your workspace.

## Authentication

It's important to note that all requests to the Cohorts API must be authenticated with a private API key. See the [Authentication](/api/authentication) section for details on obtaining and using a private API key.

The behavior of the API depends on which workspace the private API key is associated with in your organization. Details are provided with each endpoint in this documentation.

There are various different access levels available. By default, a private API key will provide read-only access to cohorts defined in the workspace that owns the API key, or inherited from workspaces above this workspace in an organization hierarchy. Please contact [Technical Services](mailto:technical-services@permutive.com) if you would like to discuss different access levels to the Cohorts API.

## Cohort query format

The behavior of a cohort is defined by a *query*, which specifies the conditions a user must meet to fall into the cohort. When creating, updating or viewing cohorts, the Cohorts API uses a JSON format to represent these queries.

<CardGroup cols={1}>
  <Card title="Cohort query format" icon="code" href="./cohort-query-format">
    How to define the behavior of cohorts
  </Card>
</CardGroup>

## Endpoints

The Cohorts API provides five endpoints:

<CardGroup cols={3}>
  <Card title="Create a cohort" icon="users" href="./create-cohort">
    Create a cohort for your workspace.
  </Card>

  <Card title="Retrieve a cohort" icon="users" href="./get-cohort">
    Retrieve a cohort by its cohort ID.
  </Card>

  <Card title="Retrieve all cohorts" icon="users" href="./get-cohorts">
    Retrieve all cohorts for your workspace.
  </Card>

  <Card title="Update a cohort" icon="users" href="./update-cohort">
    Update a cohort by its cohort ID.
  </Card>

  <Card title="Delete a cohort" icon="users" href="./delete-cohort">
    Delete a cohort by its cohort ID.
  </Card>
</CardGroup>