Reference

API reference

One public endpoint does the recording. Everything else — the timeline, integrity, agents — lives in your Vault dashboard behind your login.

Authentication

Pass an ingest key as a Bearer token. Create and revoke keys in Settings.

http

Authorization: Bearer vk_live_YOUR_KEY

Keep keys server-side. A key is write access to your Vault; the full value is shown only once.

POST /api/ingest

Record one event, or a batch. Returns 201 with the sequence and hash of each recorded event.

Event fields

Field	Type	Required	Notes
`type`	string	yes	`know`, `did`, or `decision`.
`summary`	string	yes	Human-readable description of the event.
`agent`	string	no	Who produced it. Defaults to `default`.
`action`	string	no	Short verb/tool, e.g. `file.write`.
`status`	string	no	`ok`, `blocked`, or `flagged`.
`payload`	object	no	Arbitrary JSON detail, stored verbatim.

Single event

curl

curl -X POST https://vouchstone.dev/api/ingest \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent":"deploy-bot", "type":"did", "action":"db.migrate",
        "status":"ok", "summary":"applied migration to prod" }'

Batch

Send up to 100 events at once under an events array; they’re chained in order.

curl

curl -X POST https://vouchstone.dev/api/ingest \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": [
        { "type":"know", "summary":"recalled deploy target" },
        { "type":"did", "action":"deploy", "status":"ok", "summary":"shipped v4127" }
      ] }'

Response

201 Created

{ "ok": true, "recorded": [ { "seq": 4127, "type": "did", "hash": "9f2a1c…" } ] }

Errors

Status	Meaning
`401`	Missing or invalid ingest key.
`413`	Batch exceeds 100 events.
`422`	Invalid event — bad `type` or missing `summary`.

Errors return { "error": "message" }.