API Timestamp Endpoints

Endpoints Overview

Method	Path	Auth	Description
POST	/api/timestamps	✅	Create a new timestamp batch
GET	/api/timestamps	✅	List your timestamp batches
GET	/api/timestamps/:id	✅	Get details of a specific batch
GET	/api/timestamps/receipt/:id	🔸	Get receipt with verification data

Auth legend: ✅ = required, 🔸 = optional (returns more data if authenticated)

Create a Timestamp

POST /api/timestamps
Content-Type: application/json

Request Body

{
  "files": [
    {
      "name": "contract-v3.pdf",
      "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
      "size": 245780
    },
    {
      "name": "appendix-a.pdf",
      "hash": "d7a8fbb307d7809469ca9abcb0082e4f...",
      "size": 89420
    }
  ],
  "anchorMode": "instant",
  "lgUpgrade": false,
  "orgId": null
}

Parameters

Field	Type	Required	Description
files	array	Yes	Array of file objects with name, hash, size
files[].name	string	Yes	Original filename
files[].hash	string	Yes	SHA-256 hash of the file contents
files[].size	number	Yes	File size in bytes
anchorMode	string	Yes	"scheduled" or "instant"
lgUpgrade	boolean	No	Include the Legal-Grade upgrade for the batch
orgId	number	No	Organization ID (for team timestamps)

Response

{
  "jobId": 42,
  "batchId": "batch_abc123",
  "status": "pending",
  "anchorMode": "instant",
  "lgUpgrade": false,
  "files": [
    {
      "name": "contract-v3.pdf",
      "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
      "size": 245780
    },
    {
      "name": "appendix-a.pdf",
      "hash": "d7a8fbb307d7809469ca9abcb0082e4f...",
      "size": 89420
    }
  ],
  "creditsCharged": 4,
  "balanceRemaining": 838,
  "immediateAnchor": true,
  "txHash": "0x7f8a19c3b42e..."
}

Credit Costs

Operation	Cost	Notes
Scheduled timestamp	1 credit per file	Available to all users
Instant timestamp	2 credits per file	Requires active verification
Legal-Grade upgrade	Starter and Pro: 50 credits up to 25 files, then +2/file. Business: 25 credits up to 25 files, then +1/file. Enterprise: included.

The creditsCharged field in the response shows the total deducted. For the example above (2 instant files, no Legal-Grade), the charge is 4 credits.

Error Responses

// Insufficient credits
{
  "error": "Insufficient credits",
  "required": 4,
  "available": 0,
  "anchorMode": "instant"
}

// Invalid anchor mode
{
  "error": "Invalid anchor mode. Use 'scheduled' or 'instant'"
}

List Timestamp Jobs

GET /api/timestamps

Returns all timestamp jobs for the authenticated user, ordered by most recent first.

Response

[
  {
    "jobId": 42,
    "batchId": "batch_abc123",
    "status": "anchored",
    "anchorMode": "instant",
    "fileCount": 2,
    "createdAt": "2026-02-03T12:00:00Z",
    "anchoredAt": "2026-02-03T12:00:15Z",
    "txHash": "0x7f8a19c3b42e..."
  },
  {
    "jobId": 41,
    "batchId": "batch_xyz789",
    "status": "pending",
    "anchorMode": "scheduled",
    "fileCount": 10,
    "createdAt": "2026-02-03T11:30:00Z",
    "anchoredAt": null,
    "txHash": null
  }
]

Job Status Values

Status	Meaning
pending	Job created, waiting for blockchain anchoring
anchoring	Transaction submitted, waiting for confirmation
anchored	Successfully recorded on the blockchain
failed	Anchoring failed (extremely rare)

Get Job Details

GET /api/timestamps/:id

Returns full details for a specific timestamp job, including all files and anchoring metadata.

Response

{
  "jobId": 42,
  "batchId": "batch_abc123",
  "status": "anchored",
  "anchorMode": "instant",
  "lgUpgrade": false,
  "orgId": null,
  "files": [
    {
      "name": "contract-v3.pdf",
      "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
      "size": 245780,
      "merkleProof": ["0xabc...", "0xdef..."]
    }
  ],
  "merkleRoot": "0x123...",
  "txHash": "0x7f8a19c3b42e...",
  "blockNumber": 54321,
  "network": "amoy",
  "createdAt": "2026-02-03T12:00:00Z",
  "anchoredAt": "2026-02-03T12:00:15Z"
}

Get Receipt

GET /api/timestamps/receipt/:id

Returns the complete receipt with all verification data needed to independently prove the timestamp. This is the data that goes into PDF certificates.

The receipt includes the Merkle proof for each file, allowing third parties to mathematically verify that a specific file was part of the anchored batch.

Authentication

This endpoint accepts optional authentication (🔸). Unauthenticated requests return basic verification data. Authenticated requests return additional metadata like organization info and identity attestation status.

Workflow Examples

Single File (Instant)

// Hash the file client-side
const hash = await crypto.subtle.digest('SHA-256', fileBuffer);
const hashHex = Array.from(new Uint8Array(hash))
  .map(b => b.toString(16).padStart(2, '0'))
  .join('');

// Create timestamp
const res = await fetch('/api/timestamps', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    files: [{ name: file.name, hash: hashHex, size: file.size }],
    anchorMode: 'instant'
  })
});

const job = await res.json();
// txHash is available immediately for instant mode
console.log(job.txHash);

Batch Files (Scheduled)

// Hash multiple files
const files = await Promise.all(
  fileList.map(async (file) => ({
    name: file.name,
    hash: await computeSha256(file),
    size: file.size
  }))
);

// Send as batch — all share one Merkle root
const res = await fetch('/api/timestamps', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    files,
    anchorMode: 'scheduled'
  })
});

Related Guides

• API Verification Endpoints — verify hashes you’ve anchored
• API Credits Endpoints — check balances before timestamping
• Instant vs Scheduled Timestamps — choosing the right anchor mode
• Batch Timestamping — strategies for high-volume workflows