---
title: "create_behavior"
description: "Create Behavior: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/create_behavior
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# 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`: false
- `destructiveHint`: false
- `idempotentHint`: false
- `openWorldHint`: 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: <code>&#94;&#40;&#63;&#61;&#46;&#42;&#92;&#83;&#41;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` description ` | no | string | Optional description.; maxLength: ` 1000 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#48;&#56;&#92;&#117;&#48;&#48;&#48;&#98;&#92;&#117;&#48;&#48;&#48;&#99;&#92;&#117;&#48;&#48;&#48;&#101;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` location_text ` | no | string | Optional place where the Behavior happens, as plain text.; maxLength: ` 500 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` 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: <code>&#94;&#40;&#63;&#61;&#46;&#42;&#92;&#83;&#41;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` sub_behaviors[].description ` | no | string | Optional description.; maxLength: ` 1000 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#48;&#56;&#92;&#117;&#48;&#48;&#48;&#98;&#92;&#117;&#48;&#48;&#48;&#99;&#92;&#117;&#48;&#48;&#48;&#101;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` 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: <code>&#94;&#91;&#92;&#120;&#50;&#49;&#45;&#92;&#120;&#55;&#101;&#93;&#43;&#36;</code> |
| ` 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: <code>&#94;&#91;&#92;&#120;&#50;&#49;&#45;&#92;&#120;&#55;&#101;&#93;&#43;&#36;</code> |
| ` 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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.

```json
{
  "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.

```json
{
  "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_errors` names 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 after `retry_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 same `idempotency_key`.
- `insufficient_scope`: The connection does not include the permission this tool needs. `required_scopes` lists it.
- `not_found`: No record with that id exists for this account.
- `idempotency_key_reused`: The `idempotency_key` was 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](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
