REST API Reference for Inheribase Vaults and Assets

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.

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:

{
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-23T10:30:00Z",
    "requestId": "req_abc123"
  }
}

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

{
  "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.

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

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

interface Heir {
  id: string;
  name: string;
  email: string;
  walletAddress?: string;
  addedAt: string; // ISO 8601
}

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.

curl -H "x-api-key: sk_human_abc123" \
     https://api.inheribase.com/v1/vault

Response 200 OK:

{
  "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.

curl -H "x-api-key: sk_human_abc123" \
     https://api.inheribase.com/v1/vault/vault_01HQXYZ

Response 200 OK:

{
  "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`

{
  "trigger": "dead_man_switch",
  "config": {
    "checkInFrequency": "monthly"
  }
}

Response 200 OK:

{
  "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

{
  "name": "Sarah Chen",
  "email": "sarah@example.com"
}

Response 201 Created:

{
  "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:

{
  "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

{
  "name": "Alex Chen",
  "email": "alex@example.com"
}

Response 201 Created:

{
  "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:

{
  "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 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:

{
  "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:

{
  "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):

{
  "note": "Monthly review completed"
}

Response 200 OK:

{
  "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:

{
  "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

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.

​Authentication

​Key types

​Response format

​Error codes

​Rate limits

​Types

​Endpoints

​Vaults

​List vaults

​Get vault details

​Update release configuration

​People

​Add guardian

​Remove guardian

​Add heir

​Remove heir

​Assets

​Upload asset

​List assets

​Release

​Check in (reset DMS timer)

​Cancel release

​Deprecated endpoints (v1.0)

Authentication

Key types

Response format

Error codes

Rate limits

Types

Endpoints

Vaults

List vaults

Get vault details

Update release configuration

People

Add guardian

Remove guardian

Add heir

Remove heir

Assets

Upload asset

List assets

Release

Check in (reset DMS timer)

Cancel release

Deprecated endpoints (v1.0)