> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

Manage your Buyer Personas programmatically using the 1eye API. Create, retrieve, update, and delete Personas to define the people and decision-makers you want to reach within your ideal customer companies.

Personas are a core component of the 1eye Knowledge Base. While ICPs define the companies you want to target, Personas define the people within those companies who are most relevant to your business.

1eye uses Personas to evaluate Buyer fit, identify relevant decision-makers, and match Buyers to your targeting criteria.

Changes made through the API are automatically reflected in the 1eye Console, and vice versa.

## Base URL

All Persona API requests use:

```text theme={null}
https://api.1eye.ai/v1/kb/personas
```

## Authentication

All endpoints require a valid 1eye API key.

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

API keys are scoped to a single workspace. All operations automatically apply to the workspace associated with your API key.

You do not need to provide a workspace ID.

The examples below use `$API_KEY` as the environment variable containing your API key.

For more information, see [Authentication](/api-reference/auth).

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/kb/personas` | List Personas |
| `GET` | `/v1/kb/personas/{persona_id}` | Retrieve a Persona |
| `POST` | `/v1/kb/personas` | Create a Persona |
| `PATCH` | `/v1/kb/personas/{persona_id}` | Update a Persona |
| `DELETE` | `/v1/kb/personas/{persona_id}` | Delete a Persona |

All endpoints return JSON responses, except DELETE, which returns no response body.

***

## Persona Object

A Persona defines the types of people who are most likely to influence, evaluate, or purchase your products and services.

Personas typically describe a buyer's role, responsibilities, seniority, business challenges, and purchasing priorities.

For example, Snowbricks, a fictional cloud data and AI platform, might target VPs of Data Engineering, Heads of Analytics, and Chief Data Officers at companies investing in modern data infrastructure.

### Fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Full name of the Persona |
| `short_name` | string | Unique short identifier for the Persona |
| `description` | string | Detailed Persona definition, including roles, responsibilities, seniority, challenges, and buying priorities |

### Example Persona

```json theme={null}
{
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads."
}
```

### System-Managed Fields

1eye automatically generates and maintains additional fields.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique Persona identifier |
| `client_id` | string | Workspace identifier |
| `created_by` | object | Information about who created the Persona |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last modification timestamp |

These fields are read-only and cannot be modified through Create or Update requests.

Persona identifiers use the `per_` prefix.

Example:

```text theme={null}
per_363250364328685568
```

***

## 1. List Personas

`GET /v1/kb/personas`

Retrieve a paginated list of Personas configured in your workspace.

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | No | Maximum number of Personas to return. Default: 100. Maximum: 1,000 |
| `cursor` | string | No | Pagination cursor returned by a previous request |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/personas?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "per_363250364328685568",
      "client_id": "wor_123456789012345678",
      "name": "VP of Data Engineering",
      "short_name": "vp-data-engineering",
      "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    },
    {
      "id": "per_363250364328685569",
      "client_id": "wor_123456789012345678",
      "name": "Head of Analytics",
      "short_name": "head-of-analytics",
      "description": "Analytics leaders responsible for business intelligence, reporting, data accessibility, and analytics strategy. Common titles include Head of Analytics, VP of Analytics, Director of Business Intelligence, and Head of Data Analytics. These leaders prioritize faster insights, reliable reporting, scalable analytical workloads, and reducing dependence on fragmented data tools.",
      "created_at": "2026-10-18T18:05:00Z",
      "updated_at": "2026-10-18T18:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

### Pagination

List Personas uses cursor-based pagination.

When additional results are available, `pagination.next_cursor` contains a continuation token.

Pass this token using the `cursor` parameter to retrieve the next page.

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/personas?limit=100&cursor=YOUR_CURSOR" \
  -H "Authorization: Bearer $API_KEY"
```

When `next_cursor` is `null`, there are no additional results.

For more information, see [Pagination](/api-reference/pagination).

### Behavior

* Returns Personas belonging to the authenticated workspace.
* Excludes soft-deleted Personas.
* Supports cursor-based pagination.
* Returns an empty `data` array when no Personas exist.
* Does not return Personas belonging to other workspaces.

***

## 2. Retrieve a Persona

`GET /v1/kb/personas/{persona_id}`

Retrieve a specific Persona using its unique identifier.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `persona_id` | string | Yes | Unique identifier of the Persona |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/personas/per_363250364328685568" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

* Returns the complete Persona record.
* Includes system-generated metadata.
* The Persona must belong to the authenticated workspace.
* Returns `404 Not Found` if the Persona does not exist, has been deleted, or belongs to another workspace.

***

## 3. Create a Persona

`POST /v1/kb/personas`

Create a new Buyer Persona in your workspace.

New Personas become available for future Buyer evaluations and matching.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Full Persona name |
| `short_name` | string | Yes | Unique short identifier |
| `description` | string | Yes | Detailed Persona definition |

### Example Request

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/kb/personas" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VP of Data Engineering",
    "short_name": "vp-data-engineering",
    "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads."
  }'
```

### Example Response

**201 Created**

```json theme={null}
{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

When a Persona is created:

1. 1eye generates a unique Persona ID.
2. The Persona is associated with your workspace.
3. The Persona becomes visible in the Knowledge Base.
4. The Persona becomes available for future Buyer evaluations.
5. The Persona can immediately be retrieved or updated through the API.

**Important:** Creating a Persona does not automatically reevaluate existing Buyers.

The new Persona is used during subsequent Buyer evaluations.

### Validation

* `name` must not be empty.
* `short_name` must not be empty.
* `description` must not be empty.
* `short_name` must be unique among active Personas in the workspace.
* System-managed fields cannot be supplied in the request.

***

## 4. Update a Persona

`PATCH /v1/kb/personas/{persona_id}`

Update an existing Persona using its unique identifier.

The API supports partial updates. You only need to provide the fields you want to change.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `persona_id` | string | Yes | Unique identifier of the Persona |

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Updated Persona name |
| `short_name` | string | No | Updated short identifier |
| `description` | string | No | Updated Persona definition |

At least one editable field must be supplied.

### Example Request

Update the Persona description to include additional technical and business responsibilities.

```bash theme={null}
curl -X PATCH "https://api.1eye.ai/v1/kb/personas/per_363250364328685568" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "VPs and Heads of Data Engineering at mid-market and enterprise organizations responsible for cloud data infrastructure, data platform architecture, and engineering teams. These leaders manage data pipelines, ETL/ELT workloads, lakehouse environments, data warehouses, and infrastructure supporting AI applications. They typically own or influence data platform budgets, vendor evaluations, and infrastructure modernization initiatives. Strong buying triggers include warehouse migrations, rising compute costs, real-time data requirements, platform consolidation, and initiatives to deploy generative AI and machine learning at scale."
  }'
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "VPs and Heads of Data Engineering at mid-market and enterprise organizations responsible for cloud data infrastructure, data platform architecture, and engineering teams. These leaders manage data pipelines, ETL/ELT workloads, lakehouse environments, data warehouses, and infrastructure supporting AI applications. They typically own or influence data platform budgets, vendor evaluations, and infrastructure modernization initiatives. Strong buying triggers include warehouse migrations, rising compute costs, real-time data requirements, platform consolidation, and initiatives to deploy generative AI and machine learning at scale.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}
```

### Partial Updates

Only the fields supplied in the request are updated.

For example:

```json theme={null}
{
  "name": "Head of Data Engineering"
}
```

Updates the Persona name without modifying its `short_name` or `description`.

### Behavior

* Updates the existing Persona.
* Preserves fields not included in the request.
* Preserves the original Persona ID.
* Updates the modification timestamp.
* Reflects changes in the 1eye Console.
* Uses the updated Persona definition for future Buyer evaluations.

**Important:** Updating a Persona does not automatically trigger historical Buyer reevaluation.

Existing Buyer evaluation results remain unchanged until they are reevaluated through the normal 1eye processing pipeline.

***

## 5. Delete a Persona

`DELETE /v1/kb/personas/{persona_id}`

Delete a Persona from your workspace.

Deleting a Persona performs a **soft delete**. The Persona is removed from active use but is not permanently erased from 1eye.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `persona_id` | string | Yes | Unique identifier of the Persona |

### Example Request

```bash theme={null}
curl -X DELETE "https://api.1eye.ai/v1/kb/personas/per_363250364328685568" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

**204 No Content**

The response body is empty.

### What Happens When a Persona Is Deleted?

* The Persona is removed from the active Knowledge Base.
* The Persona no longer appears in List Personas results.
* Retrieving the deleted Persona returns `404 Not Found`.
* The Persona is excluded from future Buyer evaluations.
* The deleted Persona is removed from active Buyer Persona associations.
* Historical Persona information is preserved internally.

### Impact on Existing Buyers

Deleting a Persona does not delete Buyers previously associated with that Persona.

For example, Snowbricks might have identified a Buyer matching the VP of Data Engineering Persona.

**Before deletion:**

```text theme={null}
Buyer: Jane Doe
Company: Acme Analytics
Title: VP of Data Engineering

Matched Persona:
- VP of Data Engineering
```

**After deleting VP of Data Engineering:**

```text theme={null}
Buyer: Jane Doe
Company: Acme Analytics
Title: VP of Data Engineering

Matched Persona:
- No active Persona match
```

The Buyer remains in 1eye, including their contact information, company information, and historical Signals.

Only the deleted Persona association is removed from active matching results.

### Important Considerations

Deleting a Persona does not:

* Delete Buyers.
* Delete Signals.
* Delete associated companies.
* Permanently erase historical evaluations.
* Delete previously synchronized CRM contacts.
* Automatically trigger new Buyer evaluations.

**Restoring deleted Personas is not currently exposed through the public API.**

***

## 6. Error Handling

All Persona endpoints use the standard 1eye API error format.

| HTTP Status | Description |
| - | - |
| `200` | Successful retrieval or update |
| `201` | Persona created successfully |
| `204` | Persona deleted successfully |
| `400` | Invalid request or missing required fields |
| `401` | Invalid or missing API key |
| `403` | Insufficient permissions |
| `404` | Persona not found or inaccessible |
| `409` | Duplicate or conflicting Persona |
| `429` | Workspace rate limit exceeded |
| `500` | Internal server error |

### Example Error

Attempting to retrieve a Persona that does not exist:

**404 Not Found**

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Persona not found.",
    "request_id": "req_359051753366339585"
  }
}
```

### Validation Errors

Invalid requests return an error identifying the issue.

Examples include:

* Missing Persona name.
* Missing short name.
* Empty description.
* Duplicate short name.
* Invalid Persona ID.
* Attempting to modify system-managed fields.

For more information, see [Errors](/api-reference/errors).

***

## 7. Pagination & Rate Limits

### Pagination

List Personas supports the existing 1eye cursor-based pagination mechanism.

* Default page size: 100.
* Maximum page size: 1,000.
* Use `cursor` to retrieve subsequent pages.
* A `null` next cursor indicates the end of the collection.

See [Pagination](/api-reference/pagination).

### Rate Limits

Persona API requests count toward your workspace's API rate limits.

Rate limits are shared across all API keys belonging to the same workspace.

If a limit is exceeded, the API returns:

**429 Too Many Requests**

Follow the `Retry-After` header when provided.

See [Rate Limits](/api-reference/rate-limits).

***

## 8. How Personas Affect Buyer Intelligence

Personas help 1eye determine which people within your target companies are most relevant to your products and GTM strategy.

The Knowledge Base is used by the REEM pipeline:

**Resolve → Enrich → Evaluate → Match**

### ICPs vs. Personas

| Knowledge Base Resource | Purpose |
| - | - |
| ICPs | Define the types of companies you want to target |
| Personas | Define the people and decision-makers you want to reach within those companies |

For example, Snowbricks might have:

**ICP:** Cloud-Native SaaS Companies

**Persona:** VP of Data Engineering

1eye evaluates company fit against the ICP and contact fit against the Persona.

Together, these configurations help identify Buyers who are relevant to Snowbricks' go-to-market strategy.

### Impact of Persona Changes

| Operation | Impact |
| - | - |
| Create | New Persona becomes available for future Buyer evaluations |
| Update | Updated Persona definition is used for future evaluations |
| Delete | Persona is removed from active matching and future evaluations |

### Existing Buyer Evaluations

Creating or updating a Persona does not automatically reevaluate existing Buyers.

Existing evaluations are preserved until the normal REEM pipeline processes them again.

### Deleting a Persona

Deleting a Persona removes its active Buyer associations without deleting underlying Buyer records or historical Signals.

### Console Synchronization

All changes are reflected in the 1eye Console.

* Personas created through the API appear in the Console.
* Console updates are reflected in API responses.
* Deleted Personas no longer appear in active Knowledge Base views.

The API and Console operate on the same underlying Knowledge Base.

***

## 9. Best Practices

### Use Role-Based Persona Names

Choose names that clearly identify the decision-maker or buyer segment.

For Snowbricks, examples include:

* VP of Data Engineering
* Head of Analytics
* Chief Data Officer
* Director of Data Platform
* Head of Machine Learning

### Use Consistent Short Names

Short names should be concise, descriptive, and unique within your workspace.

Examples:

```text theme={null}
vp-data-engineering
head-of-analytics
chief-data-officer
director-data-platform
head-machine-learning
```

### Write Detailed Persona Descriptions

Persona descriptions should explain who the buyer is, what they are responsible for, and why they are relevant to your product.

Useful information includes:

* Common job titles.
* Department or business function.
* Seniority level.
* Primary responsibilities.
* Technology ownership.
* Budget and purchasing authority.
* Business challenges.
* Buying priorities.
* Relevant evaluation or purchasing triggers.

For example, Snowbricks might target engineering leaders responsible for modernizing data infrastructure, reducing cloud data costs, and supporting AI workloads.

### Include Related Job Titles

A Persona should represent a meaningful buyer segment, not necessarily one exact job title.

For example, a VP of Data Engineering Persona may include:

* VP of Data Engineering
* Head of Data Engineering
* Director of Data Engineering
* Director of Data Platform

This helps 1eye evaluate Buyers with different titles but similar responsibilities.

### Focus on Responsibilities, Not Just Titles

Two Buyers may have different job titles but perform similar roles.

Descriptions that include responsibilities, business challenges, and purchasing priorities provide stronger context for Persona matching than job titles alone.

### Use PATCH for Updates

Update only the fields that need to change.

Avoid replacing complete Persona definitions when a partial update is sufficient.

### Delete Carefully

Deleting a Persona removes it from active Buyer matching.

Before deleting a Persona, consider how it is currently used across Buyer Intelligence and your GTM workflows.

***

## 10. Related Documentation

* [Authentication](/api-reference/auth)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Buyers](/api-reference/list-buyers)
* [Knowledge Base – Personas](/knowledge-base/personas)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.