API v1 Reference › Agent Schedules

Creates an agent schedule.

POSThttps://api.awork.com/api/v1/agents/{agentId}/schedules
POST https://api.awork.com/api/v1/agents/{agentId}/schedules

Creates a schedule for an agent after validating its cadence, timezone, and optional project or task context.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Path parameters

agentIdstringRequired
format: uuid

The Custom Agent ID.

Request body Required

The schedule payload.

application/json

namestringRequired
minLength: 1 maxLength: 255

The schedule display name.

promptstring or nullOptional
maxLength: 25000

Optional custom instructions for the initial message. Omitted, null, or blank input clears custom instructions.

cronRulestringRequired
minLength: 1 maxLength: 100

The cron rule used for recurring execution.

recurrenceIntervalinteger or nullOptional
format: int32minimum: 1 maximum: 99

The number of matching cron occurrences between scheduled runs.

timezonestring or nullOptional
maxLength: 100

The timezone for the cron rule.

projectIdstring or nullOptional
format: uuid

The optional project context id.

taskIdstring or nullOptional
format: uuid

The optional task context id.

isEnabledboolean or nullOptional

Whether the schedule is enabled.

Responses

200 OK

application/json

namestring or nullOptional

The schedule display name.

idstringOptional
format: uuid

The schedule id.

createdOnstringOptional
format: date-time

When the schedule was created.

agentIdstring or nullOptional
format: uuid

The agent id that is executed by this schedule.

typestring or nullOptional

Runtime target type: personal-agent or custom-agent.

ownerUserIdstringOptional
format: uuid

The user id whose context is used to execute the scheduled run.

promptstring or nullOptional

Optional custom instructions. An omitted or null prompt means no custom instructions.

cronRulestring or nullOptional

The normalized cron rule used for recurring execution.

recurrenceIntervalintegerOptional
format: int32

The number of matching cron occurrences between scheduled runs.

timezonestring or nullOptional

The timezone used to evaluate the cron rule.

projectIdstring or nullOptional
format: uuid

The optional project context id.

taskIdstring or nullOptional
format: uuid

The optional task context id.

isTaskContextDeletedbooleanOptional

Whether the required task context was deleted.

isEnabledbooleanOptional

Whether this schedule is active.

needsAttentionbooleanOptional

Whether the schedule needs user attention.

lastFailureReasonstring or nullOptional

The latest rejection reason.

consecutiveFailureCountintegerOptional
format: int32

The number of consecutive failed scheduled executions.

lastAttemptOnstring or nullOptional
format: date-time

The latest occurrence time.

lastSuccessfulRunOnstring or nullOptional
format: date-time

The latest accepted occurrence time.

400 Bad Request

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

401 Unauthorized

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

404 Not Found

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation