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

# SDK and API Reference

> Complete Vaultak SDK and REST API documentation, v0.5.0

## Installation

```
pip install vaultak
```

## Initialization

```
from vaultak import Vaultak, ActionType, KillSwitchMode

vt = Vaultak(
    api_key="vtk_your_api_key_here",
    allowed_action_types=[ActionType.FILE_READ, ActionType.API_CALL],
    allowed_resources=["/tmp/*", "/data/readonly/*"],
    blocked_resources=["prod.*", "*.env"],
    max_actions_per_minute=20,
    max_risk_score=0.7,
    mode=KillSwitchMode.PAUSE
)
```

## Parameters

| Parameter                 | Type           | Default            | Description                             |
| ------------------------- | -------------- | ------------------ | --------------------------------------- |
| api\_key                  | str            | required           | Your Vaultak API key                    |
| mode                      | KillSwitchMode | ALERT              | Response mode when violation occurs     |
| allowed\_action\_types    | list           | None (all allowed) | Whitelist of permitted action types     |
| allowed\_resources        | list           | None (all allowed) | Glob patterns for permitted resources   |
| blocked\_resources        | list           | \[]                | Glob patterns for blocked resources     |
| max\_actions\_per\_minute | int            | 60                 | Rate limit for agent actions            |
| max\_risk\_score          | float          | 1.0                | Hard ceiling on risk score              |
| risk\_threshold           | float          | 0.7                | Score that triggers the response mode   |
| rollback\_limit           | int            | 5                  | Max actions to reverse in ROLLBACK mode |

## Action Types

| Value                       | Description             |
| --------------------------- | ----------------------- |
| ActionType.FILE\_READ       | Reading a file          |
| ActionType.FILE\_WRITE      | Writing to a file       |
| ActionType.FILE\_DELETE     | Deleting a file         |
| ActionType.API\_CALL        | External API request    |
| ActionType.DATABASE\_QUERY  | Reading from a database |
| ActionType.DATABASE\_WRITE  | Writing to a database   |
| ActionType.CODE\_EXECUTION  | Executing code          |
| ActionType.NETWORK\_REQUEST | Network communication   |

## Response Modes

```
KillSwitchMode.ALERT     # Log and notify only (default)
KillSwitchMode.PAUSE     # Halt agent, await approval
KillSwitchMode.ROLLBACK  # Reverse last N actions and pause
```

## vt.monitor()

Context manager that wraps your entire agent session.

```
with vt.monitor("my-agent"):
    pass
```

## vt.log\_action()

Explicitly log a single agent action.

```
vt.log_action(
    agent_id="my-agent",
    action_type="file_delete",
    resource="/data/sensitive.csv",
    payload={"reason": "cleanup"}
)
```

## 5-Dimensional Risk Scoring

Every action is scored across five dimensions:

| Dimension            | Description                                      |
| -------------------- | ------------------------------------------------ |
| Action severity      | How destructive is this action type?             |
| Resource sensitivity | How sensitive is the target resource?            |
| Payload anomaly      | Does the payload deviate from baseline?          |
| Frequency            | Is the agent acting unusually fast?              |
| Context              | Does this action fit the agent's normal pattern? |

## REST API

All endpoints require your API key in the header:

```
x-api-key: vtk_your_api_key_here
```

## POST /api/check

Pre-execution risk check. Returns decision before action runs.

```
curl -X POST https://vaultak.com/api/check
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{"agent_id": "my-agent", "action_type": "file_delete", "resource": "/data/sensitive.csv"}'
```

Response:

```
{
  "decision": "block",
  "reason": "Resource '/data/sensitive.csv' is blocked for this agent",
  "risk_score": 0.91,
  "risk_breakdown": {...}
}
```

## PATCH /api/agents/{agent_id}/profile

Update an agent's permission profile from the API.

```
curl -X PATCH https://vaultak.com/api/agents/my-agent/profile
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{
    "allowed_action_types": ["file_read", "api_call"],
    "allowed_resources": ["/tmp/*"],
    "blocked_resources": ["prod.*", "*.env"],
    "max_actions_per_minute": 20,
    "max_risk_score": 0.7
  }'
```

## POST /api/actions

Log a completed agent action.

```
curl -X POST https://vaultak.com/api/actions
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{"agent_id": "my-agent", "action_type": "file_write", "resource": "/tmp/output.txt"}'
```

## GET /api/agents

List all registered agents with their permission profiles.

```
curl https://vaultak.com/api/agents
  -H "x-api-key: vtk_your_api_key_here"
```

## GET /api/alerts

Retrieve active alerts.

```
curl https://vaultak.com/api/alerts
  -H "x-api-key: vtk_your_api_key_here"
```

## Security Policies

Policies let you define rules that automatically block, pause, or allow actions.

```
curl -X POST https://vaultak.com/api/policies
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{
    "name": "no-prod-deletes",
    "action_type": "file_delete",
    "resource_pattern": "prod.*",
    "effect": "block",
    "max_risk_score": 0.5,
    "priority": 10
  }'
```

| Field             | Type  | Description                              |
| ----------------- | ----- | ---------------------------------------- |
| name              | str   | Human-readable policy name               |
| action\_type      | str   | Action type to match                     |
| resource\_pattern | str   | Glob pattern for resource matching       |
| effect            | str   | block, pause, or allow                   |
| max\_risk\_score  | float | Trigger if risk score exceeds this value |
| priority          | int   | Higher priority policies evaluated first |