Signal evidence

Read exact evidence and record what delivered work addressed. Keys with signals:read can read source-linked evidence; signal-evidence:read is needed for its connections, signal-evidence:curate creates or corrects claims and connections, and signal-evidence:write resolves or reopens them.

7 endpoints

GET

List evidence records

GET /external/v1/signal-evidence

Filter evidence by type, category and source Signal account. Keys granted signals:read can list evidence too. Filters combine with AND before pagination and counting. Each record includes its UUID as id, a stable workspace-scoped publicId such as EVIDENCE-123, 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.

Requirements

API scopes required:

signal-evidence:read

Request

Parameters

Name	Type	Description
limit	integer	Page size, 1–100. Default 20.
offset	integer	Matching rows to skip. Default 0.
signalId	uuid	Filter by source Signal.
evidenceType	string	Exact, case-sensitive stored type, such as need, friction or product_feedback; up to 48 characters.
category	string	Exact, case-sensitive category label, such as Product bug or Product request; up to 120 characters.
accountId	uuid	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	active (default) or all.
q	string	Search public ID, title, description, excerpt and category; up to 200 characters.

Responses

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 Request

GET

/external/v1/signal-evidence

http

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

Example Response

200 OK

json

[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "publicId": "EVIDENCE-123",
    "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

Get an evidence record

GET /external/v1/signal-evidence/:id

Read one exact evidence record, including completed or not-relevant evidence. Use either the UUID or EVIDENCE-n ID from the Evidence sidebar. publicId is stable within the workspace; signalId identifies its source Signal. Keys granted signals:read can read evidence too.

Requirements

API scopes required:

signal-evidence:read

Request

Parameters

Name	Type	Description
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.

Responses

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

200 OK

json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "publicId": "EVIDENCE-123",
  "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
}

GET

List evidence connections

GET /external/v1/signal-evidence/:id/links

List every record one evidence claim is connected to, with the relationship role (supports, qualifies, contradicts or context) and origin (manual for a curated connection, automatic_relevance for one the router proposed). Read this before changing a connection so an existing role is not overwritten blindly. Insight connections that were previously removed are excluded. A connection alone does not mean the work addressed the claim. Connections name the linked records, so this route needs signal-evidence:read even for keys granted signals:read.

Requirements

API scopes required:

signal-evidence:read

Request

Parameters

Name	Type	Description
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.

Responses

200

Success

The claim's current connections are 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 record is not available in this workspace.

Example Response

200 OK

json

{
  "evidenceId": "7c1f...",
  "links": [
    {
      "targetType": "insight",
      "targetId": "4d2a...",
      "publicId": "INS-18",
      "name": "Export retries duplicate rows",
      "role": "supports",
      "origin": "manual",
      "confidence": null
    }
  ]
}

PATCH

Correct an evidence claim

PATCH /external/v1/signal-evidence/:id

Correct one evidence claim in a single save: title, description, exact source quote, category, productId or featureIds. Omitted fields stay unchanged; productId accepts null to clear the assignment. extracts must match one exact, continuous passage from the source Signal; pass null to clear it. This changes the reviewer-owned claim only. The source Signal, links and linked Insight wording are not changed. Not-relevant evidence cannot be corrected. The response confirms the database save; the search embedding refreshes in the background. To protect a field you read from a concurrent edit, pass its original value in expectedValues. The API returns 409 only when one of those fields changed and your patch would replace it. Repeating the same patch is safe.

Requirements

API scopes required:

signal-evidence:curate

Request

Parameters

Name	Type	Description
expectedValues	object	Original values for fields you read. A changed field returns 409 with the current record.
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.
title	string	3–500 characters.
description	string	Up to 10,000 characters. Send an empty string to remove inaccurate wording.
extracts	string \| null	One exact, continuous quote from the source Signal, preserving punctuation and spacing. Send null to clear it.
category	enum	Exact stored category, for example Product bug.
productId	uuid \| null	Assigned product, or null to clear it.
featureIds	uuid[]	At most 50 product features.

Responses

409

Conflict

A field in expectedValues changed since it was read. The response includes the current record and changed field names.

200

Success

The corrected 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 record is not available in this workspace.

Example Response

200 OK

json

{
  "id": "7c1f...",
  "title": "Export retries duplicate CRM rows",
  "category": "Product bug",
  "productId": null,
  "resolvedAt": null,
  "dismissedAt": null
}

PUT

Connect evidence to a record

PUT /external/v1/signal-evidence/:id/links/:targetType/:targetId

Connect one evidence claim to an insight, opportunity, idea or initiative with an explicit role, or change the role of an existing connection. The connection is recorded as manual, so automatic routing will not overwrite or remove it. Connecting a claim to an insight also adds that insight to the insightIds of the claim's source Signal. Repeating the same call is safe. Connect only claims the target record genuinely concerns; a connection is a research statement, not a delivery decision.

Requirements

API scopes required:

signal-evidence:curate

Request

Parameters

Name	Type	Description
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.
targetType *	enum	insight, opportunity, idea or initiative.
targetId *	uuid	Target record UUID in this workspace.
role	enum	supports (default), qualifies, contradicts or context.

Responses

200

Success

The saved connection 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 record is not available in this workspace.

Example Response

200 OK

json

{
  "evidenceId": "7c1f...",
  "targetId": "4d2a...",
  "targetType": "insight",
  "role": "supports"
}

DELETE

Remove an evidence connection

DELETE /external/v1/signal-evidence/:id/links/:targetType/:targetId

Remove one evidence connection. Removing an insight connection records a durable exclusion that automatic routing will not recreate, and rebuilds the insight from its remaining evidence. The insight stays in the source Signal's insightIds while another claim from that Signal still supports it, and leaves when the last one is removed. Opportunity, idea and initiative connections are removed outright, and automatic routing may propose them again later; this matches the behaviour of the same action in the app. Removing a connection does not dismiss, delete or complete the claim.

Requirements

API scopes required:

signal-evidence:curate

Request

Parameters

Name	Type	Description
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.
targetType *	enum	insight, opportunity, idea or initiative.
targetId *	uuid	Target record UUID in this workspace.

Responses

200

Success

The removal is confirmed.

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 record is not available in this workspace.

Example Response

200 OK

json

{
  "evidenceId": "7c1f...",
  "targetId": "4d2a...",
  "targetType": "insight",
  "linked": false
}

PATCH

Resolve or reopen evidence

PATCH /external/v1/signal-evidence/:id/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.

Requirements

API scopes required:

signal-evidence:write

Request

Parameters

Name	Type	Description
id *	string	Evidence UUID or workspace-scoped public ID, such as EVIDENCE-123.

Request body (application/json)

resolvedboolean

Required

true completes the record; false reopens it. Strings are rejected.

Responses

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 Request

PATCH

/external/v1/signal-evidence/:id/resolution

json

{
  "resolved": true
}

Example Response

200 OK

json

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