> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

> **Info**
>
> This Experience API is for Contentful Personalization use. If you are looking for the documentation for Studio, see the [Studio section](/experiences/overview).

## Overview

The Experience API is the core of Contentful Personalization. It returns profiles, JSON representations of visitors and their activity, in response to events. The Experience API is highly performant because of its deployment on the edge.

## Response envelope

All Experience API responses use a standard envelope:

**Success (200):**

```json
{
  "data": { ... },
  "error": null,
  "message": "ok"
}
```

**Error:**

```json
{
  "message": "<description>",
  "data": {},
  "error": {
    "code": "ERR_..."
  }
}
```

The `data` field contains the response payload on success. On error, `data` is an empty object and `error` contains a machine-readable error code.

## Error responses

All endpoints can return the following errors:

| HTTP | `error.code`                | Cause                                                                                                                                     |
| ---- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `ERR_INVALID_DATA`          | Request body or query parameters fail validation.                                                                                         |
| 404  | `ERR_CONFIG_NOT_FOUND`      | Organization or environment not found.                                                                                                    |
| 404  | `ERR_PROFILE_NOT_FOUND`     | Profile ID does not exist.                                                                                                                |
| 404  | `ERR_NAMESPACE_MISMATCH`    | Profile belongs to a different organization/environment.                                                                                  |
| 429  | `ERR_PROFILE_OVERLOAD`      | Too many concurrent requests to this profile's state. To resolve this issue, send events less frequently, e.g. by implementing a backoff. |
| 500  | `ERR_INTERNAL_SERVER_ERROR` | Unhandled server error.                                                                                                                   |