Read your audit trail

Read · GET /v1/tenants/{tenant}/audit · MCP tool audit

Lists every action recorded for your tenant, oldest first: submissions, builds, signatures, checks and installations. The answer also says whether the trail is intact. Add submission to see the records of one submission only.

Roles that can call it: viewer, builder, deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
`submission`	query	no	Optional: show only the records of this submission

Returns

A JSON object with these keys: tenant, records, chain, guarantee, caller_authenticated.

Example request

curl 'https://api.tarsana.io/v1/tenants/acme/audit?submission=sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1' \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme'

Example response

{
  "tenant": "acme",
  "records": [
    {
      "seq": 1,
      "action": "submit",
      "outcome": "ok",
      "summary": "the spec was admitted and recorded",
      "submission": "sha256:cdff0629...",
      "recorded_at": "2026-10-05T02:15:39.523210Z",
      "hash": "sha256:32dca838...",
      "prev": "sha256:0689405a..."
    }
  ],
  "chain": {
    "verified": true,
    "records": 1,
    "head": "sha256:32dca838...",
    "problems": []
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`audit_unavailable`	503	Your audit trail could not be written or read. If you made a change, it was carried out but is missing from the trail, so contact Tarsana support.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown