Tasks API

Tasks are units of AI work in Sasha. Each task has a prompt that Sasha executes. Tasks can be run on demand via API, or put on a schedule to run automatically.

Use Cases

Use Case	Description
Recurring reports	Put a daily/weekly report task on a schedule — Sasha generates and emails summaries automatically
Client briefings	Before a client meeting, trigger a task to generate a briefing from project history
Data sync	Run an on-demand task to pull data from an external system into Sasha's knowledge base
Compliance reports	Schedule monthly audit or compliance reports
Knowledge maintenance	Put a task on a schedule to review stale documentation and flag updates needed
CI/CD integration	Trigger tasks from your deployment pipeline — generate release notes, update changelogs
CRM workflows	When a deal closes in your CRM, call the API to trigger a project setup task
Monitoring & alerts	Schedule a task to check system health metrics and alert on anomalies

Quick Start

1. Create an on-demand task

curl -X POST https://your-sasha.example.com/api/v1/tasks \
  -H "X-API-Key: sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-report",
    "promptName": "weekly-summary"
  }'

2. Put it on a schedule

curl -X PUT https://your-sasha.example.com/api/v1/tasks/weekly-report \
  -H "X-API-Key: sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpression": "0 9 * * 1",
    "timezone": "America/New_York"
  }'

3. Run it now

curl -X POST https://your-sasha.example.com/api/v1/tasks/weekly-report/run \
  -H "X-API-Key: sk_your_key"

API Reference

List tasks

GET /api/v1/tasks

Returns all tasks. Optionally filter by schedule status.

Query parameters:

Parameter	Type	Description
`scheduled`	`true` \| `false`	Filter to only scheduled or only on-demand tasks

Response:

{
  "tasks": [
    {
      "name": "weekly-report",
      "promptName": "weekly-summary",
      "cronExpression": "0 9 * * 1",
      "timezone": "America/New_York",
      "enabled": true,
      "timeoutMs": 300000,
      "lastRunAt": "2025-02-10T14:00:00.000Z",
      "lastStatus": "completed",
      "nextRunAt": "2025-02-17T14:00:00.000Z",
      "isScheduled": true,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-02-01T08:30:00.000Z"
    }
  ]
}

Get task details

GET /api/v1/tasks/:name

Returns task details and its 10 most recent executions.

Response:

{
  "task": { ... },
  "recentExecutions": [
    {
      "executionId": "exec_abc123",
      "executionType": "schedule",
      "name": "weekly-report",
      "status": "completed",
      "triggerType": "scheduled",
      "startedAt": "2025-02-10T14:00:00.000Z",
      "completedAt": "2025-02-10T14:02:15.000Z",
      "durationMs": 135000,
      "inputTokens": 1250,
      "outputTokens": 3400
    }
  ]
}

Create a task

POST /api/v1/tasks

Request body:

Field	Type	Required	Description
`name`	string	Yes	Unique task identifier
`promptName`	string	Yes	Name of the prompt to execute
`cronExpression`	string	No	Cron schedule (omit for on-demand task)
`timezone`	string	No	Timezone for cron (default: `UTC`)
`enabled`	boolean	No	Whether schedule is active (default: `true`)
`timeout`	number	No	Timeout in milliseconds (default: `300000`)

Example — scheduled task:

curl -X POST https://your-sasha.example.com/api/v1/tasks \
  -H "X-API-Key: sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-digest",
    "promptName": "daily-activity-summary",
    "cronExpression": "0 6 * * *",
    "timezone": "UTC",
    "enabled": true,
    "timeout": 300000
  }'

Example — on-demand task:

curl -X POST https://your-sasha.example.com/api/v1/tasks \
  -H "X-API-Key: sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "client-briefing",
    "promptName": "generate-client-brief"
  }'

Response: 201 Created

{
  "task": {
    "name": "daily-digest",
    "promptName": "daily-activity-summary",
    "cronExpression": "0 6 * * *",
    "timezone": "UTC",
    "enabled": true,
    "isScheduled": true,
    "nextRunAt": "2025-02-12T06:00:00.000Z",
    ...
  }
}

Update a task

PUT /api/v1/tasks/:name

Update any task fields. Only include fields you want to change.

Request body:

Field	Type	Description
`promptName`	string	New prompt to execute
`cronExpression`	string	New cron schedule
`timezone`	string	New timezone
`enabled`	boolean	Enable/disable schedule
`timeout`	number	New timeout in milliseconds

Delete a task

DELETE /api/v1/tasks/:name

Response:

{
  "success": true,
  "message": "Task deleted"
}

Run a task

POST /api/v1/tasks/:name/run

Run a task immediately. Works for both scheduled and on-demand tasks, regardless of whether the schedule is enabled or disabled.

Response:

{
  "success": true,
  "message": "Task execution started",
  "taskName": "weekly-report"
}

Schedule Management

Enable a schedule (Schedule On)

POST /api/v1/tasks/:name/enable

Activates the cron timer. The task will run automatically at the scheduled times.

Disable a schedule (Schedule Off)

POST /api/v1/tasks/:name/disable

Pauses the cron timer. The task keeps its cron expression and can still be run manually via the /run endpoint.

How scheduling works

cronExpression uses standard 5-field cron syntax: minute hour day-of-month month day-of-week
timezone accepts IANA timezone names (e.g., America/New_York, Europe/London, UTC)
enabled only affects automatic scheduling — manual runs via /run always work
Tasks without a cronExpression are on-demand and have no schedule to enable/disable

Common cron expressions:

Expression	Meaning
`0 6 * * *`	Every day at 6:00 AM
`0 9 * * 1`	Every Monday at 9:00 AM
`0 /4 * *`	Every 4 hours
`0 9 1 * *`	First day of every month at 9:00 AM
`/30 * * *`	Every 30 minutes

Execution History

Get task execution history

GET /api/v1/tasks/:name/history

Query parameters:

Parameter	Type	Default	Description
`limit`	number	50	Max records (max 100)
`offset`	number	0	Pagination offset

Response:

{
  "executions": [
    {
      "executionId": "exec_abc123",
      "executionType": "schedule",
      "name": "weekly-report",
      "status": "completed",
      "triggerType": "scheduled",
      "startedAt": "2025-02-10T14:00:00.000Z",
      "completedAt": "2025-02-10T14:02:15.000Z",
      "durationMs": 135000,
      "resultSummary": "Report generated successfully",
      "inputTokens": 1250,
      "outputTokens": 3400
    }
  ]
}

Execution statuses

Status	Description
`running`	Currently executing
`completed`	Finished successfully
`failed`	Encountered an error
`timeout`	Exceeded timeout limit
`stale`	Was running when server restarted

Troubleshooting

Issue	Solution
Task not running on schedule	Check `enabled` is `true` and `cronExpression` is valid
404 when creating a task	Verify the `promptName` exists in your scheduled-prompts directory
409 Conflict on create	A task with that name already exists — use PUT to update
Task times are wrong	Check the `timezone` field — defaults to UTC if not specified
Run returns success but task fails	Check execution history via `GET /api/v1/tasks/:name/history`
Schedule On/Off not taking effect	The scheduler reloads automatically — check server logs if issues persist