Sparks API v1

Overview

Sparks are ephemeral, self-destructing secrets. When someone reads a Spark, the plaintext is returned and the Spark is immediately destroyed ("burned"). The encrypted data can never be accessed again.

Key Features

• Read-Once: Data is permanently destroyed after first read
• Auto-Expiration: Unread Sparks expire after TTL (default 24 hours, max 24 hours)
• Double Zero-Trust: Encrypted with both system and account keys
• Audit Trail: Track when Sparks are created, read, and destroyed

Content Types

Sparks support both text and binary content. The server treats text/* types (plus application/json, application/xml, application/javascript, and types with +json/+xml suffixes) as text: send those payloads as UTF-8 strings. Any other content type is treated as binary: base64-encode the payload and set content_type to the appropriate MIME type.

Spark States

Create Spark

curl -X POST https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "super_secret_password_123",
    "ttl_minutes": 60
  }'

{
  "data": {
    "spark_id": "spk_abc123def456...",
    "size_bytes": 25,
    "status": "active",
    "created_at": 1702000000,
    "expires_at": 1702003600,
    "ttl_minutes": 60
  }
}

Link Sparks (text/uri-list)

Setting content_type to text/uri-list creates a link Spark: the payload must be a single http/https URL (validated before sealing), and the destination is encrypted at rest, never stored in plaintext. The server automatically mints a public x.sv SparkLink for the Spark, so the response additionally carries link_url (https://x.sv/{code}) and link_code. The destination burns on first open. Pass bound_ip to bind the link to a single IP address. List responses surface link_url for link Sparks.

curl -X POST https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "https://example.com/one-time-download",
    "content_type": "text/uri-list",
    "ttl_minutes": 60
  }'

{
  "data": {
    "spark_id": "spk_abc123...",
    "size_bytes": 38,
    "status": "active",
    "created_at": 1702000000,
    "expires_at": 1702003600,
    "ttl_minutes": 60,
    "link_url": "https://x.sv/abc123...",
    "link_code": "abc123..."
  }
}

List Sparks

curl "https://api.sparkvault.com/v1/sparks?status=active&limit=10" \
  -H "X-API-Key: sv_live_xxx"

{
  "data": {
    "sparks": [
      {
        "spark_id": "spk_abc123...",
        "account_id": "acc_xyz789...",
        "content_type": "text/plain",
        "status": "active",
        "size_bytes": 25,
        "created_at": 1702000000,
        "expires_at": 1702086400,
        "burned_at": null,
        "time_remaining": 82800
      }
    ],
    "count": 1,
    "has_more": false
  }
}

Read Spark (Burn)

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

{
  "data": {
    "spark_id": "spk_abc123def456...",
    "payload": "super_secret_password_123",
    "content_type": "text/plain",
    "size_bytes": 25,
    "status": "ash",
    "created_at": 1702000000,
    "burned_at": 1702001000,
    "was_active": true
  }
}

Delete Spark

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

(204 No Content)

Kindling (Grouping Sparks)

Kindling allows you to group related Sparks together. This is useful for multi-step workflows like verification flows, retry sequences, or any scenario where multiple Sparks belong to the same logical operation.

How Kindling Works

• Start a Group: Create a Spark with with_kindling: true to generate a new kindling ID
• Join a Group: Create subsequent Sparks with kindling: "kdl_xxx" to add them to the family
• Query by Kindling: List all Sparks in a group using ?kindling=kdl_xxx

curl -X POST https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "verification code data",
    "ttl_minutes": 15,
    "with_kindling": true
  }'

{
  "data": {
    "spark_id": "spk_abc123...",
    "kindling": "kdl_xyz789...",
    "status": "active",
    "created_at": 1702000000,
    "expires_at": 1702000900
  }
}

curl -X POST https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "retry data",
    "ttl_minutes": 15,
    "kindling": "kdl_xyz789..."
  }'

{
  "data": {
    "spark_id": "spk_def456...",
    "kindling": "kdl_xyz789...",
    "status": "active",
    "created_at": 1702000100,
    "expires_at": 1702001000
  }
}

curl "https://api.sparkvault.com/v1/sparks?kindling=kdl_xyz789" \
  -H "X-API-Key: sv_live_xxx"

{
  "data": {
    "sparks": [
      {
        "spark_id": "spk_abc123...",
        "kindling": "kdl_xyz789...",
        "status": "ash",
        "created_at": 1702000000
      },
      {
        "spark_id": "spk_def456...",
        "kindling": "kdl_xyz789...",
        "status": "active",
        "created_at": 1702000100
      }
    ],
    "count": 2,
    "has_more": false
  }
}

Sharing Sparks

Share sparks via x.sv URLs using the /v1/sparks/:id/share endpoint. SparkLinks provide shareable URLs with visibility controls.

curl -X PATCH https://api.sparkvault.com/v1/sparks/spk_xxx/share \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'

{
  "data": {
    "shared": true,
    "share_url": "https://x.sv/abc123...",
    "link_code": "abc123...",
    "visibility": "public",
    "invites": [],
    "expires_at": 1702086400,
    "created_at": 1702000000
  }
}

Common Use Cases

Share Database Credentials

// Create a Spark with database credentials
const response = await fetch('https://api.sparkvault.com/v1/sparks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPARKVAULT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payload: JSON.stringify({
      host: 'db.example.com',
      username: 'admin',
      password: 'super_secret_password'
    }),
    ttl_minutes: 60 // Expires in 1 hour
  })
});

const { spark_id } = (await response.json()).data;

// Mint a burn-on-read x.sv link for the recipient
const shareResponse = await fetch(`https://api.sparkvault.com/v1/sparks/${spark_id}/share`, {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.SPARKVAULT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ visibility: 'public' })
});

const { share_url } = (await shareResponse.json()).data;

// Hand out share_url via Slack, email, etc.
console.log(`Share this link: ${share_url}`);

Share Binary Files (PDF, Images)

// Read file and convert to base64
const fs = require('fs');
const fileBuffer = fs.readFileSync('contract.pdf');
const base64Content = fileBuffer.toString('base64');

const response = await fetch('https://api.sparkvault.com/v1/sparks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPARKVAULT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filename: 'Signed Contract.pdf',
    payload: base64Content,
    content_type: 'application/pdf',  // Binary content
    ttl_minutes: 1440
  })
});

// Recipient reads the Spark
const readResponse = await fetch(`https://api.sparkvault.com/v1/sparks/${spark_id}`, {
  headers: { 'X-API-Key': recipientApiKey }
});
const { payload, content_type } = (await readResponse.json()).data;

// The server treats text/*, application/json, application/xml,
// application/javascript, and +json/+xml types as UTF-8 text;
// every other content type arrives base64-encoded.
const isText = content_type.startsWith('text/')
  || ['application/json', 'application/xml', 'application/javascript'].includes(content_type)
  || content_type.endsWith('+json')
  || content_type.endsWith('+xml');

if (!isText) {
  const buffer = Buffer.from(payload, 'base64');
  fs.writeFileSync('downloaded.pdf', buffer);
}

Secure CI/CD Secret Injection

# Read the Spark and inject into environment
CREDENTIALS=$(curl -s "https://api.sparkvault.com/v1/sparks/$SPARK_ID" \
  -H "X-API-Key: $SPARKVAULT_API_KEY" | jq -r '.data.payload')

# Parse and export
export DB_PASSWORD=$(echo $CREDENTIALS | jq -r '.password')

# The Spark is now burned and cannot be read again
# Even if someone obtains the SPARK_ID, the secret is gone

API Key Rotation

import requests
import os

# Generate new API key and share via Spark
new_api_key = generate_new_api_key()

response = requests.post(
    'https://api.sparkvault.com/v1/sparks',
    headers={
        'X-API-Key': os.environ['SPARKVAULT_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'payload': new_api_key,
        'ttl_minutes': 1440  # 24 hours to claim
    }
)

spark_id = response.json()['data']['spark_id']
notify_team(f"New API key ready: {spark_id}")

Usage

Spark operations are covered by your seat subscription. Usage is tracked against the pool included with your plan; there are no per-operation charges. For subscription tiers and capacity blocks, see the pricing page.

Security Model

Double Zero-Trust Encryption

Sparks use two independent encryption keys:

1. SparkVault Master Key (SVMK): A post-quantum ML-KEM-1024 keypair retrieved at runtime from AWS SSM Parameter Store. Sealing a Spark performs a software ML-KEM-1024 encapsulation to produce a per-Spark shared secret.
2. Account Master Key (AMK): Your account's unique HMAC key managed in a FIPS 140-3 validated key management system (AWS KMS). The API calls KMS GenerateMac (HMAC-SHA512) to produce a per-Spark salt; the key itself never leaves KMS.

The per-Spark encryption key is derived with HKDF from the ML-KEM-1024 shared secret and the KMS HMAC salt, and the payload is sealed with AES-256-GCM. Both keys are required to decrypt a Spark. Even with full database access, SparkVault cannot decrypt Sparks without combining these keys, which are stored separately with strict access controls.

Atomic Burn

When a Spark is read, the decryption and deletion happen atomically behind a read lock. The encrypted data is deleted from storage before the plaintext is returned. This ensures that even in the event of a system failure, the Spark cannot be read twice: if the burn cannot be completed, the plaintext is withheld and the request fails with 500 SPARK_BURN_FAILED.

Error Reference