Skip to content
cadenya
Get started
API Reference
Agents
Schedules

Create a new schedule

client.Agents.Schedules.New(ctx, workspaceID, agentID, body) (*AgentSchedule, error)
POST/v1/workspaces/{workspaceId}/agents/{agentId}/schedules

Creates a new schedule for an agent

ParametersExpand Collapse
workspaceID string
agentID string
body AgentScheduleNewParams
Metadata param.Field[CreateResourceMetadata]

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.

Spec param.Field[AgentScheduleSpec]

AgentScheduleSpec is the user-provided configuration for a schedule.

ReturnsExpand Collapse
type AgentSchedule struct{…}

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

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 Time

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 stringOptional

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 stringOptional

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

Labels map[string, string]Optional

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

AgentScheduleSpec is the user-provided configuration for a schedule.

InitialMessage string

The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.

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 []ScheduleCalendarOptional

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

Comment stringOptional
DayOfMonth []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
DayOfWeek []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
Hour []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
Minute []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
Month []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
Second []ScheduleRangeOptional
End int64Optional
Start int64Optional
Step int64Optional
Intervals []ScheduleIntervalOptional

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

Every stringOptional
Offset stringOptional

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

Timezone stringOptional

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

Data unknownOptional

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

OverlapPolicy AgentScheduleSpecOverlapPolicyOptional

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

formatenum
One of the following:
const AgentScheduleSpecOverlapPolicyOverlapPolicyUnspecified AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_UNSPECIFIED"
const AgentScheduleSpecOverlapPolicyOverlapPolicyAllow AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_ALLOW"
const AgentScheduleSpecOverlapPolicyOverlapPolicySkip AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_SKIP"
Status AgentScheduleSpecStatusOptional

Lifecycle. Defaults to ACTIVE on create when unspecified.

formatenum
One of the following:
const AgentScheduleSpecStatusAgentScheduleStatusUnspecified AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_UNSPECIFIED"
const AgentScheduleSpecStatusAgentScheduleStatusActive AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ACTIVE"
const AgentScheduleSpecStatusAgentScheduleStatusPaused AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_PAUSED"
const AgentScheduleSpecStatusAgentScheduleStatusArchived AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ARCHIVED"
VariationID stringOptional

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

Info AgentScheduleInfoOptional

AgentScheduleInfo provides read-only runtime data about a schedule.

CreatedBy ProfileOptional

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.

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 stringOptional

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

Labels map[string, string]Optional

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

Configuration for a profile.

Type ProfileSpecType

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

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringOptional

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

Name stringOptional

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

LastFireAt TimeOptional

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

formatdate-time
LastObjectiveID stringOptional

ID of the most recent objective the schedule created.

LastSkippedAt TimeOptional

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

formatdate-time
LastSkipReason stringOptional

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

NextFireAt TimeOptional

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

formatdate-time
TotalFires int64Optional

Lifetime count of objectives created by this schedule.

formatint32

Create a new schedule

package main

import (
  "context"
  "fmt"

  "github.com/cadenya/cadenya-go"
  "github.com/cadenya/cadenya-go/option"
  "github.com/cadenya/cadenya-go/shared"
)

func main() {
  client := cadenya.NewClient(
    option.WithAPIKey("My API Key"),
  )
  agentSchedule, err := client.Agents.Schedules.New(
    context.TODO(),
    "workspaceId",
    "agentId",
    cadenya.AgentScheduleNewParams{
      Metadata: cadenya.F(shared.CreateResourceMetadataParam{
        Name: cadenya.F("name"),
      }),
      Spec: cadenya.F(cadenya.AgentScheduleSpecParam{
        InitialMessage: cadenya.F("initialMessage"),
        Schedule: cadenya.F(cadenya.AgentScheduleSpecScheduleParam{

        }),
      }),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", agentSchedule.Metadata)
}

{
  "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"
    }
  },
  "spec": {
    "initialMessage": "initialMessage",
    "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": {},
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
    "variationId": "variationId"
  },
  "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"
    }
  },
  "spec": {
    "initialMessage": "initialMessage",
    "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": {},
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
    "variationId": "variationId"
  },
  "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
  }
}