Background Tasks

Save

Save posts the name, instructions, and triggers at revision 1. The stored workflow keeps the name Follow up when a promise slips, those instructions and triggers, cloud execution, and revision 2.

patch/v1/background-tasks/{slug}

Request

Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
URL: /v1/background-tasks/{slug}
Auth: HTTP bearer

Path parameters

slugstring required

Workflow address.

Example:follow-up-when-a-promise-slips

Workflow to save.

Request body

activeboolean

Enable or disable local scheduling/remote pickup.

createdAtstring date-time nullable

Original desktop task creation timestamp.

executionTarget'desktop' | 'api'

Where this task should execute.

instructionsstring nullable

New task instructions.

lastAttemptAtstring date-time nullable

Latest local attempt timestamp.

lastRunAtstring date-time nullable

Latest local run timestamp.

lastRunErrorstring nullable

Latest local run error.

lastRunIdstring nullable

Latest local run id.

lastRunSummarystring nullable

Latest local run summary.

modelstring nullable

Desktop-facing LLM model id.

namestring nullable

New task name.

providerstring nullable

Provider slug. Depending on the row this may be an OAuth provider, LLM provider, or execution backend.

revisioninteger required

Current task revision returned by the last GET/list/PATCH response.

triggersunknown

Example request

{
  "active": true,
  "createdAt": "2026-06-04T20:38:00Z",
  "executionTarget": "api",
  "instructions": "Summarize important account changes and draft follow-up notes.",
  "lastAttemptAt": "2026-06-04T21:00:00Z",
  "lastRunAt": "2026-06-04T21:02:00Z",
  "lastRunId": "run-20260604-210000",
  "lastRunSummary": "No high-priority account changes.",
  "model": "openai/gpt-4.1-mini",
  "name": "Daily Account Summary",
  "provider": "openai",
  "revision": 2,
  "triggers": {
    "cronExpr": "0 9 * * *",
    "timezone": "America/New_York"
  }
}

Response

Stored workflow.

activeboolean required

Whether the background task is active for scheduling and remote trigger pickup.

createdAtstring date-time required

Original desktop task creation timestamp when known; otherwise the server row creation time.

executionTarget'desktop' | 'api' required

Where this task executes. desktop preserves the local-first path; api dispatches to the Temporal-backed API worker.

idstring uuid required

Stable UUID primary key.

instructionsstring required

Background task instructions mirrored from task.yaml.

lastAttemptAtstring date-time nullable

Last time the desktop attempted to run this task.

lastRunAtstring date-time nullable

Last time the desktop completed or recorded a run for this task.

lastRunErrorstring nullable

Latest run error, empty when the latest run did not fail.

lastRunIdstring nullable

Last desktop or remote-trigger run id mirrored for this task.

lastRunSummarystring nullable

Short summary from the latest run.

modelstring nullable

Desktop-facing LLM model id.

namestring required

Human-readable background task name.

providerstring nullable

Provider slug. Depending on the row this may be an OAuth provider, LLM provider, or execution backend.

revisioninteger required

Optimistic-lock revision used by write endpoints.

scheduleSyncErrorstring nullable

Latest schedule reconciliation error, empty when healthy.

scheduleSyncState'current' | 'syncing' | 'failed' | 'paused' required

Server-owned Temporal schedule reconciliation state.

scheduleSyncedAtstring date-time nullable

Last successful schedule reconciliation timestamp.

slugstring required

Stable per-user background task slug matching bg-tasks/<slug> locally.

systemManagedboolean required

Whether Oppulence owns and upgrades this definition. Managed tasks can be paused but not deleted or edited.

templateSlugstring nullable

First-party template that owns this definition. Empty for user-authored tasks.

templateVersioninteger

Installed version of the owning first-party template. Zero for user-authored tasks.

triggersunknown

updatedAtstring date-time required

Server timestamp for the last mirrored task update.

Example response

{
  "active": true,
  "createdAt": "2026-06-04T20:38:00Z",
  "executionTarget": "desktop",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "instructions": "Summarize important account changes.",
  "lastAttemptAt": "2026-06-04T21:00:00Z",
  "lastRunAt": "2026-06-04T21:02:00Z",
  "lastRunId": "run-20260604-210000",
  "lastRunSummary": "No high-priority account changes.",
  "model": "openai/gpt-4.1-mini",
  "name": "Daily Account Summary",
  "provider": "openai",
  "revision": 2,
  "scheduleSyncState": "current",
  "scheduleSyncedAt": "2026-06-04T20:39:00Z",
  "slug": "daily-summary",
  "templateSlug": "relationship-refresh",
  "templateVersion": 1,
  "triggers": {
    "cronExpr": "0 9 * * *",
    "timezone": "America/New_York"
  },
  "updatedAt": "2026-06-04T20:39:00Z"
}

Changes

No recorded changes to this operation across all 50 revisions of this API.