---
title: "Create a new evidence item under a product in the authenticated workspace."
method: POST
path: "/api/v1/evidence"
tags: ["evidence"]
---

# Create a new evidence item under a product in the authenticated workspace.

`POST /api/v1/evidence`

Billing-gated: a 403 with body { error:'plan_limit_reached', metric:'evidence_items', current, limit, plan } is returned when the evidence_items quota is hit (distinct from the scope 403 which has body { error: 'Insufficient permissions...' }). Row stored with status='active', triage_status='inbox', created_by=auth.userId. Fires a Slack notify + PostHog evidence_created event (fire-and-forget). linkedIntentIds is [] on a fresh create.

## Query parameters

- `workspace_id` string

## Request body

- object
  - `content` string, required — Non-empty evidence text; trimmed before storage.
  - `type` string, required — One of friction | quote | observation | metric | request.
  - `productId` string, required — Product must belong to the workspace (else 404).
  - `source` string — Free-text source label; stored as null if omitted.
  - `sourceUrl` string — Source URL; stored as null if omitted.
  - `severity` string — low | medium | high | critical. 400 if invalid.
  - `sentiment` string — positive | negative | neutral | mixed. 400 if invalid.
  - `tags` string[] — Tag array; defaults to [].
  - `stage` string — Free-text journey stage; stored as null if omitted.

## Response `201`

Evidence created.

- object

## Other responses

- `400` — Missing/empty content, missing/invalid type, missing productId, or invalid severity/sentiment.
- `401` — Missing/invalid API key or no valid session cookie.
- `403` — API key lacks write scope; cookie auth not a workspace member; OR billing limit reached (body { error: 'plan_limit_reached', metric: 'evidence_items', current, limit, plan }).
- `404` — productId not found in this workspace.
- `429` — Rate limit exceeded (general bucket, 300/h).
- `500` — DB or internal error.

## Changes

- **2026-08-23** `155c812b368b` — 6 info
  - added the optional property `details` to the response with the `400` status
  - added the optional property `details` to the response with the `401` status
  - added the optional property `details` to the response with the `403` status
  - added the optional property `details` to the response with the `404` status
  - …2 more

[Change history](https://skmtc.dev/pathmode/apis/pathmode-api/changes/api/v1/evidence/post.md)

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pathmode/pathmode-api/revisions/e419abb0a327/schema)