Inheribase LogoInheribase
AI IntegrationsAPI Reference
Verified by Inheribase Team

API Reference

Complete REST API reference for building on the Inheribase protocol.

API Reference

The Inheribase API enables programmatic management of vaults, assets, guardians, and heirs. All endpoints follow REST conventions and return JSON responses.

Base URL: https://api.inheribase.com

Authentication

All requests require an 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 PrefixScopeUse Case
sk_human_...Full vault accessPersonal, 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 follow this structure:

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

Error responses:

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

Error Codes

HTTP StatusError CodeDescriptionResolution
400VALIDATION_ERRORRequest body failed validationCheck required fields and data types
401UNAUTHORIZEDMissing or invalid API keyVerify your x-api-key header
402INSUFFICIENT_CREDITSVault Credits balance too lowTop up credits from the dashboard
403FORBIDDENAPI key lacks permissionUse an sk_human_ key or request elevated scope
404NOT_FOUNDResource does not existVerify the vault/guardian/heir ID
409CONFLICTResource already exists or state conflictCheck current vault state before retrying
429RATE_LIMITEDToo many requestsWait for Retry-After header duration
500INTERNAL_ERRORServer errorRetry after a brief delay; contact support if persistent

Rate Limits

Endpoint PatternLimitWindow
GET /api/vault*120 requestsPer minute
POST /api/vault/:id/asset60 requestsPer minute
POST /api/vault/:id/release/*10 requestsPer minute
POST /api/vault/:id/guardian30 requestsPer minute
POST /api/vault/:id/heir30 requestsPer minute

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

Types

Vault

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

Guardian

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

Heir

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

Asset

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.

Example:

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

Example:

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

Request Body:

{
  "trigger": "dead_man_switch",
  "config": {
    "checkInFrequency": "monthly"
  }
}
FieldTypeRequiredDescription
triggerReleaseTriggerYesOne of dead_man_switch, manual, guardian_claim
config.checkInFrequencystringFor DMSweekly, biweekly, monthly, or quarterly

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 guardian.

Request Body:

{
  "name": "Sarah Chen",
  "email": "sarah@example.com"
}
FieldTypeRequiredDescription
namestringYesGuardian's display name
emailstringYesValid email address
walletAddressstringNoOptional Ethereum address

Response 201 Created:

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

Errors:

  • 409 — Guardian with this email already exists
  • 400 — Guardian limit reached for the current SSS preset

Remove Guardian

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

Response 200 OK:

{
  "data": {
    "removed": "grd_01HQABC",
    "remainingGuardians": 2,
    "sharesRegenerated": true
  }
}

Add Heir

POST /api/vault/:id/heir

Request Body:

{
  "name": "Alex Chen",
  "email": "alex@example.com"
}
FieldTypeRequiredDescription
namestringYesHeir's display name
emailstringYesValid email address
walletAddressstringNoOptional Ethereum address

Response 201 Created:

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

Errors:

  • 409 — Heir with this email already exists
  • 400 — Maximum 5 heirs per vault

Remove Heir

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

Response 200 OK:

{
  "data": {
    "removed": "heir_01HQDEF",
    "remainingHeirs": 1
  }
}

Assets

Upload Asset

POST /api/vault/:id/asset

Upload an encrypted asset. Files must be encrypted client-side before upload.

Request Body (multipart/form-data):

FieldTypeRequiredDescription
filebinaryYesEncrypted file data
filenamestringYesOriginal filename
contentTypestringNoMIME type (auto-detected if omitted)
metadataJSON stringNoCustom 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 5 GB limit

List Assets

GET /api/vault/:id/asset

Query Parameters:

ParameterTypeDefaultDescription
categorystringallFilter: document, image, video, audio, other
limitnumber50Results per page (max 100)
offsetnumber0Pagination 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

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)

Cancel Release

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

Cancel an active release during the 30-day contestation period.

Response 200 OK:

{
  "data": {
    "cancelled": true,
    "vaultState": "active",
    "cancelledAt": "2026-03-23T10:30:00Z"
  }
}

Errors:

  • 409 — Vault is not in releasing state or contestation period elapsed

Deprecated Endpoints (v1.0)

The following endpoints were removed in v2.0. See the Migration Guide.

Removed EndpointReplacement
POST /api/vault/:id/lockVault states simplified to active / releasing / released
POST /api/vault/:id/unlockVault states simplified
* /api/vault/:id/protection/*Merged into People endpoints
* /api/vault/:id/succession/*Merged into People endpoints
POST /api/vault/:id/release/contestPOST /api/vault/:id/release/cancel
* /api/vault/:id/verificationRemoved (verification is automatic)
* /api/vault/:id/certificateRemoved
GET /api/verify/:hashRemoved

SDK & Integration

Webhooks

Webhook support for real-time event notifications is planned for a future release. Use polling via GET /api/vault/:id to monitor vault state changes.

On this page

API ReferenceAuthenticationKey TypesResponse FormatError CodesRate LimitsTypesVaultGuardianHeirAssetEndpointsVaultsList VaultsGet Vault DetailsUpdate Release ConfigurationPeopleAdd GuardianRemove GuardianAdd HeirRemove HeirAssetsUpload AssetList AssetsReleaseCheck In (Reset DMS Timer)Cancel ReleaseDeprecated Endpoints (v1.0)SDK & IntegrationWebhooks