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

# REST API Reference for Inheribase Vaults and Assets

> Complete REST API reference for the Inheribase protocol — authentication, error codes, rate limits, types, and all vault endpoints.

The Inheribase API lets you programmatically manage vaults, assets, guardians, and heirs. The base URL for all requests is `https://api.inheribase.com`. All endpoints follow REST conventions and return JSON responses.

## Authentication

Every request requires your Inheribase API key in the `x-api-key` header.

```bash theme={null}
curl -H "x-api-key: sk_human_your_key_here" \
     https://api.inheribase.com/v1/vault
```

### Key types

| Key prefix     | Scope                             | Use case                       |
| -------------- | --------------------------------- | ------------------------------ |
| `sk_human_...` | Full vault access                 | Personal, trusted environments |
| `sk_agent_...` | Restricted (read + check-in only) | Shared or automated setups     |

Generate keys from **Dashboard → Settings → API Keys**.

## Response format

All successful responses use this envelope structure:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-23T10:30:00Z",
    "requestId": "req_abc123"
  }
}
```

Error responses include an `error` object with a machine-readable code:

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your Vault Credits balance is insufficient for this operation.",
    "status": 402
  }
}
```

## Error codes

| HTTP status | Error code             | Description                               | Resolution                                               |
| ----------- | ---------------------- | ----------------------------------------- | -------------------------------------------------------- |
| **400**     | `VALIDATION_ERROR`     | Request body failed validation            | Check required fields and data types                     |
| **401**     | `UNAUTHORIZED`         | Missing or invalid API key                | Verify your `x-api-key` header                           |
| **402**     | `INSUFFICIENT_CREDITS` | Vault Credits balance too low             | Top up credits from the dashboard                        |
| **403**     | `FORBIDDEN`            | API key lacks permission                  | Use an `sk_human_` key or request elevated scope         |
| **404**     | `NOT_FOUND`            | Resource does not exist                   | Verify the vault, guardian, or heir ID                   |
| **409**     | `CONFLICT`             | Resource already exists or state conflict | Check current vault state before retrying                |
| **429**     | `RATE_LIMITED`         | Too many requests                         | Wait for the duration in the `Retry-After` header        |
| **500**     | `INTERNAL_ERROR`       | Server error                              | Retry after a brief delay; contact support if persistent |

## Rate limits

| Endpoint pattern                | Limit        | Window     |
| ------------------------------- | ------------ | ---------- |
| `GET /api/vault*`               | 120 requests | Per minute |
| `POST /api/vault/:id/asset`     | 60 requests  | Per minute |
| `POST /api/vault/:id/release/*` | 10 requests  | Per minute |
| `POST /api/vault/:id/guardian`  | 30 requests  | Per minute |
| `POST /api/vault/:id/heir`      | 30 requests  | Per minute |

Rate-limited responses include a `Retry-After` header with the number of seconds to wait before retrying.

## Types

The following TypeScript interfaces describe the shape of objects returned by the API.

```typescript theme={null}
interface Vault {
  id: string;
  state: VaultState;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
  creditsBalance: number; // In Vault Credits (1 = $0.01)
  assetCount: number;
  guardianCount: number;
  heirCount: number;
  releaseTrigger: ReleaseTrigger | null;
  sssPreset: SSSPreset;
}

type VaultState = "active" | "releasing" | "released";
type ReleaseTrigger = "dead_man_switch" | "manual" | "guardian_claim";
type SSSPreset = "standard" | "enhanced";
// standard = 2-of-3, enhanced = 3-of-5
```

```typescript theme={null}
interface Guardian {
  id: string;
  name: string;
  email: string;
  status: "pending" | "accepted" | "declined";
  walletAddress?: string;
  invitedAt: string; // ISO 8601
  acceptedAt?: string; // ISO 8601
}
```

```typescript theme={null}
interface Heir {
  id: string;
  name: string;
  email: string;
  walletAddress?: string;
  addedAt: string; // ISO 8601
}
```

```typescript theme={null}
interface Asset {
  id: string;
  filename: string;
  contentType: string; // MIME type
  sizeBytes: number;
  category: "document" | "image" | "video" | "audio" | "other";
  arweaveTxId: string;
  createdAt: string; // ISO 8601
}
```

## Endpoints

### Vaults

#### List vaults

```
GET /api/vault
```

Returns all vaults owned by the authenticated user.

```bash theme={null}
curl -H "x-api-key: sk_human_abc123" \
     https://api.inheribase.com/v1/vault
```

**Response** `200 OK`:

```json theme={null}
{
  "data": [
    {
      "id": "vault_01HQXYZ",
      "state": "active",
      "createdAt": "2026-01-15T09:00:00Z",
      "creditsBalance": 5000,
      "assetCount": 12,
      "guardianCount": 3,
      "heirCount": 2,
      "releaseTrigger": "dead_man_switch",
      "sssPreset": "standard"
    }
  ]
}
```

***

#### Get vault details

```
GET /api/vault/:id
```

Returns the full details for a single vault, including timestamps and current state.

```bash theme={null}
curl -H "x-api-key: sk_human_abc123" \
     https://api.inheribase.com/v1/vault/vault_01HQXYZ
```

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "id": "vault_01HQXYZ",
    "state": "active",
    "createdAt": "2026-01-15T09:00:00Z",
    "updatedAt": "2026-03-20T14:30:00Z",
    "creditsBalance": 5000,
    "assetCount": 12,
    "guardianCount": 3,
    "heirCount": 2,
    "releaseTrigger": "dead_man_switch",
    "sssPreset": "standard"
  }
}
```

***

#### Update release configuration

```
POST /api/vault/:id/release/config
```

Configure the trigger type and check-in frequency for a vault's release mechanism.

**Request body:**

| Field                     | Type             | Required | Description                                             |
| ------------------------- | ---------------- | -------- | ------------------------------------------------------- |
| `trigger`                 | `ReleaseTrigger` | Yes      | One of `dead_man_switch`, `manual`, or `guardian_claim` |
| `config.checkInFrequency` | `string`         | For DMS  | `weekly`, `biweekly`, `monthly`, or `quarterly`         |

```json theme={null}
{
  "trigger": "dead_man_switch",
  "config": {
    "checkInFrequency": "monthly"
  }
}
```

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "trigger": "dead_man_switch",
    "checkInFrequency": "monthly",
    "contestationDays": 30,
    "nextCheckInDue": "2026-04-20T14:30:00Z"
  }
}
```

***

### People

#### Add guardian

```
POST /api/vault/:id/guardian
```

Sends an invitation email to the specified guardian. Guardians participate in Shamir's Secret Sharing (SSS) to protect your vault key.

**Request body:**

| Field           | Type     | Required | Description               |
| --------------- | -------- | -------- | ------------------------- |
| `name`          | `string` | Yes      | Guardian's display name   |
| `email`         | `string` | Yes      | Valid email address       |
| `walletAddress` | `string` | No       | Optional Ethereum address |

```json theme={null}
{
  "name": "Sarah Chen",
  "email": "sarah@example.com"
}
```

**Response** `201 Created`:

```json theme={null}
{
  "data": {
    "id": "grd_01HQABC",
    "name": "Sarah Chen",
    "email": "sarah@example.com",
    "status": "pending",
    "invitedAt": "2026-03-23T10:30:00Z"
  }
}
```

**Errors:**

* `409` — A guardian with this email address already exists on this vault.
* `400` — Guardian limit reached for the current SSS preset.

***

#### Remove guardian

```
DELETE /api/vault/:id/guardian/:gid
```

Removes a guardian from the vault and regenerates SSS shares for the remaining guardians.

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "removed": "grd_01HQABC",
    "remainingGuardians": 2,
    "sharesRegenerated": true
  }
}
```

***

#### Add heir

```
POST /api/vault/:id/heir
```

Adds an heir to the vault. Heirs receive access to your vault contents when a release is triggered.

**Request body:**

| Field           | Type     | Required | Description               |
| --------------- | -------- | -------- | ------------------------- |
| `name`          | `string` | Yes      | Heir's display name       |
| `email`         | `string` | Yes      | Valid email address       |
| `walletAddress` | `string` | No       | Optional Ethereum address |

```json theme={null}
{
  "name": "Alex Chen",
  "email": "alex@example.com"
}
```

**Response** `201 Created`:

```json theme={null}
{
  "data": {
    "id": "heir_01HQDEF",
    "name": "Alex Chen",
    "email": "alex@example.com",
    "addedAt": "2026-03-23T10:30:00Z"
  }
}
```

**Errors:**

* `409` — An heir with this email address already exists on this vault.
* `400` — Maximum 5 heirs per vault.

***

#### Remove heir

```
DELETE /api/vault/:id/heir/:hid
```

Removes an heir from the vault.

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "removed": "heir_01HQDEF",
    "remainingHeirs": 1
  }
}
```

***

### Assets

#### Upload asset

```
POST /api/vault/:id/asset
```

Upload an encrypted asset to the vault. Files must be encrypted client-side before upload. Consult the [MCP Server guide](/agents/mcp-server) if you want encryption handled automatically by an AI assistant.

**Request body** (`multipart/form-data`):

| Field         | Type          | Required | Description                          |
| ------------- | ------------- | -------- | ------------------------------------ |
| `file`        | `binary`      | Yes      | Encrypted file data                  |
| `filename`    | `string`      | Yes      | Original filename                    |
| `contentType` | `string`      | No       | MIME type — auto-detected if omitted |
| `metadata`    | `JSON string` | No       | Custom metadata tags                 |

**Response** `201 Created`:

```json theme={null}
{
  "data": {
    "id": "asset_01HQGHI",
    "filename": "family-trust-2026.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 2048576,
    "category": "document",
    "arweaveTxId": "ar_tx_abc123def456",
    "createdAt": "2026-03-23T10:30:00Z",
    "creditsConsumed": 20
  }
}
```

**Errors:**

* `402` — Insufficient credits for the file size.
* `400` — File exceeds the 5 GB limit.

***

#### List assets

```
GET /api/vault/:id/asset
```

Returns a paginated list of assets stored in the vault.

**Query parameters:**

| Parameter  | Type     | Default | Description                                                           |
| ---------- | -------- | ------- | --------------------------------------------------------------------- |
| `category` | `string` | all     | Filter by category: `document`, `image`, `video`, `audio`, or `other` |
| `limit`    | `number` | 50      | Results per page (max 100)                                            |
| `offset`   | `number` | 0       | Pagination offset                                                     |

**Response** `200 OK`:

```json theme={null}
{
  "data": [
    {
      "id": "asset_01HQGHI",
      "filename": "family-trust-2026.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 2048576,
      "category": "document",
      "arweaveTxId": "ar_tx_abc123def456",
      "createdAt": "2026-03-23T10:30:00Z"
    }
  ],
  "meta": { "total": 12, "limit": 50, "offset": 0 }
}
```

***

### Release

#### Check in (reset DMS timer)

```
POST /api/vault/:id/release/checkin
```

Records an Audit Pulse that confirms you are active and resets the Dead Man's Switch countdown. Each check-in costs 2 Vault Credits (\$0.02).

**Request body** (optional):

```json theme={null}
{
  "note": "Monthly review completed"
}
```

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "success": true,
    "nextCheckInDue": "2026-04-23T10:30:00Z",
    "daysRemaining": 30
  }
}
```

**Errors:**

* `402` — Check-in costs \$0.02 (2 credits) — top up your balance to proceed.

***

#### Cancel release

```
POST /api/vault/:id/release/cancel
```

Cancel an active release during the 30-day contestation period. You cannot cancel a release after the contestation period has elapsed.

**Response** `200 OK`:

```json theme={null}
{
  "data": {
    "cancelled": true,
    "vaultState": "active",
    "cancelledAt": "2026-03-23T10:30:00Z"
  }
}
```

**Errors:**

* `409` — Vault is not in `releasing` state, or the contestation period has elapsed.

***

## Deprecated endpoints (v1.0)

The following endpoints were removed in v2.0 as part of the API simplification.

| Removed endpoint                      | Replacement                                                    |
| ------------------------------------- | -------------------------------------------------------------- |
| `POST /api/vault/:id/lock`            | Vault states simplified to `active` / `releasing` / `released` |
| `POST /api/vault/:id/unlock`          | Vault states simplified                                        |
| `* /api/vault/:id/protection/*`       | Merged into People endpoints                                   |
| `* /api/vault/:id/succession/*`       | Merged into People endpoints                                   |
| `POST /api/vault/:id/release/contest` | `POST /api/vault/:id/release/cancel`                           |
| `* /api/vault/:id/verification`       | Removed — verification is now automatic                        |
| `* /api/vault/:id/certificate`        | Removed                                                        |
| `GET /api/verify/:hash`               | Removed                                                        |

<Note>
  Webhook support for real-time event notifications is planned for a future release. In the meantime, poll `GET /api/vault/:id` to monitor vault state changes.
</Note>