---
title: "Post Evidence"
method: POST
path: "/evidence"
tags: ["evidence"]
---

# Post Evidence

`POST /evidence`

## Request

- Base URL: `https://app.tascan.io/api/v1`
- URL: `https://app.tascan.io/api/v1/evidence`
- Auth: HTTP bearer

Post one evidence event into the evidence ledger (protocol v0.2 V9a, POST /evidence): an actor did an action to an object at a point in time, optionally with a location and provenance. idempotency_key is required — the same (org, idempotency_key) always returns the same row, never a second insert. Optionally correlate the event to a task or task list. Write tier; a device credential (structurally different from an API key) is not reachable through this MCP connection, so device_id is never set here.

## Request body

- object
  - `actor` object, required: Who did it.
    - `kind` 'worker' | 'agent' | 'device', required: worker requires an active, unmerged worker id in your organization; agent/device ids are recorded as given.
    - `id` string, required: The actor's id.
  - `action` string, required: What happened, e.g. inspected, scanned, calibrated.
  - `object` object, required: What it happened to.
    - `kind` 'asset' | 'tag' | 'serial' | 'url', required: What kind of thing object.ref names.
    - `ref` string, required: The object reference (asset id, tag id, serial number, or URL).
  - `occurred_at` string, required: ISO timestamp for when the event actually happened.
  - `location` object: Optional location.
    - `zone_id` string: Optional geofence zone UUID.
    - `lat` number
    - `lng` number
  - `provenance` object: Optional provenance object. provenance.kind first_party_scan is written only by the scan_events trigger and is refused from a caller; provenance.signature triggers device-signature verification.
  - `correlation` object: Optional correlation hint.
    - `task_id` string: A task UUID in your organization to correlate this evidence to.
    - `task_list_id` string: A task list UUID in your organization to correlate this evidence to (used when task_id is absent or does not resolve).
  - `idempotency_key` string, required: Required, 1-200 chars. The same key on the same org replays the same stored row.

## Response `200`

Success. JSON body: { data: ... } or an error object { error, message }.

## Other responses

- `4XX`: Client error (validation, auth, scope, rate limit).

---

[API](https://skmtc.dev/tascan/apis/tascan-api.md) · [All operations](https://skmtc.dev/tascan/apis/tascan-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tascan/apis/tascan-api/revisions/56fcd2861498?raw)