temporalBLOCK Guide

Authentication

Every request requires an X-API-Key header. Get your key from the dashboard. Keys follow the format tblk_(live|test)_…. The key goes in the X-API-Key header — not Authorization: Bearer. Sending it as a Bearer token returns a 401 with code WRONG_AUTH_HEADER. A missing or invalid key returns 401 INVALID_API_KEY.

// All requests — add this header
fetch("https://api.temporalblock.com/api/v1/calibrate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TBLK_API_KEY,  // never hardcode
  },
  body: JSON.stringify({ timezone: "America/New_York" }),
})

PAYG past included quota: snippet $0.02 · briefing $0.04 · deep $0.10.

Calibrate

POST /api/v1/calibrate returns a prompt block that anchors your LLM to the certified current date, time, and the boundary of its training data. Call this before every conversation that involves any time-sensitive question.

// Detect timezone in the browser or React Native
const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// e.g. "America/New_York", "America/Chicago", "America/Los_Angeles",
//      "America/Denver", "Europe/London", "Asia/Tokyo"

const { calibrateBlock } = await fetch(
  "https://api.temporalblock.com/api/v1/calibrate",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.TBLK_API_KEY,
    },
    body: JSON.stringify({ timezone }),
  }
).then((r) => r.json());

// Prepend calibrateBlock to your system prompt — it's a ready-made string
const systemPrompt = calibrateBlock + "\n\n" + yourExistingSystemPrompt;

Bridge & Full

Bridge reconciles your model's knowledge with the live web. POST /api/v1/bridge runs a real-time search on your behalf and returns a reconciliation block. POST /api/v1/full combines calibrate + bridge into one round trip — the most common choice.

// /v1/full = calibrate + bridge in one call
// BYO provider key: pass your own Brave / Perplexity / OpenAI key
const result = await fetch("https://api.temporalblock.com/api/v1/full", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TBLK_API_KEY,
  },
  body: JSON.stringify({
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    syncTier: "snippet",         // "snippet" | "briefing" | "deep"
    syncProvider: "perplexity",  // or "brave" | "serpapi" | "openai" | "anthropic" | "google"
    syncApiKey: process.env.PERPLEXITY_API_KEY,
  }),
}).then((r) => r.json());

// result.calibrateBlock  → prepend to system prompt
// result.bridgeBlock     → append to system prompt (or inject as a user turn)
// result.meta            → anchor confidence, Spiral coordinate, tier info

curl "$BASE_URL/api/v1/events?limit=25" \
  -H "X-API-Key: $TEMPORALBLOCK_API_KEY"

// Free bridge + Spiral preview on /v1/calibrate (all tiers, no extra charge)
const result = await fetch("https://api.temporalblock.com/api/v1/calibrate", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": process.env.TBLK_API_KEY },
  body: JSON.stringify({
    model: "gpt-4o",
    includeBridgePreview: true,
    bridgePreviewQuery: "What is the current state of quantum computing hardware?",
  }),
}).then((r) => r.json());

// result.meta.bridgePreview → { query, briefing, citations, evidence }
//   omitted (not a 4xx) when rate-limited or operator key unavailable
// result.meta.spiral         → free basic Spiral preview, all tiers
// result.meta.spiralCoordinate → { scales, sin, cos } free on all tiers

Tools manifest for LLM agents

GET /api/v1/tools returns an OpenAI or Anthropic function-calling manifest of every API operation your key is entitled to invoke. Pass it directly to your LLM — the model then calls the right endpoints itself.

// Anthropic format — use ?format=anthropic so Claude sees short names
// ("calibrate", "create_skill") instead of the long internal identifiers
const { tools, baseUrl } = await fetch(
  "https://api.temporalblock.com/api/v1/tools?format=anthropic",
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());

// tools[n] → { name, description, input_schema, displayName }
// Pass directly to anthropic.messages.create({ tools, … })

import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();

const msg = await anthropic.messages.create({
  model: "claude-opus-4-5",
  max_tokens: 1024,
  tools,
  messages: [{ role: "user", content: "What time is it for me?" }],
});

// OpenAI format (default) — tools[n].function.name is the stable dispatch key
const { tools, baseUrl } = await fetch(
  "https://api.temporalblock.com/api/v1/tools",
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());

// Build a dispatch map once — key is function.name
const byName = Object.fromEntries(tools.map((t) => [t.function.name, t]));

// Execute one tool_call returned by the LLM
async function executeTool(name: string, args: Record<string, unknown>) {
  const t = byName[name];
  let path = t.path;
  const body: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(args)) {
    if (path.includes(`{${k}}`)) {
      path = path.replace(`{${k}}`, String(v));
    } else {
      body[k] = v;
    }
  }
  const isRead = t.method === "GET" || t.method === "DELETE";
  return fetch(`${baseUrl}${path}`, {
    method: t.method,
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.TBLK_API_KEY!,
    },
    body: isRead ? undefined : JSON.stringify(body),
  }).then((r) => r.json());
}

Timers, alarms & schedules (Skills)

POST /api/v1/skills creates a skill — a row with a trigger and a webhook URL. When the trigger fires, the API POSTs a signed payload to your endpoint. Use this for timers, alarms, reminders, and recurring schedules.

// 2-minute countdown timer
const { skill, webhookSecret } = await fetch(
  "https://api.temporalblock.com/api/v1/skills",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.TBLK_API_KEY,
    },
    body: JSON.stringify({
      label: "2 minute timer",
      trigger: { kind: "simple", everyMs: 120_000 },  // 2 min = 120,000 ms
      webhookUrl: "https://your-app.example.com/webhook",
    }),
  }
).then((r) => r.json());

// ⚠ webhookSecret is shown EXACTLY ONCE — save it now.
// It is the signing secret for verifying incoming webhook payloads.

// Alarm at a specific UTC instant
trigger: { kind: "simple", atUtcMs: Date.now() + 30 * 60_000 }  // 30 min from now

// Recurring — every hour, forever
trigger: { kind: "simple", everyMs: 3_600_000, repeat: true }

// Recurring with a cap — fire 12 times then stop
trigger: { kind: "simple", everyMs: 3_600_000, repeat: true, maxFires: 12 }

// Common everyMs values:
// 1 minute  =  60_000
// 5 minutes = 300_000
// 2 hours   = 7_200_000
// 1 day     = 86_400_000

// Verify an incoming webhook — same derivation for both signature headers
import { createHash, createHmac } from "node:crypto";

function verifyWebhook(req: Request, rawSecret: string): boolean {
  const sigHeader = req.headers.get("X-Tblk-Signature") ?? "";
  const [scheme, incoming] = sigHeader.split("=", 2);
  if (scheme !== "sha256" || !incoming) return false;

  const body = await req.text();
  const signingKey = createHash("sha256").update(rawSecret).digest("hex");
  const expected = createHmac("sha256", signingKey).update(body).digest("hex");
  return expected === incoming;
  // Also check X-Tblk-Account-Signature using your stable account key
}

Retry schedule on non-2xx: 1 min → 5 min → 30 min → 2 h → 12 h (5 total). Return 2xx immediately — do not block on downstream processing.

Manual arm — a "press here to start" button

Creating a skill and starting its countdown are usually the same instant. Manual arm splits them: create the skill ahead of time, unarmed, then start the clock the moment a real person clicks a button in your own UI — not when your server happened to call the API. Reusable pattern: create a skill, render a chip Unarmed with a button, and flip it to Armed on click.

1. Server-side: create the skill unarmed

// Your backend — needs your real API key. Do this ahead of the button render,
// e.g. as soon as the chat turn that offers "press here to start" is generated.
const { skill, webhookSecret, armToken, armExpiresAtMs } = await fetch(
  "https://api.temporalblock.com/api/v1/skills",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.TBLK_API_KEY,
    },
    body: JSON.stringify({
      label: "10 minute focus timer",
      trigger: { kind: "after", rung: "min", fractionOfCycle: 10 / 60 },
      webhookUrl: "https://your-app.example.com/webhook",
      armPolicy: "manual",
    }),
  }
).then((r) => r.json());

// skill.status === "unarmed" — the 10-minute clock has NOT started yet.
// Send skill.id + armToken down to the browser. Never send X-API-Key to the browser.

2. Browser: chip + button, wired to the arm endpoint

// Reusable vanilla-JS pattern — drop into any chat/UI framework.
// No API key here: armToken is the only credential this call needs.
async function armSkill(skillId, armToken, chipEl) {
  chipEl.textContent = "Arming…";
  const res = await fetch(
    `https://api.temporalblock.com/api/v1/skills/${skillId}/arm`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ armToken }),
    }
  );
  if (res.status === 200) {
    chipEl.textContent = "Armed — running";     // countdown starts NOW
  } else if (res.status === 410) {
    chipEl.textContent = "Expired — create a new one";
  } else if (res.status === 409) {
    chipEl.textContent = "Already armed";
  } else {
    chipEl.textContent = "Could not arm — try again";
  }
}

// <button onclick="armSkill(skillId, armToken, chip)">Start timer</button>
// <span id="chip">Unarmed</span>

The arm call is meant for a human's own click — never have an LLM or agent call it on its own. Discovery tools (GET /v1/tools) do not list it for that reason; only armPolicy on create is agent-visible.

Spiral Block

The Temporal Spiral is a 12-rung coordinate system that maps any UTC instant to a phase in [0, 1) on every time scale from microseconds to millennia. GET /api/v1/spiral returns the live-anchored coordinate for the current moment.

// Live Spiral coordinate for right now
const coordinate = await fetch(
  "https://api.temporalblock.com/api/v1/spiral",
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());

// coordinate.scales → { us, ms, s, min, hr, day, wk, mo, yr, dec, cen, mil }
// Each scale: { rung, phase, sin, cos, source, cycleStartUtcMs, cycleEndUtcMs }
// coordinate.spiralReadable → human string, e.g. "2026-hr-0.648"

// Pin to a specific past or future moment with atUtcMs:
const pinned = await fetch(
  "https://api.temporalblock.com/api/v1/spiral?atUtcMs=1780300000000",
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());

Sub-second rungs (us, ms) are library-grounded — derived from system clock without NTP correction. All other rungs are anchored to the certified NTP/NTS ensemble. Full Spiral docs →

body: JSON.stringify({
  includeSpiralBlock: true,
  // ... other /v1/full fields
})

// result.spiralBlock                         → system-prompt-ready phase string (Standard+)
// result.meta.spiral.confidenceMs            → scalar confidence in ms (Standard+)
// result.meta.spiral.confidenceBreakdown     → { fromLastSyncMs, sampleDispersionMs, toNextSyncMs } (Pro+)
// result.meta.spiral.syncCyclePhase          → { msSinceLastSync, msUntilNextSync, fractionThroughCycle } (Pro+)
// result.meta.spiral.upgradeReason           → plain-language upsell hint (Lite only)

State KV

A simple key-value store scoped to your API key. Store any JSON value under a string key. Use it as agent memory, or as the trigger condition for a whenStateMatches skill.

const BASE = "https://api.temporalblock.com/api/v1/state";
const headers = { "Content-Type": "application/json", "X-API-Key": process.env.TBLK_API_KEY };

// Write a value (Standard+)
await fetch(`${BASE}/session-mode`, {
  method: "PUT",
  headers,
  body: JSON.stringify({ value: "focus" }),
});

// Read a value (all tiers)
const { value } = await fetch(`${BASE}/session-mode`, { headers }).then((r) => r.json());

// Delete
await fetch(`${BASE}/session-mode`, { method: "DELETE", headers });

// List all keys
const { keys } = await fetch(`${BASE}?prefix=session`, { headers }).then((r) => r.json());

// Trigger a skill when the value becomes "urgent":
trigger: {
  kind: "whenStateMatches",
  stateKey: "session-mode",
  condition: { eq: "urgent" },
}

Causal Block

Strict event ordering across every node — useful for distributed systems that need a single authoritative "happened-before" relationship regardless of network clock drift. Three endpoints: /now, /merge, and /compare.

const BASE = "https://api.temporalblock.com/api/v1/causal";
const H = { "Content-Type": "application/json", "X-API-Key": process.env.TBLK_API_KEY };

// Stamp the current moment — returns a causal clock vector
const { clock } = await fetch(`${BASE}/now`, { method: "POST", headers: H }).then(r => r.json());

// Merge two clocks from different nodes (returns the union — the "latest" happened-before)
const merged = await fetch(`${BASE}/merge`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ clocks: [clockA, clockB] }),
}).then(r => r.json());

// Compare two clocks — returns "before" | "after" | "concurrent"
// (Pro+ only)
const { relation } = await fetch(`${BASE}/compare`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ a: clockA, b: clockB }),
}).then(r => r.json());

/now and /merge are trickle-limited on Lite. /compare requires Pro+. Full Causal Block docs →

Output Pacing

Track your model's token output rate against an authoritative Spiral-anchored clock. The API supplies elapsed time, rate, and estimated finish — it does not count tokens itself. Use it to detect when a model is running slow, stalled, or ahead of a budget.

const BASE = "https://api.temporalblock.com/api/v1/pacing";
const H = { "Content-Type": "application/json", "X-API-Key": process.env.TBLK_API_KEY };

// 1. Open a session at the start of the LLM response stream
const { session } = await fetch(`${BASE}/sessions`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ model: "claude-opus-4-5", targetTokensPerSec: 40 }),
}).then(r => r.json());
const sessionId = session.id;

// 2. Send tick events as tokens arrive — include your own token count
await fetch(`${BASE}/sessions/${sessionId}/ticks`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ tokensSinceLastTick: 32 }),
}).then(r => r.json());
// Response: { elapsedMs, tokensPerSec, estimatedFinishMs, spiralCoordinate, … }

// 3. Close the session when the stream ends
await fetch(`${BASE}/sessions/${sessionId}/close`, { method: "POST", headers: H });

// Stateless estimate — no session required (all tiers)
const estimate = await fetch(`${BASE}/estimate?tokens=500&model=claude-opus-4-5`, {
  headers: H,
}).then(r => r.json());

Live sessions require Standard+. The stateless /estimate endpoint is available on all tiers. Full Output Pacing docs →

Common pitfalls

// ✗ Wrong — returns UTC, LLM will show the wrong hour
body: JSON.stringify({})

// ✓ Correct — always detect and forward the user's timezone
const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
body: JSON.stringify({ timezone })

// If timezone is unknowable, pass "UTC" explicitly —
// the block labels it UTC so the LLM doesn't misrepresent it
body: JSON.stringify({ timezone: "UTC" })

// Refresh at bot startup — not at build time
const { tools } = await fetch(
  "https://api.temporalblock.com/api/v1/tools?format=anthropic",
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());
// The June 2026 manifest says "Set a timer, alarm, reminder…" in the description.
// A cached pre-June manifest may not.

// ✗ Wrong — durationMs is a rejected legacy field
trigger: { kind: "after", durationMs: 120000 }

// ✓ Correct — simple trigger with everyMs
trigger: { kind: "simple", everyMs: 120000 }