---
title: "Signal evidence API reference"
canonical_url: https://zentrik.ai/docs/api/signal-evidence
markdown_url: https://zentrik.ai/docs/api/signal-evidence.md
last_reviewed: 2026-09-10
---

# Signal evidence API reference

Read exact evidence and record what delivered work addressed. Request signal-evidence:read and signal-evidence:write separately.

- Human reference: https://zentrik.ai/docs/api/signal-evidence
- 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/signal-evidence — List evidence records

Operation ID: `list-signal-evidence`

Filter evidence by type, category and source Signal account. Filters combine with AND before pagination and counting. Each record includes evidenceType and compact accounts linked to its source Signal. Active visibility excludes completed and not-relevant records; visibility=all includes both. Use the Ideas evidence endpoint to read an Idea’s direct evidence links. List responses are arrays with X-Total-Count, X-Limit, X-Offset and X-Has-More headers. Continue until X-Has-More is false; concurrent edits can shift offset pages.

Required API key scopes: `signal-evidence:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size, 1–100. Default 20. |
| `offset` | integer | No | Matching rows to skip. Default 0. |
| `signalId` | uuid | No | Filter by source Signal. |
| `evidenceType` | string | No | Exact, case-sensitive stored type, such as need, friction or product_feedback; up to 48 characters. |
| `category` | string | No | Exact, case-sensitive category label, such as Product bug or Product request; up to 120 characters. |
| `accountId` | uuid | No | Account linked to the source Signal. Resolve the UUID with GET /external/v1/accounts. Evidence without a source account does not match; unknown or other-workspace accounts return an empty list. |
| `visibility` | enum | No | active (default) or all. |
| `q` | string | No | Search title, description, excerpt and category; up to 200 characters. |

### Example request

```http
GET /external/v1/signal-evidence?evidenceType=product_feedback&category=Product%20bug&accountId=44444444-4444-4444-8444-444444444444&limit=20
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The requested data is returned. | — |
| 400 | Invalid request | Invalid ID, unsupported field, empty patch, or invalid value. | — |
| 403 | Missing scope | The key does not grant the required resource scope. | — |
| 404 | Not found | The addressed record or assignment is outside this workspace or team. | — |

### Example response

```json
[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "title": "Export duplicates rows",
    "description": "Retrying the export adds a second copy.",
    "extracts": null,
    "category": "Product bug",
    "evidenceType": "product_feedback",
    "signalId": "55555555-5555-4555-8555-555555555555",
    "accounts": [
      {
        "id": "44444444-4444-4444-8444-444444444444",
        "name": "Acme"
      }
    ],
    "resolvedAt": null,
    "resolution": null,
    "resolvedByUserId": null,
    "dismissedAt": null
  }
]
```

---

## GET /external/v1/signal-evidence/:id — Get an evidence record

Operation ID: `get-signal-evidence`

Read one exact evidence record, including completed or not-relevant evidence. signalId identifies its source Signal.

Required API key scopes: `signal-evidence:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | Record UUID in the path. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The requested data is returned. | — |
| 400 | Invalid request | Invalid ID, unsupported field, empty patch, or invalid value. | — |
| 403 | Missing scope | The key does not grant the required resource scope. | — |
| 404 | Not found | The addressed record or assignment is outside this workspace or team. | — |

### Example response

```json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "title": "Export duplicates rows",
  "description": "Retrying the export adds a second copy.",
  "extracts": null,
  "category": "Product bug",
  "signalId": null,
  "resolvedAt": null,
  "resolution": null,
  "resolvedByUserId": null,
  "dismissedAt": null
}
```

---

## PATCH /external/v1/signal-evidence/:id/resolution — Resolve or reopen evidence

Operation ID: `set-signal-evidence-resolution`

Mark one selected evidence record acted on, or reopen it. Bugs become fixed, requests implemented, and other categories addressed. Completion is independent of relevance; not-relevant evidence cannot be completed. Repeated writes preserve the original completion timestamp. The decision survives source reprocessing. API-key writes have resolvedByUserId:null and are attributed to the key in the API audit; they never impersonate its creator. New reports and other linked records are unaffected.

Required API key scopes: `signal-evidence:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | Record UUID in the path. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolved` | boolean | Yes | true completes the record; false reopens it. Strings are rejected. |

### Example request

```json
{
  "resolved": true
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The saved record is returned. | — |
| 400 | Invalid request | Invalid ID, unsupported field, empty patch, or invalid value. | — |
| 403 | Missing scope | The key does not grant the required resource scope. | — |
| 404 | Not found | The addressed record or assignment is outside this workspace or team. | — |
| 409 | Conflict | The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear. | — |

### Example response

```json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "resolvedAt": "2026-09-10T10:00:00Z",
  "resolution": "fixed",
  "resolvedByUserId": null,
  "dismissedAt": null
}
```