SparkVault API v1

Quick Start

Every call is plain JSON over HTTPS, authenticated with an API key: grab yours, then seal your first secret. It burns the moment it's read:

curl https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": "the launch code is 793-alpha", "ttl_minutes": 60}'

The response's data.spark_id is the one-time handle to your secret: read it once and it's gone. The Authentication and Response Format sections below cover the envelope, or skip the plumbing and start from the JavaScript SDK.

Explore the API

Base URL

All API requests should be made to the following base URL:

https://api.sparkvault.com/v1

Authentication

SparkVault supports two authentication methods:

• API Keys: Best for server-to-server integrations and automation. Keys are prefixed sv_live_ (production) or sv_test_ (test).
• JWT Tokens: Best for user-facing applications with session management

Include your API key in the X-API-Key header:

curl https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_YOUR_API_KEY"

See the Authentication guide for complete details.

Response Format

All successful responses follow a consistent JSON structure with data and meta fields:

{
  "data": {
    "spark_id": "spk_abc123...",
    "account_id": "acc_def456...",
    "content_type": "text/plain",
    "size_bytes": 1024,
    "status": "active",
    "created_at": 1702000000,
    "expires_at": 1702003600,
    "burned_at": null,
    "time_remaining": 3600
  },
  "meta": {
    "api_version": "1.x.y",
    "request_id": "req_xyz789...",
    "response_ms": 42,
    "timestamp": 1702000000,
    "pools": {
      "storage": { "used_gb": 12.5, "limit_gb": 100, "pct": 0.125, "state": "ok" },
      "bandwidth": { "used_gb": 3.25, "limit_gb": 100, "pct": 0.0325, "state": "ok", "cycle_resets_at": 1704067200 },
      "identity": { "used": 15, "limit": 500, "pct": 0.03, "state": "ok" }
    },
    "quota": {
      "limit": 300,
      "used": 15,
      "remaining": 285,
      "resets_at": 1702000060
    }
  }
}

Meta Fields

• api_version: Semantic version of the deployed API release
• request_id: Unique identifier for this request (useful for support)
• response_ms: Server processing time in milliseconds
• timestamp: Unix timestamp when response was generated
• pools: Pooled-capacity status for your subscription's storage, bandwidth, and identity pools, attached only on authenticated, successful responses to billable routes. Each pool reports usage against its limit, a utilization fraction (pct), and a state of ok | notice | warning | exhausted. This is usage tracking, not a spendable balance.
• quota: Rate limit status for your account (included on authenticated responses with status below 400)

Error Handling

Errors return a consistent structure with machine-readable codes and human-friendly messages:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "reason": "missing"
    }
  },
  "meta": {
    "api_version": "1.x.y",
    "request_id": "req_xyz789..."
  }
}

Common Error Codes

Rate Limiting

API requests are rate limited to 300 requests per minute per account, measured in 60-second windows. The current rate limit status is included in the meta.quota field of every authenticated response with a status below 400.

{
  "meta": {
    "quota": {
      "limit": 300,
      "used": 42,
      "remaining": 258,
      "resets_at": 1702000060
    }
  }
}

Pagination

List endpoints use cursor-based pagination with limit and cursor query parameters. Cursors are signed per account and bound to the resource they page over. A tampered, cross-account, or cross-resource cursor returns 400 VALIDATION_ERROR.

curl "https://api.sparkvault.com/v1/sparks?limit=20&cursor=eyJzcGFya19pZCI6..." \
  -H "X-API-Key: sv_live_YOUR_API_KEY"

Paginated responses include the items, a count, and cursor metadata:

{
  "data": {
    "sparks": [...],
    "count": 20,
    "has_more": true,
    "next_cursor": "eyJzcGFya19pZCI6..."
  }
}

next_cursor is present only when has_more is true. Pass it back as the cursor parameter to fetch the next page. A total field appears only on endpoints that compute one. Default and maximum limit vary per endpoint (default 25-100, max 100-500); check each endpoint's reference page for exact values. For example, /sparks and /vaults both default to 100 (max 500).

Security

Zero-Knowledge Architecture

SparkVault is designed so that we cannot access your encrypted data, even with full system access. Our multi-key architecture uses three types of master keys:

• SparkVault Master Key (SVMK): SparkVault's system-wide software ML-KEM-1024 keypair, stored in AWS SSM Parameter Store
• Account Master Key (AMK): Your account's unique HMAC key managed in AWS KMS (FIPS 140-3 validated)
• Vault Master Key (VMK): A per-vault key that you generate and control

Different features require different combinations of these keys:

• Sparks (Double Zero-Trust): Requires both the SVMK and your AMK
• Vaults (Triple Zero-Trust): Requires the SVMK, AMK, and your VMK

Key Management

Self-managed Vault Master Keys (VMKs) are generated client-side and are never stored by SparkVault. If you lose a self-managed VMK, the data in that vault is permanently unrecoverable, so always store it in a secure password manager or key management system. Vaults using the Hosted VMK option instead store the VMK KMS-wrapped (a per-vault key under the HVMK root KEK), which lets SparkVault derive vault access server-side for features like public sharing.

Client Libraries

Official SDKs handle authentication, encryption, and resumable transfers for you:

• JavaScript SDK: @sparkvault/sdk-js for browsers and Node.js
• Mobile SDK: @sparkvault/sdk-mobile for React Native and Expo

For other languages, any HTTP client works: the API is plain JSON over HTTPS.

Support

Need help? Include the request_id from the response when contacting support. This helps us quickly locate your request in our logs.

• Email: support@sparkvault.com