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

# Audit

> Immutable logging of all lake activities

# Audit

Docyard maintains immutable audit logs for every action that happens in the lake. This ensures compliance, security, and accountability.

## What's Logged

### Artifact Uploads

Every artifact upload is logged:

```json theme={null}
{
  "event": "artifact_uploaded",
  "timestamp": "2026-03-15T10:30:00Z",
  "actor": {
    "type": "distributor",
    "id": "dist-abc123",
    "name": "Acme Insurance"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "upload endpoint_id": "upload endpoint-def456",
    "template": "Insurance Declaration",
    "locks": {
      "policy_number": "POL-12345678",
      "effective_date": "2026-03-15"
    },
    "threshold": 20
  }
}
```

### Retrieval Attempts

Every retrieval attempt is logged:

```json theme={null}
{
  "event": "artifact_retrieval_attempted",
  "timestamp": "2026-03-15T14:30:00Z",
  "actor": {
    "type": "collector",
    "id": "coll-xyz789",
    "name": "FirstCity Bank"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "dock_id": "dock-abc123",
    "keys_provided": ["policy_number"],
    "score": 20,
    "threshold": 20,
    "result": "granted"
  }
}
```

### Access Denials

Failed retrieval attempts are also logged:

```json theme={null}
{
  "event": "artifact_retrieval_denied",
  "timestamp": "2026-03-15T14:35:00Z",
  "actor": {
    "type": "collector",
    "id": "coll-unknown",
    "name": "Unknown Entity"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "dock_id": "dock-unknown",
    "keys_provided": [],
    "score": 0,
    "threshold": 20,
    "result": "denied",
    "reason": "insufficient_keys"
  }
}
```

### Template Changes

Template creation and updates:

```json theme={null}
{
  "event": "template_created",
  "timestamp": "2026-03-10T09:00:00Z",
  "actor": {
    "type": "distributor",
    "id": "dist-abc123",
    "name": "Acme Insurance"
  },
  "resource": {
    "type": "template",
    "id": "tmpl-abc123"
  },
  "details": {
    "template_name": "Acme Declaration Page",
    "locks_count": 4,
    "status": "draft"
  }
}
```

### Admin Actions

Admin vetting and approvals:

```json theme={null}
{
  "event": "template_approved",
  "timestamp": "2026-03-10T11:00:00Z",
  "actor": {
    "type": "admin",
    "id": "admin-001",
    "name": "Docyard Admin"
  },
  "resource": {
    "type": "template",
    "id": "tmpl-abc123"
  },
  "details": {
    "previous_status": "pending_approval",
    "new_status": "published"
  }
}
```

## Log Structure

Each audit log entry contains:

| Field       | Description         | Example                |
| ----------- | ------------------- | ---------------------- |
| `event`     | Type of event       | `artifact_uploaded`    |
| `timestamp` | When it happened    | `2026-03-15T10:30:00Z` |
| `actor`     | Who did it          | `{ type, id, name }`   |
| `resource`  | What was affected   | `{ type, id }`         |
| `details`   | Event-specific data | `{ ... }`              |
| `metadata`  | Additional context  | `{ ip, user_agent }`   |

## Querying Logs

### List All Logs

```json theme={null}
GET /api/v1/audit/logs
```

```json theme={null}
{
  "logs": [
    { "event": "artifact_uploaded", "timestamp": "2026-03-15T10:30:00Z" },
    { "event": "artifact_retrieved", "timestamp": "2026-03-15T14:30:00Z" }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1250 }
}
```

### Filter by Event Type

```json theme={null}
GET /api/v1/audit/logs?event=artifact_retrieval_attempted
```

### Filter by Actor

```json theme={null}
GET /api/v1/audit/logs?actor_type=collector&actor_id=coll-xyz789
```

### Filter by Time Range

```json theme={null}
GET /api/v1/audit/logs?after=2026-03-01T00:00:00Z&before=2026-03-31T23:59:59Z
```

### Filter by Resource

```json theme={null}
GET /api/v1/audit/logs?resource_type=artifact&resource_id=art-xyz789
```

### Get Entity History

Get all events for a specific artifact:

```json theme={null}
GET /api/v1/audit/entity/art-xyz789
```

```json theme={null}
{
  "entity_id": "art-xyz789",
  "entity_type": "artifact",
  "events": [
    {
      "event": "artifact_uploaded",
      "timestamp": "2026-03-15T10:30:00Z",
      "actor": "Acme Insurance"
    },
    {
      "event": "artifact_retrieved",
      "timestamp": "2026-03-15T14:30:00Z",
      "actor": "FirstCity Bank"
    },
    {
      "event": "artifact_retrieved",
      "timestamp": "2026-03-15T15:00:00Z",
      "actor": "FirstCity Bank"
    }
  ]
}
```

## Retention Policies

Audit logs are retained based on document type:

| Document Type          | Retention Period |
| ---------------------- | ---------------- |
| Insurance declarations | 7 years          |
| Loan agreements        | 10 years         |
| Birth certificates     | Permanent        |
| General documents      | 3 years          |

## Compliance Use Cases

### For Distributors

* Prove artifact was uploaded on a specific date
* Track who retrieved your documents
* Monitor for unauthorized access attempts

### For Collectors

* Demonstrate chain of custody for audits
* Prove documents were retrieved legally
* Track internal document access

### For Docyard

* Detect anomalous access patterns
* Investigate security incidents
* Generate compliance reports

## Exporting Logs

### Export to JSON

```json theme={null}
GET /api/v1/audit/export?format=json&after=2026-01-01
```

### Export to CSV

```json theme={null}
GET /api/v1/audit/export?format=csv&after=2026-01-01
```

### Export for Specific Entity

```json theme={null}
GET /api/v1/audit/entity/art-xyz789/export?format=pdf
```

## Immutability

Audit logs cannot be modified or deleted:

* Append-only storage
* Cryptographic signatures
* Distributed across multiple nodes
* Tamper-evident timestamps

Any attempt to modify logs creates a new log entry recording the modification attempt itself.

***

## Next Steps

* Understand [Distributors](/concepts/distributors)
* Understand [Collectors](/concepts/collectors)
* See the [API Reference](/api-reference/audit)