---
title: "Audit trail · intentic sandbox API"
description: "The tamper-evident record of who did what, its check, its export and its outside copy. Every route in the audit trail group of the intentic sandbox API."
url: "https://intentic.dev/api/audit/"
---

The sandbox itself

# Audit trail

The tamper-evident record of who did what, its check, its export and its outside copy

**On this page (4 sections)**

- [The audit trail](#audit-list)
- [Check the audit trail for tampering](#audit-verify)
- [Download the audit trail for a period](#audit-export)
- [Whether the audit trail's outside copy keeps up](#audit-status)

Reading the trail, checking that no entry was changed or removed since it was written, downloading a period of it, and whether the copy kept outside this sandbox is keeping up.

**GET`/audit` The audit trail**

Who changed a setting, a member, a secret's gate or a policy, who signed in, and, when reads are recorded, who opened what. Newest first, filtered and paged. Reading it is itself recorded when reads are.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `from` Only records written at or after… | number | query |
| `to` Only records written before this time,… | number | query |
| `action` Only actions starting with this, such… | string | query |
| `actor` Only records whose actor's address, token… | string | query |
| `target` Only records whose target contains this | string | query |
| `before` Paging cursor: only records written before… | number | query |
| `limit` How many records to return | integer | query |

### What comes back

| Field | Type |
| --- | --- |
| `records` The records, newest first | object[] |
| `actor` | object |
| `when kind is "member"` | shape |
| `email` The address they signed in with,… | string |
| `role` Their tier at the moment they… | string |
| `when kind is "token"` | shape |
| `id` The control token's id | string |
| `label` The name its owner gave the… | string |
| `when kind is "agent"` | shape |
| `conversationId` The conversation whose agent did it | string |
| `when kind is "system"` | shape |
| `reason` What part of the sandbox acted,… | string |
| `action` What happened, as a dotted name:… | string |
| `target` What it happened to: a member's… | string |
| `outcome` How it ended | "ok" | "refused" | "failed" |
| `details` A few facts that make the… | object |
| `v` The record format | 1 |
| `id` The record's own id | string |
| `at` When it was written, in milliseconds… | number |
| `prevHash` The hash of the record before… | string |
| `hash` SHA-256, in hex, over this record's… | string |
| `next` The cursor for the next, older… | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/audit" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.audit.list();
```

**GET`/audit/verify` Check the audit trail for tampering**

Recomputes every record's hash and its link to the one before it. Names the first record that was changed, removed or inserted after it was written. It shows tampering; it cannot undo it, which is what the copy sent to a forward address is for.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `ok` Whether every record kept is intact… | boolean |
| `checked` How many records were checked | number |
| `segments` How many monthly files were checked | number |
| `prunedThrough` Where the kept chain starts: the… | object |
| `at` | number |
| `hash` | string |
| `broken` The first record that does not… | object |
| `segment` The monthly file it is in | string |
| `line` Its line number in that file,… | number |
| `id` The record's id, when the line… | string |
| `at` When the record says it was… | number |
| `reason` unreadable: the line is not a… | "unreadable" | "hash-mismatch" | "chain-break" |
| `torn` Whether the newest file ends in… | boolean |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/audit/verify" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.audit.verify();
```

**GET`/audit/export` Download the audit trail for a period**

The records written in a period as JSON Lines, exactly as stored, so whoever receives them can check the hashes themselves.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `from` required The first moment to include, in… | number | query |
| `to` required The moment to stop before, in… | number | query |

### What comes back

| Field | Type |
| --- | --- |
| `filename` A file name to save it… | string |
| `jsonl` The records, one JSON object per… | string |
| `count` How many records it holds | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/audit/export?from=1&to=1" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.audit.export({
 "from": "1",
 "to": "1"
});
```

**GET`/audit/status` Whether the audit trail's outside copy keeps up**

Which monthly files are kept, the oldest record, and whether records are reaching the forward address.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `forwarding` Absent while no forward address is… | object |
| `url` Where records are sent | string |
| `pending` How many records are waiting to… | number |
| `lastSentAt` When the last record reached it | number |
| `lastError` Why the last attempt failed, when… | string |
| `nextAttemptAt` When the next attempt is due,… | number |
| `oldestAt` When the oldest record kept was… | number |
| `segments` The monthly files kept, oldest first | string[] |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/audit/status" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.audit.status();
```

More in The sandbox itself

[Previous ← Activity](https://intentic.dev/api/activity/)[Next Data protection →](https://intentic.dev/api/compliance/)