Pin provenance

Optional audit metadata on metadata.provenance. Agents and automations can attach run context when creating or updating pins; anyone with access to the pin can inspect it in the app (Run metadata on the pin).

Provenance is not part of pin_config — it lives on pin metadata so it stays separate from rendered content.

When to use

Link a pin back to a workflow run (run_id)
Point to a trace pin (trace_pin_id) for full agent spans
Record sources (URLs, files, queries, other pins)
Stamp who updated the pin (agent, automation, human)
Attach approval context after a human decision

Typical flow: automation PATCHes output pins with provenance after a run; users open Run metadata on the pin to verify what produced the data.

Endpoints

Provenance is accepted anywhere pin metadata is written:

Method	Path
`POST`	`/v1/pins`
`PUT`	`/v1/pins/:pinId`
`PATCH`	`/v1/pins/batch`
`POST`	`/api/pins/send` (dashboard API)
`PUT`	`/api/pins/:pid` (dashboard API)

Omit metadata.provenance to leave it unchanged. Send "provenance": null to clear.

Schema

Strict object — unknown keys are rejected.


{
  "run_id": "n8n-exec-abc123",
  "trace_pin_id": "p-trace456",
  "updated_by": "agent",
  "sources": [
    {
      "type": "url",
      "label": "Stripe docs",
      "ref": "https://docs.stripe.com/api/charges"
    },
    {
      "type": "pin",
      "label": "Source dataset",
      "ref": "p-source789"
    }
  ],
  "approval": {
    "item_id": "req-001",
    "resolved_by": "user@company.com",
    "resolved_at": "2026-06-23T10:15:00.000Z",
    "option_label": "Approve launch"
  }
}

Fields

Field	Type	Description
`run_id`	string	External run / execution id (max 128 chars)
`trace_pin_id`	string	Pin id of a `trace` pin (max 64 chars)
`updated_by`	`"agent"` \| `"automation"` \| `"human"`	Who last set provenance
`sources`	array	Up to 10 source references
`sources[].type`	`"url"` \| `"file"` \| `"pin"` \| `"query"`	Source kind
`sources[].label`	string	Optional display label (max 120 chars)
`sources[].ref`	string	URL, file path, pin id, or query text (max 512 chars)
`approval`	object	Optional human decision metadata
`approval.item_id`	string	Approval-queue item id (max 64 chars)
`approval.resolved_by`	string	Who resolved (max 128 chars)
`approval.resolved_at`	string	ISO timestamp (max 32 chars)
`approval.option_label`	string	Chosen option label (max 120 chars)

Sending {} is treated as clear (same as null).

Size limits

Limit	Value
Whole `provenance` object (serialized JSON)	4 KB max
`sources` array length	10 max

Oversized payloads return 400 with code PROVENANCE_LIMIT_EXCEEDED. Invalid shape returns PROVENANCE_INVALID.

Examples

Set on create


curl -X POST https://api.pindown.ai/v1/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_type": "stat-cards",
    "pin_config": {
      "cards": [
        { "title": "MRR", "value": "$124k", "change": "+8%", "trend": "up" }
      ]
    },
    "metadata": {
      "title": "Weekly MRR",
      "provenance": {
        "run_id": "wf-weekly-42",
        "updated_by": "automation",
        "sources": [
          { "type": "query", "label": "Stripe MRR", "ref": "SELECT sum(mrr) FROM subscriptions" }
        ]
      }
    }
  }'

Update / replace on existing pin

metadata.provenance is replaced when provided (not deep-merged).


curl -X PUT https://api.pindown.ai/v1/pins/p-abc123def456 \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "provenance": {
        "run_id": "wf-weekly-43",
        "trace_pin_id": "p-trace-xyz",
        "updated_by": "agent"
      }
    }
  }'

Clear provenance


{
  "metadata": {
    "provenance": null
  }
}

Batch update


{
  "updates": [
    {
      "id": "p-abc123",
      "metadata": {
        "provenance": {
          "run_id": "batch-run-1",
          "updated_by": "automation"
        }
      }
    }
  ]
}

Inspecting in the app

When metadata.provenance is present:

Hover the pin header → history icon → Run metadata
Or right-click the pin → Run metadata

The dialog shows run id, trace link, sources, approval summary, and raw JSON.

Error codes

Code	HTTP	Meaning
`PROVENANCE_INVALID`	400	Unknown keys, wrong types, or too many sources
`PROVENANCE_LIMIT_EXCEEDED`	400	Serialized provenance > 4 KB

Create a Pin — metadata fields on create
Update Pin — partial metadata updates
Pin Types & Schemas — trace pins for full run spans