SDK API Reference

CloudClient

import { CloudClient } from "@cronlet/sdk";

const cronlet = new CloudClient({
  apiKey: process.env.CRONLET_API_KEY!,
  baseUrl: process.env.CRONLET_BASE_URL,
  orgId: "org_123",
  userId: "user_456",
  role: "admin",
});

Constructor options

interface CloudClientOptions {
  apiKey: string;
  baseUrl?: string;
  orgId?: string;
  userId?: string;
  role?: "viewer" | "member" | "admin" | "owner";
}

tasks

tasks.create(input, createdBy?)

Creates a task.

source is not a caller-managed field in normal SDK usage:

• direct SDK calls are sent with source: "sdk"
• calls made through the agent/MCP path with createdBy.type === "agent" are sent with source: "mcp"

const task = await cronlet.tasks.create(
  {
    name: "Daily report",
    handler: {
      type: "webhook",
      url: "https://api.example.com/report",
      method: "POST",
    },
    schedule: {
      type: "daily",
      times: ["09:00"],
    },
    timezone: "UTC",
    retryAttempts: 1,
    retryBackoff: "linear",
    retryDelay: "1s",
    timeout: "30s",
    active: true,
  },
  {
    type: "agent",
    id: "assistant_123",
    name: "support-agent",
  }
);

Input shape:

interface TaskCreateRequest {
  name: string;
  description?: string;
  handler: HandlerConfigInput;
  schedule: ScheduleConfigInput | string;
  timezone?: string;
  retryAttempts?: number;
  retryBackoff?: "linear" | "exponential";
  retryDelay?: string;
  timeout?: string;
  active?: boolean;
  callbackUrl?: string;
  metadata?: Record<string, unknown>;
  maxRuns?: number;
  expiresAt?: string;
}

tasks.list()

const tasks = await cronlet.tasks.list();

tasks.get(taskId)

const task = await cronlet.tasks.get(taskId);

tasks.patch(taskId, input)

await cronlet.tasks.patch(taskId, {
  active: false,
  maxRuns: null,
  callbackUrl: null,
});

tasks.delete(taskId)

await cronlet.tasks.delete(taskId);

tasks.trigger(taskId)

const run = await cronlet.tasks.trigger(taskId);

tasks.pause(taskId)

Equivalent to patch(taskId, { active: false }).

tasks.resume(taskId)

Equivalent to patch(taskId, { active: true }).

runs

runs.list(taskId?, limit?)

const allRuns = await cronlet.runs.list();
const taskRuns = await cronlet.runs.list(taskId, 20);

runs.get(runId)

const run = await cronlet.runs.get(runId);

secrets

secrets.list()

const secrets = await cronlet.secrets.list();

secrets.create(input)

await cronlet.secrets.create({
  name: "SLACK_TOKEN",
  value: "xoxb-...",
});

secrets.delete(name)

await cronlet.secrets.delete("SLACK_TOKEN");

usage

usage.get()

const usage = await cronlet.usage.get();

audit

audit.record(input)

This is exposed by the SDK but documented as internal-use oriented.

await cronlet.audit.record({
  action: "task.created",
  targetType: "task",
  targetId: "task_123",
  actorType: "agent",
  actorId: "assistant_456",
  metadata: {
    source: "agent-loop",
  },
});

Return types you will see often

TaskRecord

Notable fields:

• id
• orgId
• name
• description
• source
• handlerType
• handlerConfig
• scheduleType
• scheduleConfig
• timezone
• nextRunAt
• retryAttempts
• retryBackoff
• retryDelay
• timeout
• active
• createdBy
• callbackUrl
• metadata
• maxRuns
• expiresAt
• runCount
• createdAt
• updatedAt

source is one of:

• "dashboard"
• "mcp"
• "sdk"

Reference shape:

interface TaskRecord {
  id: string;
  orgId: string;
  name: string;
  description: string | null;
  source: "dashboard" | "mcp" | "sdk";
  handlerType: HandlerType;
  handlerConfig: HandlerConfig;
  scheduleType: ScheduleType;
  scheduleConfig: ScheduleConfig;
  timezone: string;
  nextRunAt: string | null;
  retryAttempts: number;
  retryBackoff: "linear" | "exponential";
  retryDelay: string;
  timeout: string;
  active: boolean;
  createdBy: CreatedBy | null;
  callbackUrl: string | null;
  metadata: Record<string, unknown> | null;
  maxRuns: number | null;
  expiresAt: string | null;
  runCount: number;
  createdAt: string;
  updatedAt: string;
}

RunRecord

Notable fields:

• id
• taskId
• status
• trigger
• attempt
• durationMs
• output
• logs
• errorMessage

Tool exports

import {
  cronletTools,
  openaiTools,
  anthropicTools,
  langchainTools,
  createToolHandler,
} from "@cronlet/sdk";

cronletTools

cronletTools.openai
cronletTools.anthropic
cronletTools.langchain
cronletTools.definitions

createToolHandler(client)

Returns helpers for:

• execute(name, args)
• handleOpenAI(toolCall)
• handleAnthropic(toolUse)

CronletError

import { CronletError } from "@cronlet/sdk";

try {
  await cronlet.tasks.get("missing");
} catch (error) {
  if (error instanceof CronletError) {
    console.log(error.message);
    console.log(error.code);
    console.log(error.status);
  }
}

Current behavioral notes

• CloudClient assumes JSON API responses and throws CronletError on non-OK payloads.
• tasks.create() and tasks.patch() accept schedule objects and supported schedule strings.

REST reference

GET /v1/org-status

Returns a viewer-readable org setup snapshot used by the dashboard.

Response shape:

interface OrgStatusSnapshot {
  hasApiKeys: boolean;
}

Current fields:

• hasApiKeys: true if the organization has at least one API key configured
• string schedules are parsed client-side into ScheduleConfig objects before request serialization.
• naive once datetime strings are interpreted as UTC unless the string includes timezone information.
• Use the SDK from server-side code only.

Reference types

For exact TypeScript shapes, see:

• packages/cloud-sdk/src/client.ts
• packages/cloud-sdk/src/tools.ts
• packages/cloud-shared/src/types.ts
• packages/cloud-shared/src/schemas.ts