Documentation

Everything you need to integrate Jobs Done into your application. Choose your preferred method: CLI, SDK, or direct API calls.

💻

CLI

The jobs_done CLI provides full control from your terminal, CI pipeline, or LLM agent. Every command outputs clean JSON — pipe it, parse it, automate it.

Installation

Linux — x86_64 & arm64

# x86_64 (amd64)
curl -fsSL https://github.com/jobsdone/cli/releases/latest/download/jobs_done-linux-amd64 \
    -o /usr/local/bin/jobs_done && chmod +x /usr/local/bin/jobs_done

# arm64
curl -fsSL https://github.com/jobsdone/cli/releases/latest/download/jobs_done-linux-arm64 \
    -o /usr/local/bin/jobs_done && chmod +x /usr/local/bin/jobs_done

jobs_done --version

macOS — Apple Silicon & Intel

# Apple Silicon (arm64)
curl -fsSL https://github.com/jobsdone/cli/releases/latest/download/jobs_done-darwin-arm64 \
    -o /usr/local/bin/jobs_done && chmod +x /usr/local/bin/jobs_done

# Intel (amd64)
curl -fsSL https://github.com/jobsdone/cli/releases/latest/download/jobs_done-darwin-amd64 \
    -o /usr/local/bin/jobs_done && chmod +x /usr/local/bin/jobs_done

jobs_done --version

Windows — PowerShell

# PowerShell — run as Administrator
Invoke-WebRequest -Uri "https://github.com/jobsdone/cli/releases/latest/download/jobs_done-windows-amd64.exe" `
    -OutFile "$env:ProgramFiles\jobs_done.exe"

# Add to PATH if needed, then verify
jobs_done --version

Quick Start

Terminal

# Register and get your API key
jobs_done user register "My App"
# Output:
# Name:    My App
# API Key: jd_sk_8f3e...c21a

# Set your API key (or export JOBSDONE_API_KEY)
export JOBSDONE_API_KEY="your-api-key"

# Schedule a daily cron (fires at 09:00 UTC every day)
jobs_done cron create \
    --name "daily-report" \
    --cron "0 9 * * *" \
    --url "https://your-domain.com/webhooks/daily"

# Enqueue a one-off job (idempotent — safe to call on every deploy)
jobs_done job enqueue \
    --id "send-welcome-email-user-123" \
    --url "https://your-domain.com/webhooks/welcome"

# List all your cron jobs
jobs_done cron list

# Pause and resume a cron job
jobs_done cron pause "daily-report"
jobs_done cron resume "daily-report"

🤖

LLM & agent-friendly

Every command outputs clean JSON — perfect for piping into jq, scripting in CI, or driving from an AI agent. Pass --output json to suppress decorative output. The CLI reads JOBSDONE_API_KEY from the environment — no interactive prompts in automation mode.

📦

SDKs

Official SDKs for the Jobs Done API. Select your language below to see install instructions, authentication, and a complete code example.

Official Node.js/TypeScript SDK. Type-safe access to all endpoints with native fetch.

Install

npm

npm install jobsdone-sdk

Authentication

.env / Environment

JOBSDONE_API_KEY=your-api-key
JOBSDONE_BASE_URL=https://api.jobsdone.dev  # optional, defaults to http://localhost:4000

Complete Example

This example demonstrates scheduling a daily report cron, enqueueing a one-off job, removing a tenant's schedules using a regex pattern, and handling a webhook.

TypeScript

import { createClient } from 'jobsdone-sdk';

const client = createClient({
  apiKey: process.env.JOBSDONE_API_KEY!,
  baseUrl: process.env.JOBSDONE_BASE_URL, // optional, defaults to http://localhost:4000
});

// ── 1. Schedule a daily report cron for a specific tenant ──────────────────
const tenantId = 'acme-corp';

const cron = await client.createCron({
  logicId: `daily-report-${tenantId}`,
  name: `Daily Report: ${tenantId}`,
  cronExpression: '0 9 * * *',           // 09:00 UTC every day
  webhookUrl: 'https://your-domain.com/webhooks/daily-report',
  body: {
    tenantId,
    reportType: 'daily-summary',
    format: 'json',
  },
  maxAttempts: 3,
});
console.log(`Cron scheduled: ${cron.logicId}`);

// ── 2. Enqueue a one-off welcome email job ─────────────────────────────────
// Idempotent: calling this multiple times with the same logic_id is safe.
const job = await client.enqueue({
  logicId: `welcome-email-${tenantId}`,
  description: {
    webhook: 'https://your-domain.com/webhooks/welcome',
    userId: tenantId,
  },
});
console.log(`Job enqueued: id=${job.id}, state=${job.state}`);

// ── 3. Remove all schedules for a tenant using regex ───────────────────────
// The API supports SQL LIKE patterns in the logic_id filter.
// "%" matches any sequence of characters.
const allJobs = await client.listJobs();
const tenantJobs = allJobs.filter(
  (j) => j.logicId != null && j.logicId.startsWith(`daily-report-${tenantId}`)
);

for (const j of tenantJobs) {
  await client.cancelJob(j.logicId!);
  console.log(`Cancelled job: ${j.logicId}`);
}

// ── 4. Pause and resume a cron ──────────────────────────────────────────────
const paused = await client.pauseCron(`daily-report-${tenantId}`);
console.log(`Cron paused: active=${paused.active}`);

// Later, resume it:
const resumed = await client.resumeCron(`daily-report-${tenantId}`);
console.log(`Cron resumed: active=${resumed.active}`);

🔑

Authentication

Set your API key via the JOBSDONE_API_KEY environment variable, or pass it directly to createClient({ apiKey: 'your-key' }).

Official Python SDK. Full type hints and synchronous httpx client.

Install

pip

pip install jobsdone-sdk

Authentication

.env / Environment

JOBSDONE_API_KEY=your-api-key
JOBSDONE_BASE_URL=https://api.jobsdone.dev  # optional, defaults to http://localhost:4000

Complete Example

This example demonstrates scheduling a daily report cron, enqueueing a one-off job, removing a tenant's schedules using a regex pattern, and handling a webhook.

Python

import os
from jobs_done import create_client, CronJobCreateRequest, EnqueueRequest

client = create_client({
    "api_key": os.environ["JOBSDONE_API_KEY"],
    "base_url": os.environ.get("JOBSDONE_BASE_URL", "http://localhost:4000"),
})

# ── 1. Schedule a daily report cron for a specific tenant ──────────────────
tenant_id = "acme-corp"

cron = client.create_cron(CronJobCreateRequest(
    logic_id=f"daily-report-{tenant_id}",
    name=f"Daily Report: {tenant_id}",
    cron_expression="0 9 * * *",           # 09:00 UTC every day
    webhook_url="https://your-domain.com/webhooks/daily-report",
    body={
        "tenant_id": tenant_id,
        "report_type": "daily-summary",
        "format": "json",
    },
    max_attempts=3,
))
print(f"Cron scheduled: {cron.logic_id}")

# ── 2. Enqueue a one-off welcome email job ─────────────────────────────────
# Idempotent: calling this multiple times with the same logic_id is safe.
result = client.enqueue(EnqueueRequest(
    logic_id=f"welcome-email-{tenant_id}",
    description={
        "webhook": "https://your-domain.com/webhooks/welcome",
        "user_id": tenant_id,
    },
))
print(f"Job enqueued: id={result.id}, state={result.state}")

# ── 3. Remove all schedules for a tenant using regex ───────────────────────
# Filter jobs in-memory; the API returns all jobs for the user.
all_jobs = client.list_jobs()
tenant_jobs = [j for j in all_jobs if j.logic_id and j.logic_id.startswith(f"daily-report-{tenant_id}")]

for job in tenant_jobs:
    client.cancel_job(job.logic_id)
    print(f"Cancelled job: {job.logic_id}")

# ── 4. Pause and resume a cron ──────────────────────────────────────────────
paused = client.pause_cron(f"daily-report-{tenant_id}")
print(f"Cron paused: active={paused.active}")

# Later, resume it:
resumed = client.resume_cron(f"daily-report-{tenant_id}")
print(f"Cron resumed: active={resumed.active}")

🔑

Authentication

Set your API key via the JOBSDONE_API_KEY environment variable, or pass it directly to create_client({"api_key": "your-key"}).

Official Ruby SDK. Uses Faraday for HTTP and follows Ruby idioms.

Install

gem

gem install jobs_done

Authentication

.env / Environment

JOBSDONE_API_KEY=your-api-key
JOBSDONE_BASE_URL=https://api.jobsdone.dev  # optional, defaults to http://localhost:4000

Complete Example

This example demonstrates scheduling a daily report cron, enqueueing a one-off job, removing a tenant's schedules using a regex pattern, and handling a webhook.

Ruby

require 'jobs_done'

client = JobsDone.create_client(
  api_key: ENV['JOBSDONE_API_KEY'],
  base_url: ENV['JOBSDONE_BASE_URL'] || 'http://localhost:4000'
)

# ── 1. Schedule a daily report cron for a specific tenant ──────────────────
tenant_id = 'acme-corp'

cron = client.create_cron(
  logic_id: "daily-report-#{tenant_id}",
  name: "Daily Report: #{tenant_id}",
  cron_expression: '0 9 * * *',           # 09:00 UTC every day
  webhook_url: 'https://your-domain.com/webhooks/daily-report',
  body: {
    tenant_id: tenant_id,
    report_type: 'daily-summary',
    format: 'json',
  },
  max_attempts: 3
)
puts "Cron scheduled: #{cron.logic_id}"

# ── 2. Enqueue a one-off welcome email job ─────────────────────────────────
# Idempotent: calling this multiple times with the same logic_id is safe.
result = client.enqueue(
  logic_id: "welcome-email-#{tenant_id}",
  description: {
    webhook: 'https://your-domain.com/webhooks/welcome',
    user_id: tenant_id
  }
)
puts "Job enqueued: id=#{result.id}, state=#{result.state}"

# ── 3. Remove all schedules for a tenant using regex ───────────────────────
# Filter jobs in-memory; the API returns all jobs for the user.
all_jobs = client.list_jobs
tenant_jobs = all_jobs.select do |j|
  j.logic_id&.start_with?("daily-report-#{tenant_id}")
end

tenant_jobs.each do |job|
  client.cancel_job(job.logic_id)
  puts "Cancelled job: #{job.logic_id}"
end

# ── 4. Pause and resume a cron ──────────────────────────────────────────────
paused = client.pause_cron("daily-report-#{tenant_id}")
puts "Cron paused: active=#{paused.active}"

# Later, resume it:
resumed = client.resume_cron("daily-report-#{tenant_id}")
puts "Cron resumed: active=#{resumed.active}"

🔑

Authentication

Set your API key via the JOBSDONE_API_KEY environment variable, or pass it directly to JobsDone.create_client(api_key: 'your-key').

Official Go SDK. Idiomatic Go with context support and typed errors.

Install

go get

go get jobsdone.dev/sdk/go

Authentication

Environment

export JOBSDONE_API_KEY=your-api-key
export JOBSDONE_BASE_URL=https://api.jobsdone.dev  # optional, defaults to http://localhost:4000

Complete Example

This example demonstrates scheduling a daily report cron, enqueueing a one-off job, removing a tenant's schedules using a regex pattern, and handling a webhook.

package main

import (
	"context"
	"fmt"
	"os"
	"strings"

	jobsdone "jobsdone.dev/sdk/go"
)

func main() {
	client := jobsdone.NewClient(jobsdone.ClientConfig{
		APIKey:  os.Getenv("JOBSDONE_API_KEY"),
		BaseURL: os.Getenv("JOBSDONE_BASE_URL"), // optional, defaults to http://localhost:4000
	})

	ctx := context.Background()
	tenantID := "acme-corp"

	// ── 1. Schedule a daily report cron for a specific tenant ─────────────
	cron, err := client.CreateCron(ctx, jobsdone.CronJobCreateRequest{
		LogicID:        fmt.Sprintf("daily-report-%s", tenantID),
		Name:           fmt.Sprintf("Daily Report: %s", tenantID),
		CronExpression: "0 9 * * *", // 09:00 UTC every day
		WebhookURL:     "https://your-domain.com/webhooks/daily-report",
		Body: map[string]any{
			"tenant_id":   tenantID,
			"report_type": "daily-summary",
			"format":      "json",
		},
		MaxAttempts: 3,
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Cron scheduled: %s\n", cron.LogicID)

	// ── 2. Enqueue a one-off welcome email job ─────────────────────────────
	// Idempotent: calling this multiple times with the same logic_id is safe.
	result, err := client.Enqueue(ctx, jobsdone.EnqueueRequest{
		LogicID:     fmt.Sprintf("welcome-email-%s", tenantID),
		Description: map[string]any{"webhook": "https://your-domain.com/webhooks/welcome", "user_id": tenantID},
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Job enqueued: id=%d, state=%s\n", result.ID, result.State)

	// ── 3. Remove all schedules for a tenant using regex ──────────────────
	// The API supports SQL LIKE patterns via the logic_id query parameter.
	// A trailing "%" matches any suffix.
	jobs, err := client.ListJobs(ctx, &jobsdone.JobListOptions{
		LogicID: fmt.Sprintf("daily-report-%s%%", tenantID),
	})
	if err != nil {
		panic(err)
	}

	for _, job := range jobs {
		if job.LogicID == nil {
			continue
		}
		// The API already filtered by prefix, but we double-check:
		if !strings.HasPrefix(*job.LogicID, fmt.Sprintf("daily-report-%s", tenantID)) {
			continue
		}
		if err := client.CancelJob(ctx, *job.LogicID); err != nil {
			panic(err)
		}
		fmt.Printf("Cancelled job: %s\n", *job.LogicID)
	}

	// ── 4. Pause and resume a cron ─────────────────────────────────────────
	paused, err := client.PauseCron(ctx, fmt.Sprintf("daily-report-%s", tenantID))
	if err != nil {
		panic(err)
	}
	fmt.Printf("Cron paused: active=%v\n", paused.Active)

	// Later, resume it:
	resumed, err := client.ResumeCron(ctx, fmt.Sprintf("daily-report-%s", tenantID))
	if err != nil {
		panic(err)
	}
	fmt.Printf("Cron resumed: active=%v\n", resumed.Active)
}

🔑

Authentication

Set your API key via the JOBSDONE_API_KEY environment variable, or pass it directly to NewClient(ClientConfig{APIKey: "your-key"}).

🪝

Webhooks

When a job fires, Jobs Done sends an HTTP POST to your configured webhook_url. The request body contains the body you stored when creating the cron (or the description for one-off enqueued jobs).

Webhook Request

POST /your-webhook-endpoint

# Example webhook request from Jobs Done to your endpoint:
POST /webhooks/daily-report HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-JobsDone-Signature: sha256=abc123...        # future: HMAC signature for verification
X-JobsDone-Logic-ID: daily-report-acme-corp
X-JobsDone-Cron-ID: 42

{
  "tenant_id": "acme-corp",
  "report_type": "daily-summary",
  "format": "json"
}

Response & Retries

Your Webhook Handler

// Return 2xx to acknowledge. Jobs Done retries on non-2xx responses.
// The number of retries is controlled by max_attempts (default: 3).

app.post('/webhooks/daily-report', async (req, res) => {
  const { tenant_id, report_type } = req.body;

  // Process the report...
  await generateReport({ tenantId: tenant_id, type: report_type });

  res.status(200).json({ ok: true });
});

⚠️

Webhook Security

Configure your webhook endpoint to only accept requests from the Jobs Done domain (api.jobsdone.dev). This prevents spoofed job executions. Check the X-JobsDone-Signature header (future) to verify authenticity.

📖

OpenAPI Specification

The full OpenAPI 3.0 specification is available at GET /api/openapi. Use the interactive SwaggerUI to explore all endpoints, request/response schemas, and try out API calls directly.

GET /api/openapi

Returns the complete OpenAPI 3.0 specification as JSON. Use this to generate SDKs or integrate with tools like Postman.

View OpenAPI JSON

GET /swaggerui

Interactive API documentation. Explore all endpoints, see request/response schemas, and test API calls directly from the browser.

Open SwaggerUI