Documentation

go get github.com/tickstem/cron

export TICKSTEM_API_KEY=tsk_live_...

package main

import (
    "context"
    "log"
    "os"

    "github.com/tickstem/cron"
)

func main() {
    client := cron.New(os.Getenv("TICKSTEM_API_KEY"))

    job, err := client.Register(context.Background(), cron.RegisterParams{
        Name:     "daily-cleanup",
        Schedule: "0 2 * * *",   // every day at 02:00 UTC
        Endpoint: "https://yourapp.com/jobs/cleanup",
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("registered: %s  next run: %s", job.ID, job.NextRunAt)
}

go get github.com/tickstem/cron

// Minimal — points at https://api.tickstem.dev/v1
client := cron.New(os.Getenv("TICKSTEM_API_KEY"))

// With options
client := cron.New(apiKey,
    cron.WithBaseURL("http://localhost:8090/v1"), // local dev
)

job, err := client.Register(ctx, cron.RegisterParams{
    Name:        "send-digest",
    Description: "Weekly email digest to all users",
    Schedule:    "0 9 * * 1",                          // every Monday at 09:00 UTC
    Endpoint:    "https://yourapp.com/jobs/digest",
    Method:      "POST",                                // default
    Headers: map[string]string{
        "X-Tickstem-Secret": os.Getenv("CRON_SECRET"), // see Securing your endpoint
    },
    TimeoutSecs: 60,                                    // default: 30
})

// list all jobs
jobs, err := client.List(ctx)
for _, j := range jobs {
    fmt.Printf("%s  %s  next: %s\n", j.ID, j.Schedule, j.NextRunAt)
}

// get a single job
job, err := client.Get(ctx, "job_abc123")

job, err := client.Pause(ctx, jobID)
job, err := client.Resume(ctx, jobID)

err := client.Delete(ctx, jobID)

executions, err := client.Executions(ctx, jobID)
for _, e := range executions {
    fmt.Printf("%s  status=%s  duration=%dms\n",
        e.ScheduledAt.Format(time.RFC3339),
        e.Status,
        *e.DurationMs,
    )
}

job, err := client.Get(ctx, someID)
if err != nil {
    if cron.IsNotFound(err) {
        // job doesn't exist
    }
    if cron.IsUnauthorized(err) {
        // invalid or revoked API key
    }
    if cron.IsQuotaExceeded(err) {
        // monthly execution limit reached
        // upgrade at app.tickstem.dev/dashboard/billing
    }

    // inspect the raw API error
    var apiErr *cron.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode, apiErr.Message)
    }
}

openssl rand -hex 32

job, err := client.Register(ctx, cron.RegisterParams{
    Name:     "daily-cleanup",
    Schedule: "0 2 * * *",
    Endpoint: "https://yourapp.com/jobs/cleanup",
    Headers: map[string]string{
        "X-Tickstem-Secret": os.Getenv("CRON_SECRET"),
    },
})

func cronHandler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("X-Tickstem-Secret") != os.Getenv("CRON_SECRET") {
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }
    // ... do work
}

go install github.com/tickstem/cron/cmd/tsk-local@latest

tsk-local              # starts on :8090
tsk-local --port 9000  # custom port

client := cron.New("any-key",
    cron.WithBaseURL("http://localhost:8090/v1"))

┌───────── minute      (0–59)
│ ┌─────── hour        (0–23)
│ │ ┌───── day of month (1–31)
│ │ │ ┌─── month       (1–12)
│ │ │ │ ┌─ day of week  (0–6, Sun=0)
│ │ │ │ │
* * * * *

go get github.com/tickstem/verify

import "github.com/tickstem/verify"

client := verify.New(os.Getenv("TICKSTEM_API_KEY"))

result, err := client.Verify(ctx, "[email protected]")
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.Valid)      // true if safe to store
fmt.Println(result.Disposable) // true if throwaway address
fmt.Println(result.RoleBased)  // true if generic inbox
fmt.Println(result.MXFound)    // true if domain accepts mail
fmt.Println(result.Reason)     // human-readable explanation when invalid

result, err := client.Verify(ctx, email)
if err != nil {
    // network or quota error — fail open or closed depending on your policy
    return err
}

if !result.Valid {
    return fmt.Errorf("email address not accepted: %s", result.Reason)
}

if result.RoleBased {
    // warn but don't block — some teams share an inbox
    log.Printf("role-based address submitted: %s", email)
}

page, err := client.ListHistory(ctx, verify.ListHistoryParams{
    Limit:  50,
    Offset: 0,
})
if err != nil {
    log.Fatal(err)
}

for _, v := range page.Verifications {
    fmt.Printf("%s  valid=%v  disposable=%v  checked=%s\n",
        v.Email, v.Valid, v.Disposable, v.CreatedAt.Format(time.RFC3339))
}

result, err := client.Verify(ctx, email)
if err != nil {
    if verify.IsUnauthorized(err) {
        // invalid or revoked API key
    }
    if verify.IsQuotaExceeded(err) {
        // monthly verification limit reached
        // upgrade at app.tickstem.dev/dashboard/billing
    }

    var apiErr *verify.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode, apiErr.Message)
    }
}

curl -X POST https://api.tickstem.dev/v1/monitors \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.yourapp.com/health",
    "interval_secs": 60,
    "timeout_secs": 10
  }'

# pause
curl -X PATCH https://api.tickstem.dev/v1/monitors/{id}/pause \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

# resume
curl -X PATCH https://api.tickstem.dev/v1/monitors/{id}/resume \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

# delete (removes the monitor and all its check history)
curl -X DELETE https://api.tickstem.dev/v1/monitors/{id} \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

curl https://api.tickstem.dev/v1/monitors/{id}/checks \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

curl -X POST https://api.tickstem.dev/v1/heartbeats \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily backup",
    "interval_secs": 86400,
    "grace_secs": 3600
  }'

{
  "id": "hb_01abc...",
  "name": "daily backup",
  "token": "a3f8c2d1e4b5f6...",
  "interval_secs": 86400,
  "grace_secs": 3600,
  "status": "active"
}

# pause
curl -X PATCH https://api.tickstem.dev/v1/heartbeats/{id} \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

# resume
curl -X PATCH https://api.tickstem.dev/v1/heartbeats/{id} \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

# delete (removes the heartbeat and all ping history)
curl -X DELETE https://api.tickstem.dev/v1/heartbeats/{id} \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

# Replace the token below with your actual token from the dashboard
curl -X POST https://api.tickstem.dev/v1/heartbeats/a3f8c2d1e4b5f6.../ping

import "github.com/tickstem/heartbeat"

client := heartbeat.New(os.Getenv("TICKSTEM_API_KEY"))

// At the end of every successful run:
if err := client.Ping(ctx, token); err != nil {
    log.Println("heartbeat ping failed:", err) // non-fatal
}

npm install @tickstem/cron
# or
pnpm add @tickstem/cron

npm install @tickstem/verify
# or
pnpm add @tickstem/verify

npm install @tickstem/uptime
# or
pnpm add @tickstem/uptime

npm install @tickstem/heartbeat
# or
pnpm add @tickstem/heartbeat

import { CronClient } from "@tickstem/cron"

const cron = new CronClient(process.env.TICKSTEM_API_KEY)

const job = await cron.register({
  name: "daily-cleanup",
  schedule: "0 2 * * *",
  endpoint: "https://yourapp.com/jobs/cleanup",
})

console.log(job.id, job.next_run_at)

const jobs = await cron.list()
await cron.pause(jobId)
await cron.resume(jobId)
await cron.delete(jobId)

const executions = await cron.executions(jobId)
for (const e of executions) {
  console.log(e.id, e.status, e.duration_ms)
}

import { VerifyClient } from "@tickstem/verify"

const verify = new VerifyClient(process.env.TICKSTEM_API_KEY)

const result = await verify.verify("[email protected]")

if (!result.valid) {
  console.log(result.reason)
}
if (result.disposable) {
  return { error: "Disposable email addresses are not allowed." }
}
if (result.role_based) {
  return { error: "Please use a personal email address." }
}

const history = await verify.history()
for (const entry of history) {
  console.log(entry.email, entry.valid, entry.created_at)
}

import { UptimeClient } from "@tickstem/uptime"

const uptime = new UptimeClient(process.env.TICKSTEM_API_KEY)

// create
const monitor = await uptime.create({
  name: "Production API",
  url: "https://api.yourapp.com/health",
  interval_secs: 60,
  timeout_secs: 10,
})

// list all monitors
const monitors = await uptime.list()

// get a single monitor
const m = await uptime.get(monitor.id)

// pause / resume / delete
await uptime.pause(monitor.id)
await uptime.resume(monitor.id)
await uptime.delete(monitor.id)

const checks = await uptime.checks(monitor.id)

for (const check of checks) {
  console.log(check.status, check.duration_ms + "ms", check.checked_at)
}
// check.status: "up" | "down" | "timeout"
// check.status_code: number | null
// check.error: string

import { isUnauthorized, isQuotaExceeded, APIError } from "@tickstem/uptime"

try {
  await uptime.create({ name: "x", url: "https://x.com" })
} catch (err) {
  if (isQuotaExceeded(err)) {
    // monitor limit reached, or interval_secs below plan minimum
  }
  if (err instanceof APIError) {
    console.log(err.statusCode, err.message)
  }
}

import { HeartbeatClient } from "@tickstem/heartbeat"

const hb = new HeartbeatClient(process.env.TICKSTEM_API_KEY)

// create once — save the token somewhere permanent
const heartbeat = await hb.create({
  name: "daily backup",
  interval_secs: 86400,
  grace_secs: 3600,
})

// list all heartbeats
const all = await hb.list()

// get a single heartbeat
const h = await hb.get(heartbeat.id)

// update fields
await hb.update(heartbeat.id, { name: "weekly backup", interval_secs: 604800 })

// pause / resume / delete
await hb.pause(heartbeat.id)
await hb.resume(heartbeat.id)
await hb.delete(heartbeat.id)

// at the end of every successful job run — no API key needed
try {
  await hb.ping(heartbeat.token)
} catch (err) {
  console.error("heartbeat ping failed:", err) // non-fatal — don't block your job
}

const pings = await hb.pings(heartbeat.id, { limit: 50 })

for (const ping of pings) {
  console.log(ping.pinged_at)
}

import { isUnauthorized, isQuotaExceeded, APIError } from "@tickstem/cron"

try {
  await cron.list()
} catch (err) {
  if (isUnauthorized(err)) {
    // invalid or revoked API key
  }
  if (isQuotaExceeded(err)) {
    // monthly execution limit reached
    // upgrade at app.tickstem.dev/dashboard/billing
  }
  if (err instanceof APIError) {
    console.log(err.statusCode, err.message)
  }
}

pip install tickstem

from tickstem import CronClient, CronRegisterParams

client = CronClient(os.environ["TICKSTEM_API_KEY"])

job = client.register(CronRegisterParams(
    name="daily-cleanup",
    schedule="0 2 * * *",
    endpoint="https://yourapp.com/jobs/cleanup",
    method="POST",
    timeout_secs=60,
))

print(job.id, job.next_run_at)

jobs = client.list()
job  = client.get(job_id)

client.pause(job_id)
client.resume(job_id)
client.delete(job_id)

executions = client.executions(job_id)
for e in executions:
    print(e.status, e.duration_ms, "ms")

from tickstem import VerifyClient

client = VerifyClient(os.environ["TICKSTEM_API_KEY"])

result = client.verify("[email protected]")

if not result.valid:
    raise ValueError(f"Email not accepted: {result.reason}")
if result.disposable:
    raise ValueError("Disposable email addresses are not allowed.")
if result.role_based:
    print("Warning: role-based address")  # warn but don't block

history = client.history(limit=50)
for entry in history:
    print(entry.email, entry.valid, entry.created_at)

from tickstem import UptimeClient, UptimeCreateParams, Assertion

client = UptimeClient(os.environ["TICKSTEM_API_KEY"])

monitor = client.create(UptimeCreateParams(
    name="Production API",
    url="https://api.yourapp.com/health",
    interval_secs=60,
    assertions=[
        Assertion(source="status_code",   comparison="eq", target="200"),
        Assertion(source="response_time", comparison="lt", target="2000"),
    ],
))

monitors = client.list()
checks   = client.checks(monitor.id, limit=50)

for check in checks:
    print(check.status, check.duration_ms, "ms")

client.delete(monitor.id)

from tickstem import HeartbeatClient, HeartbeatCreateParams

client = HeartbeatClient(os.environ["TICKSTEM_API_KEY"])

hb = client.create(HeartbeatCreateParams(
    name="daily backup",
    interval_secs=86400,
    grace_secs=3600,
))

# At the end of every successful job run — no API key needed
try:
    client.ping(hb.token)
except Exception as e:
    print("heartbeat ping failed:", e)  # non-fatal

client.pause(hb.id)
client.resume(hb.id)
client.delete(hb.id)

pings = client.pings(hb.id, limit=50)

from tickstem import CronClient, APIError, is_unauthorized, is_quota_exceeded

client = CronClient(os.environ["TICKSTEM_API_KEY"])

try:
    jobs = client.list()
except APIError as err:
    if is_unauthorized(err):
        print("invalid or revoked API key")
    elif is_quota_exceeded(err):
        print("monthly limit reached — upgrade at app.tickstem.dev/dashboard/billing")
    else:
        print(f"error {err.status}: {err.message}")