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

> Retrieve contextual cohort targeting values for ad server integration.

## Overview

The Contextual API enables retrieval of contextual cohort targeting values without processing user data. Use it to pass targeting values to ad servers like Google Ad Manager.

This API is designed to work independently of the main Permutive SDK, allowing you to retrieve contextual targeting even when user consent is not available.

<Note>
  If you don't need to target unconsented users with your contextual signals, the Permutive SDK will call these endpoints and segment contextual cohorts automatically.
</Note>

## Base URL

```
https://api.permutive.com/ctx/v1
```

## Authentication

The API uses API key authentication. Pass your Permutive API key as a query parameter:

```
?k=YOUR_API_KEY
```

This is the same API key used for your main Permutive SDK deployment.

## Use Cases

* **Privacy-safe contextual targeting**: Target ads based on page content without user identifiers
* **Cookie-less advertising**: Enable ad targeting in environments where cookies are blocked or unavailable
* **Server-side targeting value retrieval**: Fetch targeting values for integration with any ad server
* **Consent-free operation**: Retrieve targeting values without requiring user consent for personal data processing

## Available Endpoints

| Endpoint   | Method | Description                                                          |
| ---------- | ------ | -------------------------------------------------------------------- |
| `/segment` | POST   | Retrieve contextual cohort codes for a given URL and page properties |

## Response Format

All responses are returned in JSON format. Successful responses include cohort codes and activation mappings. The endpoint also returns content classification data if any classification provider is enabled in the account.

```json theme={"dark"}
{
  "cohorts": ["abc", "def", "ghi"],
  "activations": {
    "target_dfp": ["abc", "def"],
    "appnexus_adserver": ["ghi"]
  },
  "contextual_data": {
    "classifications": {
      "categories": [
        {
          "value": "155",
          "confidence": 0.5,
          "taxonomy": "iab_3.0",
          "provider": "ibm_watson"
        }
      ],
      "keywords": [
        {
          "value": "museum",
          "confidence": 0.7,
          "provider": "ibm_watson"
        }
      ],
      "entities": [
        {
          "value": "British Museum",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "sentiment": [
        {
          "value": "positive",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "emotion": [
        {
          "value": "joy",
          "confidence": 0.4,
          "provider": "ibm_watson"
        }
      ],
      "concepts": [
        {
          "value": "Vincent van Gogh",
          "confidence": 0.6,
          "provider": "ibm_watson"
        }
      ]
    }
  }
}
```

## Error Handling

The API returns standard HTTP status codes:

| Status Code | Description                                      |
| ----------- | ------------------------------------------------ |
| `200`       | Success                                          |
| `400`       | Bad Request - Invalid request body or parameters |
| `401`       | Unauthorized - Invalid or missing API key        |
| `500`       | Internal Server Error                            |

## Rate Limits

Contact your Customer Success Manager for information about rate limits applicable to your account.

## Next Steps

<Card title="Get Contextual Segments" href="./segment" icon="code">
  Learn how to retrieve contextual cohort codes using the segment endpoint.
</Card>