POST
/
v1
/
teams
/
{teamId}
/
workflow-schedules
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.workflowSchedules.createWorkflowSchedule({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "brief": "<string>",
  "firePlan": {
    "kind": "times",
    "times": [
      "<string>"
    ]
  },
  "cadence": "0 7 * * 1",
  "selection": {
    "mode": "fixed",
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "strategy": "<string>",
  "nextRunAt": "<string>",
  "lastRunAt": "<string>",
  "perRunCreditCeilingDecimillicents": 123,
  "dailyCreditCeilingDecimillicents": 1,
  "pendingItemCap": 50,
  "maxConcurrent": 5,
  "targetSocialAccountIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "pausedAt": "<string>",
  "createdBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "revision": 1,
  "agentOwnedLimits": true
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
idempotency-key
string

Reuse this key with the same creation request after a lost response. The original resource is returned; a different request is rejected with 409.

Required string length: 1 - 200

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Body

application/json
​
name
string
required

Display name for the workflow schedule, 1-120 characters.

Required string length: 1 - 120
​
brief
string
required

The instruction each run starts from: the prompt handed to the agent.

Required string length: 1 - 20000
​
accountPostingLimits
maxItems(1000) · object[]

Optional changed account limits to save atomically with this configuration. Accounts must be distinct selected destinations of this workspace. A nonempty array additionally requires manage_integrations. Any invalid, stale or unsafe reduction rejects every change. Omit or send [] to leave all shared limits unchanged.

Maximum array length: 1000
​
firePlan
object

When the schedule fires: { kind: "times", times: ["06:00", "18:00"] } or { kind: "window", start: "09:00", end: "18:00", count: 5 } (UTC). Exactly one of firePlan or cadence is required for schedule-typed schedules.

​
cadence
string

Legacy five-field cron expression evaluated in UTC (minute hour day-of-month month day-of-week). Prefer firePlan; a cron is used only when firePlan cannot express the cadence (weekly, stepped).

Required string length: 1 - 100
Example:

"0 7 * * 1"

​
selection
object

Which agent version each firing runs. Omit for fixed selection of agentId at its current version.

​
agentId
string<uuid> | null

Managed agent a fixed schedule runs. Omit or send null to use the team's default agent. Ignored for optimised selection.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
campaignId
string<uuid> | null

Campaign this schedule belongs to, for grouping and aggregate stats; required (and equal to selection.campaignId) for optimised selection. Null for none.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
strategy
string

Label copied onto each run this schedule starts (for example "promptA"), up to 64 characters. Omit for none.

Required string length: 1 - 64
​
perRunCreditCeilingDecimillicents
integer

Per-run credit cap in decimillicents. Omit for the default of $100 (1000000000 decimillicents); the agent version's own ceiling still applies.

​
dailyCreditCeilingDecimillicents
integer | null

Daily credit ceiling in decimillicents (UTC day). Omit for the default of $100 per day; send null for no daily ceiling.

Required range: x > 0
​
pendingItemCap
integer

Skip firings while this many (or more) of the schedule's runs are still in flight or unreviewed, 1-100 (default 10).

Required range: 1 <= x <= 100
​
maxConcurrent
integer

Skip a firing while this many of the schedule's runs are queued, running or paused, 1-10 (default 1 for new schedules).

Required range: 1 <= x <= 10
​
paused
boolean

Create the schedule paused. Omit or false to start firing at the next planned instant.

​
triggerType
enum<string>

schedule (default) fires from firePlan or cadence. trigger fires only from its inbound trigger (API only): send no firePlan or cadence.

Available options:
schedule,
trigger
​
targetSocialAccountIds
string<uuid>[]

Social accounts of this team the runs target, in priority order (the first account's platform is the optimiser's primary platform), up to 20. Omit or send [] to let the agent decide.

Maximum array length: 20

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Response

Success

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
organizationId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
name
string
required

Display name for the workflow schedule, 1-120 characters.

Required string length: 1 - 120
​
brief
string
required

The instruction each run starts from: the prompt handed to the agent.

Required string length: 1 - 20000
​
triggerType
enum<string>
required

schedule: fires from its plan; trigger: started by an inbound trigger (API only); manual: direct runs only.

Available options:
schedule,
trigger,
manual
​
kind
enum<string>
required

user: created by a person. manual_implicit: the automatic owner of an agent's direct, API and review-queue runs (hidden from lists by default; it cannot be deleted).

Available options:
user,
manual_implicit
​
firePlan
object
required

When the schedule fires (daily UTC times or a random daily window). Null for legacy cron schedules and manual schedules.

​
cadence
string | null
required

Legacy five-field UTC cron expression, used when firePlan is null (for example weekly schedules). Null when firePlan drives the schedule.

Required string length: 1 - 100
Example:

"0 7 * * 1"

​
selection
object
required

Which agent version each firing runs: fixed, or optimised across a campaign.

​
agentId
string<uuid> | null
required

Managed agent a fixed schedule runs; null for optimised selection (the campaign's agents are the pool).

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
campaignId
string<uuid> | null
required

Campaign this schedule belongs to, for grouping and aggregate stats; required (and equal to selection.campaignId) for optimised selection. Null for none.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
strategy
string | null
required

Label copied onto each run this schedule starts, for comparing set-ups in analytics; null for none.

Required string length: 1 - 64
​
nextRunAt
string | null
required

When the schedule next fires (ISO-8601 UTC); null for manual and trigger schedules.

​
lastRunAt
string | null
required

When the schedule last fired (ISO-8601 UTC); null before the first firing.

​
perRunCreditCeilingDecimillicents
integer
required

Per-run credit cap in decimillicents. A run spends at most min(this cap, the agent version's per-run ceiling).

​
dailyCreditCeilingDecimillicents
integer | null
required

Daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). Firings are skipped once it is reached (optimised selection also skips agents whose per-run ceiling no longer fits); null means no daily ceiling.

Required range: x > 0
​
pendingItemCap
integer
required

Skip firings while this many (or more) of the schedule's runs are still in flight or unreviewed, 1-100 (default 10).

Required range: 1 <= x <= 100
​
maxConcurrent
integer
required

Skip a firing while this many of the schedule's runs are queued, running or paused, 1-10 (default 1 for new schedules).

Required range: 1 <= x <= 10
​
targetSocialAccountIds
string<uuid>[]
required

Social accounts the runs target, in priority order; the first account's platform is the optimiser's primary platform. Empty lets the agent decide.

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
pausedAt
string | null
required

When the schedule was paused (ISO-8601 UTC); null while active. A paused schedule never fires.

​
createdBy
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
createdAt
string
required
​
updatedAt
string
required
​
revision
integer

a non-negative number

Required range: x >= 0
​
agentOwnedLimits
boolean

Whether the selected managed agent owns the per-run ceiling. False preserves the legacy schedule ceiling as an additional cap.