Skip to content
cadenya
Get started
API Reference
Agents
Schedules

Create a new schedule

POST/v1/workspaces/{workspaceId}/agents/{agentId}/schedules

Creates a new schedule for an agent

Path ParametersExpand Collapse
workspaceId: string
agentId: string
Body ParametersJSONExpand Collapse
metadata: CreateResourceMetadata { name, bundleKey, externalId, labels }

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”)

bundleKey: optional string

Optional bundle ownership key. See ResourceMetadata.bundle_key.

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: AgentScheduleSpec { schedule, data, initialMessage, 3 more }

AgentScheduleSpec is the user-provided configuration for a schedule.

schedule: AgentScheduleSpecSchedule { calendars, intervals, timezone }

Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR’d together. At least one rule is required.

calendars: optional array of ScheduleCalendar { comment, dayOfMonth, dayOfWeek, 4 more }

Wall-clock rules. May be empty if intervals is non-empty.

comment: optional string
dayOfMonth: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
dayOfWeek: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
hour: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
minute: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
month: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
second: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
intervals: optional array of ScheduleInterval { every, offset }

Duration-based rules. May be empty if calendars is non-empty.

every: optional string
offset: optional string

Phase shift within every. Must be < every (enforced at runtime).

timezone: optional string

IANA tz name (e.g. “America/New_York”). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.

data: optional unknown

Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.

initialMessage: optional string

Optional initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history. When unset, the fired objective defers to the selected variation’s user_message_template.

overlapPolicy: optional "OVERLAP_POLICY_UNSPECIFIED" or "OVERLAP_POLICY_ALLOW" or "OVERLAP_POLICY_SKIP"

What to do when the previous run is still in flight. Defaults to SKIP.

formatenum
One of the following:
"OVERLAP_POLICY_UNSPECIFIED"
"OVERLAP_POLICY_ALLOW"
"OVERLAP_POLICY_SKIP"
userData: optional unknown

Optional data rendered into the variation’s user_message_template when each fired objective is created. Separate from data, which renders the system prompt template.

variationId: optional string

Optional explicit variation. When unset, the agent’s variation_selection_mode chooses per fire.

ReturnsExpand Collapse
AgentSchedule object { metadata, spec, state, info }

AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.

metadata: ResourceMetadata { id, accountId, createdAt, 7 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundleKey: optional string

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

updatedAt: optional string

Timestamp when this resource was last updated

formatdate-time
spec: AgentScheduleSpec { schedule, data, initialMessage, 3 more }

AgentScheduleSpec is the user-provided configuration for a schedule.

schedule: AgentScheduleSpecSchedule { calendars, intervals, timezone }

Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR’d together. At least one rule is required.

calendars: optional array of ScheduleCalendar { comment, dayOfMonth, dayOfWeek, 4 more }

Wall-clock rules. May be empty if intervals is non-empty.

comment: optional string
dayOfMonth: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
dayOfWeek: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
hour: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
minute: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
month: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
second: optional array of ScheduleRange { end, start, step }
end: optional number
start: optional number
step: optional number
intervals: optional array of ScheduleInterval { every, offset }

Duration-based rules. May be empty if calendars is non-empty.

every: optional string
offset: optional string

Phase shift within every. Must be < every (enforced at runtime).

timezone: optional string

IANA tz name (e.g. “America/New_York”). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.

data: optional unknown

Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.

initialMessage: optional string

Optional initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history. When unset, the fired objective defers to the selected variation’s user_message_template.

overlapPolicy: optional "OVERLAP_POLICY_UNSPECIFIED" or "OVERLAP_POLICY_ALLOW" or "OVERLAP_POLICY_SKIP"

What to do when the previous run is still in flight. Defaults to SKIP.

formatenum
One of the following:
"OVERLAP_POLICY_UNSPECIFIED"
"OVERLAP_POLICY_ALLOW"
"OVERLAP_POLICY_SKIP"
userData: optional unknown

Optional data rendered into the variation’s user_message_template when each fired objective is created. Separate from data, which renders the system prompt template.

variationId: optional string

Optional explicit variation. When unset, the agent’s variation_selection_mode chooses per fire.

state: "STATE_UNSPECIFIED" or "STATE_ACTIVE" or "STATE_PAUSED" or "STATE_ARCHIVED"

The current lifecycle state of the schedule. Output only. Schedules are created STATE_ACTIVE; use the :pause, :resume, and :archive actions to transition between states.

formatenum
One of the following:
"STATE_UNSPECIFIED"
"STATE_ACTIVE"
"STATE_PAUSED"
"STATE_ARCHIVED"
info: optional AgentScheduleInfo { createdBy, lastFireAt, lastObjectiveId, 4 more }

AgentScheduleInfo provides read-only runtime data about a schedule.

createdBy: optional Profile { metadata, spec }

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email: optional string

Email address of the profile. Required and unique within an account for user profiles.

name: optional string

Display name (e.g., “Bobby Tables”).

lastFireAt: optional string

When the schedule last fired (regardless of objective outcome).

formatdate-time
lastObjectiveId: optional string

ID of the most recent objective the schedule created.

lastSkippedAt: optional string

When the schedule most recently skipped a fire (SKIP policy + prior in flight).

formatdate-time
lastSkipReason: optional string

Reason for the most recent skip (e.g. “previous objective still running”).

nextFireAt: optional string

When the schedule will next fire. Computed from the spec; absent when the schedule is STATE_PAUSED/STATE_ARCHIVED or has no future fire times.

formatdate-time
totalFires: optional number

Lifetime count of objectives created by this schedule.

formatint32

Create a new schedule

curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/schedules \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CADENYA_API_KEY" \
    -d '{
          "metadata": {
            "name": "name"
          },
          "spec": {
            "schedule": {}
          }
        }'
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    },
    "updatedAt": "2019-12-27T18:11:19.117Z"
  },
  "spec": {
    "schedule": {
      "calendars": [
        {
          "comment": "comment",
          "dayOfMonth": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "dayOfWeek": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "hour": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "minute": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "month": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "second": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ]
        }
      ],
      "intervals": [
        {
          "every": "-160513s",
          "offset": "-160513s"
        }
      ],
      "timezone": "timezone"
    },
    "data": {},
    "initialMessage": "initialMessage",
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "userData": {},
    "variationId": "variationId"
  },
  "state": "STATE_UNSPECIFIED",
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "lastFireAt": "2019-12-27T18:11:19.117Z",
    "lastObjectiveId": "lastObjectiveId",
    "lastSkippedAt": "2019-12-27T18:11:19.117Z",
    "lastSkipReason": "lastSkipReason",
    "nextFireAt": "2019-12-27T18:11:19.117Z",
    "totalFires": 0
  }
}
Returns Examples
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    },
    "updatedAt": "2019-12-27T18:11:19.117Z"
  },
  "spec": {
    "schedule": {
      "calendars": [
        {
          "comment": "comment",
          "dayOfMonth": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "dayOfWeek": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "hour": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "minute": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "month": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "second": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ]
        }
      ],
      "intervals": [
        {
          "every": "-160513s",
          "offset": "-160513s"
        }
      ],
      "timezone": "timezone"
    },
    "data": {},
    "initialMessage": "initialMessage",
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "userData": {},
    "variationId": "variationId"
  },
  "state": "STATE_UNSPECIFIED",
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "lastFireAt": "2019-12-27T18:11:19.117Z",
    "lastObjectiveId": "lastObjectiveId",
    "lastSkippedAt": "2019-12-27T18:11:19.117Z",
    "lastSkipReason": "lastSkipReason",
    "nextFireAt": "2019-12-27T18:11:19.117Z",
    "totalFires": 0
  }
}