---
title: "Opportunities API reference"
canonical_url: https://zentrik.ai/docs/api/opportunities
markdown_url: https://zentrik.ai/docs/api/opportunities.md
last_reviewed: 2026-09-03
---

# Opportunities API reference

Opportunities help you bridge the gap between user problems (insights) and product solutions (ideas). Use these endpoints to organize and prioritize the problems worth solving.

- Human reference: https://zentrik.ai/docs/api/opportunities
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/opportunities — List opportunities

Operation ID: `list-opportunities`

Retrieve a bounded page of compact opportunities in your workspace. Opportunities represent significant problems, needs, or desired outcomes identified from insights. List responses use relation IDs/counts instead of hydrating every linked insight or idea.

Required API key scopes: `opportunities:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Maximum number of items to return (default: 20, maximum: 100) |
| `offset` | number | No | Number of items to skip (default: 0) |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/opportunities?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | List of opportunities retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers. | Array<Opportunity> |

### Example response

```json
[
  {
    "id": "uuid",
    "name": "Streamline checkout process",
    "description": "High drop-off rate at the final step...",
    "status": "Draft",
    "insightIds": [
      "insight-uuid"
    ],
    "ideaIds": []
  }
]
```

---

## GET /external/v1/opportunities/:id — Get one opportunity

Operation ID: `get-opportunity`

Retrieve detailed information about a specific opportunity.

Required API key scopes: `opportunities:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier of the opportunity |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success |  | Opportunity |

### Example response

```json
{
  "id": "uuid",
  "name": "Streamline checkout process"
}
```

---

## POST /external/v1/opportunities — Create an opportunity

Operation ID: `create-opportunity`

Define a new opportunity identified from your discovery efforts.

Required API key scopes: `opportunities:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Title of the opportunity |
| `description` | string | Yes | Detailed problem statement |
| `score` | number | No | Opportunity score (0-100) |

### Example request

```json
{
  "name": "Reduce churn in Mobile App",
  "description": "Users are uninstalling after 2 days...",
  "score": 92
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The opportunity was successfully created. | Opportunity |

### Example response

```json
{
  "id": "uuid",
  "name": "Reduce churn in Mobile App"
}
```

---

## PATCH /external/v1/opportunities/:id — Update an opportunity

Operation ID: `update-opportunity`

Modify an existing opportunity.

Required API key scopes: `opportunities:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier of the opportunity |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Updated title |
| `score` | number | No | Updated score |

### Example request

```curl
curl -X PATCH https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"score": 95}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated |  | Opportunity |

---

## DELETE /external/v1/opportunities/:id — Delete an opportunity

Operation ID: `delete-opportunity`

Permanently remove an opportunity.

Required API key scopes: `opportunities:delete`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier |

### Example request

```curl
curl -X DELETE https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success |  | — |