skopik

Automations & Schedules

Automations are standing triggers that automatically open new Sessions or send turns into persistent Sessions on a defined schedule. Use them for daily code audits, periodic triage, recurring report generation, and data synchronization.

Trigger schedules

Automations support standard 5-field cron expressions, recurring intervals, and one-shot execution timestamps:

Trigger Type Format Example Behavior
Cron Schedule 0 9 * * 1-5 Triggers at 09:00 UTC every weekday (Monday through Friday).
Fixed Interval */30 * * * * Triggers every 30 minutes.
One-Shot Trigger 2027-01-01T00:00:00Z Executes once at the exact specified UTC timestamp.

Create an Automation

When creating an Automation, specify the schedule and the target Session configuration (the Agent or Template to execute, the initial prompt, reasoning effort, permission mode, and spending limits):

const automation = await skopik.automations.create({
	name: 'daily-dependency-triage',
	displayName: 'Daily Dependency Triage',
	description: 'Runs every morning to audit open pull requests and flagged security vulnerabilities.',
	schedule: {
		cron: '0 8 * * 1-5', // 8:00 AM UTC, Mon-Fri
	},
	session: {
		agent: securityAgentId,
		prompt: 'Scan the repository for outdated dependencies and open CVE advisories. Open PRs for critical updates.',
		title: 'Daily Dependency Audit',
		permission: 'ask',
		limits: {
			maxTurns: 20,
			maxCostUsd: 3,
		},
	},
})

console.log('Automation created:', automation.automationId)

Converge on a persistent Session with key

By default, an Automation creates a fresh Session on each trigger fire. To have recurring runs send new turns into the same ongoing Session (accumulating context and workspace state), provide a stable key with ifExists: 'send':

const automation = await skopik.automations.create({
	name: 'incident-monitor',
	displayName: 'Incident Channel Monitor',
	schedule: {
		cron: '*/15 * * * *', // Every 15 minutes
	},
	session: {
		key: 'incident-monitor-active',
		ifExists: 'send',
		agent: oncallAgentId,
		prompt: 'Check for unacknowledged P1/P2 alerts and summarize any active incident threads.',
	},
})

When this Automation triggers, Skopik opens the Session on the first execution and appends subsequent turns to the existing live Session on later runs.

Trigger manual execution with automations.run

Test an Automation immediately without waiting for its scheduled time:

const result = await skopik.automations.run(automation.automationId)

console.log('Fired session ID:', result.sessionId)
console.log('Created new session?:', result.created)
console.log('Delivery outcome:', result.delivery) // 'dispatched' | 'merged' | 'queued'

Manual execution runs in-process immediately and returns the resulting Session details.

List and inspect Automations

// List active automations
const { data: automations, page } = await skopik.automations.list({
	status: 'active',
	limit: 50,
})

// Fetch single automation details
const current = await skopik.automations.get(automation.automationId)

console.log('Schedule:', current.schedule)
console.log('Next fire:', current.nextRunAt)
console.log('Last fired:', current.lastRunAt)

Update schedule and configuration

const updated = await skopik.automations.update(automation.automationId, {
	displayName: 'Daily Morning Security Triage',
	schedule: {
		cron: '0 7 * * 1-5', // Move to 7:00 AM UTC
	},
	session: {
		agent: securityAgentId,
		prompt: 'Scan dependencies and inspect staging certificates.',
		limits: {
			maxTurns: 25,
			maxCostUsd: 4,
		},
	},
})

Disable and delete Automations

Deleting an Automation cancels its scheduled timer and marks it as disabled:

await skopik.automations.delete(automation.automationId)

API reference

SDK Method HTTP Endpoint Description
automations.list() GET /automations List all Automations in your organization.
automations.create() POST /automations Create a new scheduled Automation.
automations.get() GET /automations/{id} Read Automation details, schedule, and last fire times.
automations.update() PUT /automations/{id} Update schedule cadence or target Session configuration.
automations.run() POST /automations/{id}/run Manually fire the Automation immediately.
automations.delete() DELETE /automations/{id} Soft-disable and cancel the schedule.