Skip to content
TimeCairn

TimeCairn API v1

Programmatic interface to TimeCairn's hash-only stake flow. Same evidentiary weight as the web hash-only path: TSA-witnessed RFC 3161 timestamps over your file's SHA-256, plus an optional canonical attestation envelope. Your file bytes never leave your machine.

Authentication

Generate a key at /dashboard/api-keys. Send it as a Bearer token:

Authorization: Bearer corner_<32 chars>

We store only a SHA-256 hash of your token; if you lose it, revoke and generate a new one. Each key is rate-limited independently.

POST /api/v1/stake/hash

Create a hash-only stake.

Request body (JSON):

{
  "sha256_hex": "5b1ef9...64 hex chars",
  "file_name": "qscf-prereg-T1.md",
  "file_size": 12345,
  "file_mime": "text/markdown",
  "claimant_attestation": {
    "declarant_name": "Steven Mullins Jr.",
    "claim_type": "Pre-registration",
    "jurisdiction": "US",
    "self_link": "https://example.com/me",
    "claim_description": "QSCF Tier 1 T1 CHSH pre-registration v0.1.0"
  }
}

Response 200:

{
  "public_id": "r-ee29b292349aad3b",
  "status": "stamped",
  "tsa_proofs_count": 8,
  "envelope_proofs_count": 8,
  "envelope_hash_sha256": "ab12...",
  "staked_at": "2026-05-02T20:30:00.000Z",
  "stamped_at": "2026-05-02T20:30:04.123Z",
  "url": "https://timecairn.com/r/r-ee29b292349aad3b"
}

GET /api/v1/receipts/{public_id}

Fetch a receipt. Public receipts return without a bearer; your own private receipts return when you authenticate. Anyone else gets 404 on a private receipt (we never reveal its existence).

Rate limits

Per API key:

429 includes a human-readable reason. Reads (GET) are unlimited in v1.

Errors

{
  "error": {
    "code": "rate_limited" | "unauthorized" | "invalid_request" |
            "hash_invalid" | "size_exceeded" | "not_found" | "internal_error",
    "message": "<human-readable>"
  }
}

Quick example (curl)

HASH=$(sha256sum mydoc.md | awk '{print $1}')
SIZE=$(stat -c%s mydoc.md)
curl -X POST https://timecairn.com/api/v1/stake/hash \
  -H "Authorization: Bearer $CORNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"sha256_hex\":\"$HASH\",\"file_name\":\"mydoc.md\",\"file_size\":$SIZE}"