> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Routes

> Audit trail for tool invocations.

<Snippet file="stub-warning.mdx" />

## Log audit entry

```
POST /api/audit
```

### Request body

```json theme={null}
{
  "id": "entry-001",
  "userId": "user-123",
  "roleId": "developer",
  "toolPath": "github.issues.create",
  "args": { "owner": "my-org", "repo": "my-repo", "title": "Bug fix" },
  "resultStatus": "success",
  "timestamp": "2025-01-15T12:00:00Z"
}
```

Validated against `AuditEntrySchema`:

| Field          | Type       | Required | Description                                      |
| -------------- | ---------- | -------- | ------------------------------------------------ |
| `id`           | `string`   | Yes      | Unique entry ID                                  |
| `userId`       | `string`   | Yes      | User who invoked the tool                        |
| `roleId`       | `string`   | Yes      | Role used for authorization                      |
| `toolPath`     | `string`   | Yes      | Tool that was invoked                            |
| `args`         | `object`   | No       | Arguments passed to the tool                     |
| `resultStatus` | `string`   | Yes      | One of: `success`, `error`, `denied`, `elicited` |
| `elicitTrail`  | `string[]` | No       | Execution IDs of elicitations triggered          |
| `timestamp`    | `string`   | Yes      | ISO 8601 datetime                                |

### Response (201)

```json theme={null}
{
  "logged": true
}
```

***

## List audit entries

```
GET /api/audit?userId=<userId>&limit=<limit>
```

| Parameter | In    | Required | Default | Description           |
| --------- | ----- | -------- | ------- | --------------------- |
| `userId`  | query | No       | --      | Filter by user        |
| `limit`   | query | No       | `50`    | Max entries to return |

**Response (200):**

```json theme={null}
{
  "userId": "user-123",
  "limit": 50,
  "entries": []
}
```