create_behavior
Creates a Behavior, a recurring thing the user wants to track (a habit, routine or recurring task), with schedules (daily, every N days, weekly or every N weeks on chosen weekdays, monthly on day N) and reminders. With is_opportunity true it can be added to today when there is room, and schedules may be empty. sub_behaviors creates a parent and up to 25 sub-behaviors in one change; parent_behavior_id adds one sub-behavior to an existing parent, and one that follows the parent’s schedule needs no schedules. An opportunity Behavior is never in a routine. list_categories lists categories.
Permission and annotations
Required scope: cadence.behaviors.write. Contract 1.7.0; available since 1.0.0.
title: “Create Behavior”readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false
Adds a new Behavior and changes no existing record, so destructiveHint is false under both Claude’s and OpenAI’s guidance; readOnlyHint is false, so clients still treat it as a write. Calling it twice without an idempotency_key creates two Behaviors, so idempotentHint is false. openWorldHint is false.
Input
Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
title |
yes | string | Behavior name.; minLength: 1; maxLength: 160; pattern: ^(?=.*\S)[^\u0000-\u001f\u007f]*$ |
description |
no | string | Optional description.; maxLength: 1000; pattern: ^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]*$ |
location_text |
no | string | Optional place where the Behavior happens, as plain text.; maxLength: 500; pattern: ^[^\u0000-\u001f\u007f]*$ |
category_id |
no | string or null | Category id from list_categories.; format: uuid |
schedules |
no | array | Complete list of schedules. Each schedule has one recurrence rule and one or more time entries. It may be empty only for a Behavior available as an opportunity.; maxItems: 6 |
schedules[] |
yes | object | |
schedules[].id |
no | string | Existing schedule id. Omit for a new schedule.; format: uuid |
schedules[].recurrence |
yes | one of several shapes | Structured recurrence rule. Natural-language rules and cron syntax are not accepted. |
schedules[].recurrence.frequency |
yes | string | Value: daily |
schedules[].recurrence.interval |
yes | integer | Repeat every N days. 1 means every day.; minimum: 1; maximum: 999 |
schedules[].recurrence.frequency |
yes | string | Value: interval_days |
schedules[].recurrence.interval_days |
yes | integer | Repeat every N days counted from the start date.; minimum: 1; maximum: 999 |
schedules[].recurrence.frequency |
yes | string | Value: weekly |
schedules[].recurrence.interval |
yes | integer | Repeat every N weeks. 1 means every week.; minimum: 1; maximum: 999 |
schedules[].recurrence.days_of_week |
yes | array | minItems: 1; maxItems: 7; uniqueItems: true |
schedules[].recurrence.days_of_week[] |
yes | string | Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday |
schedules[].recurrence.frequency |
yes | string | Value: monthly |
schedules[].recurrence.interval |
yes | integer | Repeat every N months.; minimum: 1; maximum: 999 |
schedules[].recurrence.day_of_month |
yes | integer | Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31 |
schedules[].time_entries |
yes | array | minItems: 1; maxItems: 8 |
schedules[].time_entries[] |
yes | one of several shapes | |
schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
schedules[].time_entries[].kind |
yes | string | Value: exact |
schedules[].time_entries[].start_time |
yes | string | Exact time of day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
schedules[].time_entries[].kind |
yes | string | Value: range |
schedules[].time_entries[].preset |
yes | string | Morning 06:00-12:00, Afternoon 12:00-18:00, Evening 18:00-00:00, Night 00:00-06:00.; Values: morning, afternoon, evening, night |
schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
schedules[].time_entries[].kind |
yes | string | Value: range |
schedules[].time_entries[].start_time |
yes | string | Range start.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
schedules[].time_entries[].end_time |
yes | string | Range end. A range may end after midnight, for example 22:00-01:00.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
is_opportunity |
no | boolean | Available as an opportunity: the person can add it to today when there is room. Required true for empty schedules (contract 1.6.0). An opportunity Behavior cannot be a parent or a sub-behavior (contract 1.7.0).; default: false |
reminders |
no | object | Per-Behavior reminder settings. Omitted fields keep their current or default value. |
reminders.browser_enabled |
no | boolean | Browser reminders. On by default. |
reminders.email_enabled |
no | boolean | Email reminders. Off by default. |
reminders.offset_minutes |
no | integer | Minutes before the scheduled time: 0, 15, 60, 1440 (1 day), or 4320 (3 days). Default 0.; Values: 0, 15, 60, 1440, 4320 |
default_duration_minutes |
no | integer | Planned duration in minutes for Timeline planning.; minimum: 1; maximum: 1440 |
parent_behavior_id |
no | string | Optional parent Behavior: the new Behavior becomes its sub-behavior. The parent must be active and top-level (contract 1.7.0).; format: uuid |
inherit_parent_schedule |
no | boolean | With parent_behavior_id: true (the default) follows the parent’s schedule and takes no schedules; false needs schedules. |
sub_behavior_sort_order |
no | integer | With parent_behavior_id: position among the parent’s sub-behaviors. Defaults to last.; minimum: 0; maximum: 9999 |
sub_behaviors |
no | array | Sub-behaviors to create with this Behavior in the same change, in display order. Not allowed with parent_behavior_id: a sub-behavior can’t have sub-behaviors.; minItems: 1; maxItems: 25 |
sub_behaviors[] |
yes | object | One sub-behavior to create under the new parent. |
sub_behaviors[].title |
yes | string | Behavior name.; minLength: 1; maxLength: 160; pattern: ^(?=.*\S)[^\u0000-\u001f\u007f]*$ |
sub_behaviors[].description |
no | string | Optional description.; maxLength: 1000; pattern: ^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]*$ |
sub_behaviors[].inherit_parent_schedule |
no | boolean | True (the default) follows the parent’s schedule and takes no schedules; false needs schedules. |
sub_behaviors[].schedules |
no | array | Complete list of schedules. Each schedule has one recurrence rule and one or more time entries. It may be empty only for a Behavior available as an opportunity.; maxItems: 6 |
sub_behaviors[].schedules[] |
yes | object | |
sub_behaviors[].schedules[].id |
no | string | Existing schedule id. Omit for a new schedule.; format: uuid |
sub_behaviors[].schedules[].recurrence |
yes | one of several shapes | Structured recurrence rule. Natural-language rules and cron syntax are not accepted. |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: daily |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N days. 1 means every day.; minimum: 1; maximum: 999 |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: interval_days |
sub_behaviors[].schedules[].recurrence.interval_days |
yes | integer | Repeat every N days counted from the start date.; minimum: 1; maximum: 999 |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: weekly |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N weeks. 1 means every week.; minimum: 1; maximum: 999 |
sub_behaviors[].schedules[].recurrence.days_of_week |
yes | array | minItems: 1; maxItems: 7; uniqueItems: true |
sub_behaviors[].schedules[].recurrence.days_of_week[] |
yes | string | Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: monthly |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N months.; minimum: 1; maximum: 999 |
sub_behaviors[].schedules[].recurrence.day_of_month |
yes | integer | Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31 |
sub_behaviors[].schedules[].time_entries |
yes | array | minItems: 1; maxItems: 8 |
sub_behaviors[].schedules[].time_entries[] |
yes | one of several shapes | |
sub_behaviors[].schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
sub_behaviors[].schedules[].time_entries[].kind |
yes | string | Value: exact |
sub_behaviors[].schedules[].time_entries[].start_time |
yes | string | Exact time of day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
sub_behaviors[].schedules[].time_entries[].kind |
yes | string | Value: range |
sub_behaviors[].schedules[].time_entries[].preset |
yes | string | Morning 06:00-12:00, Afternoon 12:00-18:00, Evening 18:00-00:00, Night 00:00-06:00.; Values: morning, afternoon, evening, night |
sub_behaviors[].schedules[].time_entries[].id |
no | string | Existing time entry id. Omit for a new entry.; format: uuid |
sub_behaviors[].schedules[].time_entries[].kind |
yes | string | Value: range |
sub_behaviors[].schedules[].time_entries[].start_time |
yes | string | Range start.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].schedules[].time_entries[].end_time |
yes | string | Range end. A range may end after midnight, for example 22:00-01:00.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].sub_behavior_sort_order |
no | integer | Position among the sub-behaviors. Defaults to the list order.; minimum: 0; maximum: 9999 |
sub_behaviors[].external_ref |
no | string | Optional id of the matching record in the calling app. Stored for this client only.; minLength: 1; maxLength: 200; pattern: ^[\x21-\x7e]+$ |
end_on |
no | string | Optional last local day the Behavior runs. It stays active and moves to Not running after it.; format: date |
end_time |
no | string | Optional local time on end_on when it stops. Needs end_on. Without it the Behavior stops at the end of end_on.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
end_date |
no | string | Deprecated: send end_on. The first day without the Behavior; Cadence stores end_on as the day before.; format: date |
external_ref |
no | string | Optional id of the matching record in the calling app. Stored for this client only.; minLength: 1; maxLength: 200; pattern: ^[\x21-\x7e]+$ |
idempotency_key |
no | string | Optional client-chosen key. Repeating a call with the same key and input within 24 hours returns the first result and changes nothing.; minLength: 8; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
Provide at least one of: schedules, parent_behavior_id.
Output
Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
behavior |
yes | object | A Behavior: a recurring thing the user tracks (a habit, routine, or recurring task). |
behavior.id |
yes | string | format: uuid |
behavior.title |
yes | string | |
behavior.description |
yes | string or null | |
behavior.location_text |
yes | string or null | |
behavior.category |
yes | object or null | |
behavior.category.id |
yes | string | format: uuid |
behavior.category.name |
yes | string | |
behavior.state |
yes | string | Archived Behaviors keep their history but schedule no new Occurrences.; Values: active, archived |
behavior.archived_at |
yes | string or null | format: date-time; pattern: [Zz]$ |
behavior.auto_archived_at |
yes | string or null | Set on Behaviors that an end date archived automatically before Cadence stopped archiving on an end. New ends never set it.; format: date-time; pattern: [Zz]$ |
behavior.run_state |
yes | string | running schedules Occurrences; ended has passed its end and paused is inside a pause, both still active and shown under Not running; archived is archived.; Values: running, ended, paused, archived |
behavior.is_opportunity |
yes | boolean | True when the Behavior is available as an opportunity: the person can add it to today when there is room, with or without a schedule (contract 1.6.0). |
behavior.end_on |
yes | string or null | Last local day the Behavior runs. Null when it has no end.; format: date |
behavior.end_time |
yes | string or null | Local time on end_on when it stops. Null means it stops at the end of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
behavior.pause |
yes | object or null | The current or upcoming pause. Null when none is set or the pause is over. |
behavior.pause.from_on |
yes | string | First paused local day.; format: date |
behavior.pause.from_time |
yes | string or null | Local time on from_on when the pause starts. Null means the start of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
behavior.pause.back_on |
yes | string | Local day the Behavior runs again by itself, from the start of the day.; format: date |
behavior.end_date |
yes | string or null | Deprecated: read end_on. The day after end_on, kept for one minor version.; format: date |
behavior.default_duration_minutes |
yes | integer or null | minimum: 1 |
behavior.timezone |
yes | string | IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$ |
behavior.schedules |
yes | array | |
behavior.schedules[] |
yes | object | |
behavior.schedules[].id |
yes | string | format: uuid |
behavior.schedules[].recurrence |
yes | one of several shapes | Structured recurrence rule. Natural-language rules and cron syntax are not accepted. |
behavior.schedules[].recurrence.frequency |
yes | string | Value: daily |
behavior.schedules[].recurrence.interval |
yes | integer | Repeat every N days. 1 means every day.; minimum: 1 |
behavior.schedules[].recurrence.frequency |
yes | string | Value: interval_days |
behavior.schedules[].recurrence.interval_days |
yes | integer | Repeat every N days counted from the start date.; minimum: 1 |
behavior.schedules[].recurrence.frequency |
yes | string | Value: weekly |
behavior.schedules[].recurrence.interval |
yes | integer | Repeat every N weeks. 1 means every week.; minimum: 1 |
behavior.schedules[].recurrence.days_of_week |
yes | array | minItems: 1; maxItems: 7; uniqueItems: true |
behavior.schedules[].recurrence.days_of_week[] |
yes | string | Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday |
behavior.schedules[].recurrence.frequency |
yes | string | Value: monthly |
behavior.schedules[].recurrence.interval |
yes | integer | Repeat every N months.; minimum: 1 |
behavior.schedules[].recurrence.day_of_month |
yes | integer | Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31 |
behavior.schedules[].recurrence_summary |
yes | string | Plain-language recurrence, for example Weekly on Monday and Thursday. |
behavior.schedules[].time_entries |
yes | array | |
behavior.schedules[].time_entries[] |
yes | object | |
behavior.schedules[].time_entries[].id |
yes | string | format: uuid |
behavior.schedules[].time_entries[].kind |
yes | string | Values: exact, range |
behavior.schedules[].time_entries[].preset |
yes | string or null | Values: morning, afternoon, evening, night, null |
behavior.schedules[].time_entries[].start_time |
yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
behavior.schedules[].time_entries[].end_time |
yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
behavior.schedules[].time_entries[].label |
yes | string | Display label, for example 7:30 AM or Morning. |
behavior.schedules[].time_summary |
yes | string | |
behavior.schedule_summary |
yes | string | |
behavior.reminders |
yes | object | |
behavior.reminders.browser_enabled |
yes | boolean | |
behavior.reminders.email_enabled |
yes | boolean | |
behavior.reminders.offset_minutes |
yes | integer | minimum: 0 |
behavior.reminders.summary |
yes | string | |
behavior.archive_notes |
yes | array | |
behavior.archive_notes[] |
yes | object | |
behavior.archive_notes[].id |
yes | string | format: uuid |
behavior.archive_notes[].archived_at |
yes | string | format: date-time; pattern: [Zz]$ |
behavior.archive_notes[].note |
yes | string or null | |
behavior.archive_notes[].updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
behavior.external_ref |
yes | string or null | This client’s external record id, when it set one at creation. |
behavior.parent_behavior_id |
yes | string or null | Parent Behavior id when this is a sub-behavior. Null for a top-level Behavior (contract 1.7.0).; format: uuid |
behavior.sub_behavior_sort_order |
yes | integer | Position among the parent’s sub-behaviors, 0 first. 0 for a top-level Behavior.; minimum: 0; maximum: 9999 |
behavior.inherit_parent_schedule |
yes | boolean | True when this sub-behavior follows its parent’s schedule; its schedules then mirror the parent’s. Always false for a top-level Behavior. |
behavior.sub_behaviors |
yes | array | This Behavior’s sub-behaviors in display order, archived ones included. Empty for a sub-behavior or a Behavior without any. |
behavior.sub_behaviors[] |
yes | object | |
behavior.sub_behaviors[].id |
yes | string | format: uuid |
behavior.sub_behaviors[].title |
yes | string | |
behavior.sub_behaviors[].sub_behavior_sort_order |
yes | integer | Position among the parent’s sub-behaviors, 0 first.; minimum: 0; maximum: 9999 |
behavior.sub_behaviors[].inherit_parent_schedule |
yes | boolean | True when the sub-behavior follows its parent’s schedule. |
behavior.sub_behaviors[].active |
yes | boolean | False when the sub-behavior is archived. |
behavior.sub_behaviors[].run_state |
yes | string | Values: running, ended, paused, archived |
behavior.created_at |
yes | string | format: date-time; pattern: [Zz]$ |
behavior.updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
behavior.revision |
yes | string | Opaque version token of this record. Send it back as expected_revision to avoid overwriting a newer change.; minLength: 1; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
sub_behaviors |
no | array | The created sub-behaviors in order, when the call sent sub_behaviors (contract 1.7.0). |
sub_behaviors[] |
yes | object | A Behavior: a recurring thing the user tracks (a habit, routine, or recurring task). |
sub_behaviors[].id |
yes | string | format: uuid |
sub_behaviors[].title |
yes | string | |
sub_behaviors[].description |
yes | string or null | |
sub_behaviors[].location_text |
yes | string or null | |
sub_behaviors[].category |
yes | object or null | |
sub_behaviors[].category.id |
yes | string | format: uuid |
sub_behaviors[].category.name |
yes | string | |
sub_behaviors[].state |
yes | string | Archived Behaviors keep their history but schedule no new Occurrences.; Values: active, archived |
sub_behaviors[].archived_at |
yes | string or null | format: date-time; pattern: [Zz]$ |
sub_behaviors[].auto_archived_at |
yes | string or null | Set on Behaviors that an end date archived automatically before Cadence stopped archiving on an end. New ends never set it.; format: date-time; pattern: [Zz]$ |
sub_behaviors[].run_state |
yes | string | running schedules Occurrences; ended has passed its end and paused is inside a pause, both still active and shown under Not running; archived is archived.; Values: running, ended, paused, archived |
sub_behaviors[].is_opportunity |
yes | boolean | True when the Behavior is available as an opportunity: the person can add it to today when there is room, with or without a schedule (contract 1.6.0). |
sub_behaviors[].end_on |
yes | string or null | Last local day the Behavior runs. Null when it has no end.; format: date |
sub_behaviors[].end_time |
yes | string or null | Local time on end_on when it stops. Null means it stops at the end of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].pause |
yes | object or null | The current or upcoming pause. Null when none is set or the pause is over. |
sub_behaviors[].pause.from_on |
yes | string | First paused local day.; format: date |
sub_behaviors[].pause.from_time |
yes | string or null | Local time on from_on when the pause starts. Null means the start of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].pause.back_on |
yes | string | Local day the Behavior runs again by itself, from the start of the day.; format: date |
sub_behaviors[].end_date |
yes | string or null | Deprecated: read end_on. The day after end_on, kept for one minor version.; format: date |
sub_behaviors[].default_duration_minutes |
yes | integer or null | minimum: 1 |
sub_behaviors[].timezone |
yes | string | IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$ |
sub_behaviors[].schedules |
yes | array | |
sub_behaviors[].schedules[] |
yes | object | |
sub_behaviors[].schedules[].id |
yes | string | format: uuid |
sub_behaviors[].schedules[].recurrence |
yes | one of several shapes | Structured recurrence rule. Natural-language rules and cron syntax are not accepted. |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: daily |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N days. 1 means every day.; minimum: 1 |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: interval_days |
sub_behaviors[].schedules[].recurrence.interval_days |
yes | integer | Repeat every N days counted from the start date.; minimum: 1 |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: weekly |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N weeks. 1 means every week.; minimum: 1 |
sub_behaviors[].schedules[].recurrence.days_of_week |
yes | array | minItems: 1; maxItems: 7; uniqueItems: true |
sub_behaviors[].schedules[].recurrence.days_of_week[] |
yes | string | Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday |
sub_behaviors[].schedules[].recurrence.frequency |
yes | string | Value: monthly |
sub_behaviors[].schedules[].recurrence.interval |
yes | integer | Repeat every N months.; minimum: 1 |
sub_behaviors[].schedules[].recurrence.day_of_month |
yes | integer | Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31 |
sub_behaviors[].schedules[].recurrence_summary |
yes | string | Plain-language recurrence, for example Weekly on Monday and Thursday. |
sub_behaviors[].schedules[].time_entries |
yes | array | |
sub_behaviors[].schedules[].time_entries[] |
yes | object | |
sub_behaviors[].schedules[].time_entries[].id |
yes | string | format: uuid |
sub_behaviors[].schedules[].time_entries[].kind |
yes | string | Values: exact, range |
sub_behaviors[].schedules[].time_entries[].preset |
yes | string or null | Values: morning, afternoon, evening, night, null |
sub_behaviors[].schedules[].time_entries[].start_time |
yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].schedules[].time_entries[].end_time |
yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
sub_behaviors[].schedules[].time_entries[].label |
yes | string | Display label, for example 7:30 AM or Morning. |
sub_behaviors[].schedules[].time_summary |
yes | string | |
sub_behaviors[].schedule_summary |
yes | string | |
sub_behaviors[].reminders |
yes | object | |
sub_behaviors[].reminders.browser_enabled |
yes | boolean | |
sub_behaviors[].reminders.email_enabled |
yes | boolean | |
sub_behaviors[].reminders.offset_minutes |
yes | integer | minimum: 0 |
sub_behaviors[].reminders.summary |
yes | string | |
sub_behaviors[].archive_notes |
yes | array | |
sub_behaviors[].archive_notes[] |
yes | object | |
sub_behaviors[].archive_notes[].id |
yes | string | format: uuid |
sub_behaviors[].archive_notes[].archived_at |
yes | string | format: date-time; pattern: [Zz]$ |
sub_behaviors[].archive_notes[].note |
yes | string or null | |
sub_behaviors[].archive_notes[].updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
sub_behaviors[].external_ref |
yes | string or null | This client’s external record id, when it set one at creation. |
sub_behaviors[].parent_behavior_id |
yes | string or null | Parent Behavior id when this is a sub-behavior. Null for a top-level Behavior (contract 1.7.0).; format: uuid |
sub_behaviors[].sub_behavior_sort_order |
yes | integer | Position among the parent’s sub-behaviors, 0 first. 0 for a top-level Behavior.; minimum: 0; maximum: 9999 |
sub_behaviors[].inherit_parent_schedule |
yes | boolean | True when this sub-behavior follows its parent’s schedule; its schedules then mirror the parent’s. Always false for a top-level Behavior. |
sub_behaviors[].sub_behaviors |
yes | array | This Behavior’s sub-behaviors in display order, archived ones included. Empty for a sub-behavior or a Behavior without any. |
sub_behaviors[].sub_behaviors[] |
yes | object | |
sub_behaviors[].sub_behaviors[].id |
yes | string | format: uuid |
sub_behaviors[].sub_behaviors[].title |
yes | string | |
sub_behaviors[].sub_behaviors[].sub_behavior_sort_order |
yes | integer | Position among the parent’s sub-behaviors, 0 first.; minimum: 0; maximum: 9999 |
sub_behaviors[].sub_behaviors[].inherit_parent_schedule |
yes | boolean | True when the sub-behavior follows its parent’s schedule. |
sub_behaviors[].sub_behaviors[].active |
yes | boolean | False when the sub-behavior is archived. |
sub_behaviors[].sub_behaviors[].run_state |
yes | string | Values: running, ended, paused, archived |
sub_behaviors[].created_at |
yes | string | format: date-time; pattern: [Zz]$ |
sub_behaviors[].updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
sub_behaviors[].revision |
yes | string | Opaque version token of this record. Send it back as expected_revision to avoid overwriting a newer change.; minLength: 1; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
Example call
Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.
{
"name": "create_behavior",
"arguments": {
"title": "Drink water",
"schedules": [
{
"recurrence": {
"frequency": "daily",
"interval": 1
},
"time_entries": [
{
"kind": "exact",
"start_time": "09:00"
}
]
}
]
}
}
Example result
Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.
{
"behavior": {
"id": "00000001-1111-4111-8111-000000000001",
"title": "Morning walk",
"description": "Twenty minutes outside.",
"location_text": null,
"category": {
"id": "00000003-1111-4111-8111-000000000003",
"name": "Fitness"
},
"state": "active",
"archived_at": null,
"auto_archived_at": null,
"run_state": "running",
"is_opportunity": false,
"end_on": null,
"end_time": null,
"pause": null,
"end_date": null,
"default_duration_minutes": 20,
"timezone": "America/New_York",
"schedules": [
{
"id": "00000006-1111-4111-8111-000000000006",
"recurrence": {
"frequency": "weekly",
"interval": 1,
"days_of_week": [
"monday",
"thursday"
]
},
"recurrence_summary": "Weekly on Monday and Thursday",
"time_entries": [
{
"id": "00000007-1111-4111-8111-000000000007",
"kind": "exact",
"preset": null,
"start_time": "07:30",
"end_time": null,
"label": "7:30 AM"
},
{
"id": "00000008-1111-4111-8111-000000000008",
"kind": "range",
"preset": "evening",
"start_time": "18:00",
"end_time": "00:00",
"label": "Evening"
}
],
"time_summary": "7:30 AM, Evening"
}
],
"schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
"reminders": {
"browser_enabled": true,
"email_enabled": false,
"offset_minutes": 0,
"summary": "Browser reminder at the scheduled time"
},
"archive_notes": [],
"external_ref": null,
"parent_behavior_id": null,
"sub_behavior_sort_order": 0,
"inherit_parent_schedule": false,
"sub_behaviors": [],
"created_at": "2026-09-01T12:00:00Z",
"updated_at": "2026-10-18T13:00:00Z",
"revision": "b1.2026-10-18T13:00:00Z"
}
}
Errors
invalid_input: The input does not match the tool’s schema or rules.field_errorsnames each problem.authentication_required: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.rate_limited: Too many requests for this connection. Retry afterretry_after_seconds.service_unavailable: Cadence integrations are temporarily unavailable.internal_error: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the sameidempotency_key.insufficient_scope: The connection does not include the permission this tool needs.required_scopeslists it.not_found: No record with that id exists for this account.idempotency_key_reused: Theidempotency_keywas already used with a different input. Use a new key for a new request.invalid_state: The record’s current state does not allow this change.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.