Sign in
Background Tasks

Create workflow

Create workflow posts a draft named Follow up when a promise slips. It runs in the cloud, starts when a communication event matches, and stays inactive. The stored workflow keeps that name, the address follow-up-when-a-promise-slips, those instructions and triggers, cloud execution, revision 1, and schedule sync paused.

post/v1/background-tasks

Request

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

Request body

activeboolean

Whether this task is active. Defaults to true.

createdAtstring date-time nullable

Original desktop task creation timestamp.

executionTarget'desktop' | 'api'

Where this task should execute. Defaults to desktop.

instructionsstring required

Task instructions mirrored from task.yaml.

lastAttemptAtstring date-time nullable

Last attempt timestamp from local state.

lastRunAtstring date-time nullable

Last local run timestamp.

lastRunErrorstring nullable

Latest local run error.

lastRunIdstring nullable

Last local run id from the desktop.

lastRunSummarystring nullable

Latest local run summary.

modelstring nullable

Desktop-facing LLM model id.

namestring required

Human-readable task name.

providerstring nullable

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

slugstring nullable

Optional stable slug. If omitted, rowboat-api slugifies name.

triggersunknown

Example request

{
  "active": true,
  "createdAt": "2026-06-04T20:38:00Z",
  "executionTarget": "desktop",
  "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",
  "slug": "daily-summary",
  "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 operation changes recorded.