Stan Tasks & Heartbeat

Create and manage Stan scheduled tasks — recurring actions Stan performs on a schedule — and configure the Stan heartbeat, a periodic health-check loop that runs configurable diagnostics against the user's environment.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Scheduled Task Object

{
  "id": "task_abc001",
  "name": "Daily workflow audit",
  "action": "audit_workflows",
  "schedule": "0 9 * * *",
  "modelId": "model_abc123",
  "status": "active",
  "createdAt": "2025-02-01T08:00:00Z",
  "lastRunAt": "2025-02-15T09:00:00Z",
  "nextRunAt": "2025-02-16T09:00:00Z"
}

---

GET /api/v1/stan/tasks

List all scheduled tasks for the authenticated user.

Scope: stan:execute

Response 200 OK

[
  {
    "id": "task_abc001",
    "name": "Daily workflow audit",
    "action": "audit_workflows",
    "schedule": "0 9 * * *",
    "modelId": "model_abc123",
    "status": "active"
  }
]

---

POST /api/v1/stan/tasks

Create a new scheduled task.

Scope: stan:execute

Request Body

{
  "name": "Daily workflow audit",
  "action": "audit_workflows",
  "schedule": "0 9 * * *",
  "modelId": "model_abc123"
}

Field	Type	Required	Description
name	string	Yes	Human-readable task name
action	string	Yes	Stan action to run on each tick
schedule	string	Yes	Cron expression controlling when the task runs
modelId	string	Yes	Model used to execute the task

Response 201 Created

Returns the full Scheduled Task object.

---

GET /api/v1/stan/tasks/:id

Get details for a single scheduled task.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Task ID

Response 200 OK

Returns the full Scheduled Task object.

---

PUT /api/v1/stan/tasks/:id

Update an existing scheduled task.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Task ID

Request Body

{
  "name": "Updated task name",
  "schedule": "0 10 * * *"
}

Field	Type	Required	Description
name	string	No	Human-readable task name
action	string	No	Stan action to run
schedule	string	No	Cron expression
modelId	string	No	Model used to execute the task

Response 200 OK

{
  "updated": true
}

---

DELETE /api/v1/stan/tasks/:id

Delete a scheduled task.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Task ID

Response 204 No Content

---

POST /api/v1/stan/tasks/:id/pause

Pause a scheduled task. Paused tasks remain configured but stop firing until resumed.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Task ID

Response 200 OK

{
  "paused": true
}

---

POST /api/v1/stan/tasks/:id/resume

Resume a previously paused task.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Task ID

Response 200 OK

{
  "resumed": true
}

---

Heartbeat Object

{
  "enabled": true,
  "checks": ["workflows", "deployments", "credits"],
  "intervalMinutes": 30,
  "availableChecks": ["workflows", "deployments", "credits", "models"]
}

---

GET /api/v1/stan/heartbeat

Get the current heartbeat configuration for the authenticated user, along with the full list of available checks.

Scope: stan:execute

Response 200 OK

Returns the full Heartbeat object.

---

PUT /api/v1/stan/heartbeat

Update the heartbeat configuration.

Scope: stan:execute

Request Body

{
  "enabled": true,
  "checks": ["workflows", "deployments"],
  "intervalMinutes": 60
}

Field	Type	Required	Description
enabled	boolean	No	Whether the heartbeat runs on its interval
checks	string[]	No	List of check names to run each tick
intervalMinutes	integer	No	Run interval in minutes (minimum: 5)

Response 200 OK

Returns the updated heartbeat configuration.

---

POST /api/v1/stan/heartbeat/run

Run the configured heartbeat checks on demand and return results immediately.

Scope: stan:execute

Response 200 OK

{
  "results": [
    { "check": "workflows", "status": "ok", "message": "All workflows healthy" },
    { "check": "deployments", "status": "warn", "message": "1 deployment idle" }
  ],
  "issues": [
    { "check": "deployments", "status": "warn", "message": "1 deployment idle" }
  ],
  "healthy": false
}