{
  "schemaVersion": "1.0",
  "title": "Cal.diy schedules",
  "description": "Use these capabilities to list or read schedules and to create, update, or delete weekly availability with dated overrides. This page owns all six schedule operations.",
  "canonical": "https://getaip.org/docs/connectors/cal-diy/capabilities/schedules",
  "route": "/docs/connectors/cal-diy/capabilities/schedules",
  "source": "docs/connectors/cal-diy/capabilities/schedules.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/cal-diy/capabilities/schedules.md",
    "txt": "/docs/download/connectors/cal-diy/capabilities/schedules.txt",
    "json": "/docs/download/connectors/cal-diy/capabilities/schedules.json",
    "pdf": "/docs/download/connectors/cal-diy/capabilities/schedules.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Cal.diy schedules\ndescription: Read and safely change weekly availability schedules and dated overrides\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: cal-diy\ncapabilityIds:\n  - cap:cal_diy:schedule.list\n  - cap:cal_diy:schedule.default.get\n  - cap:cal_diy:schedule.get\n  - cap:cal_diy:schedule.create\n  - cap:cal_diy:schedule.update\n  - cap:cal_diy:schedule.delete\n---\n\n# Cal.diy schedules\n\nUse these capabilities to list or read schedules and to create, update, or\ndelete weekly availability with dated overrides. This page owns all six\nschedule operations.\n\nSchedule operations use provider API version `2024-06-11`, rather than the\ngeneral Cal.diy version used by most other capability families.\n\n## Choose an operation\n\n| Capability | Provider request | Risk | Approval |\n|---|---|---|---|\n| `cap:cal_diy:schedule.list` | `GET /v2/schedules` | Low | No |\n| `cap:cal_diy:schedule.default.get` | `GET /v2/schedules/default` | Low | No |\n| `cap:cal_diy:schedule.get` | `GET /v2/schedules/{schedule_id}` | Low | No |\n| `cap:cal_diy:schedule.create` | `POST /v2/schedules` | Medium | Required |\n| `cap:cal_diy:schedule.update` | `PATCH /v2/schedules/{schedule_id}` | Medium | Required |\n| `cap:cal_diy:schedule.delete` | `DELETE /v2/schedules/{schedule_id}` | High | Required |\n\n## List or read schedules\n\nList and default get both accept an empty object:\n\n```json\n{}\n```\n\nRead one owned schedule with an integer provider id:\n\n```json\n{\n  \"schedule_id\": 41\n}\n```\n\nThe public get schema does not set a minimum for `schedule_id`; Cal.diy can\nreject an integer outside the provider's domain. Additional fields are rejected.\n\nAll three reads are low risk and approval-free at the capability level. The\nconnector does not publish the provider response field shape.\n\n## Create a schedule\n\nCreate requires a name, time zone, and explicit default choice:\n\n```json\n{\n  \"name\": \"Customer calls\",\n  \"timeZone\": \"Europe/London\",\n  \"isDefault\": false,\n  \"availability\": [\n    {\n      \"days\": [\"Monday\", \"Tuesday\", \"Wednesday\", \"Thursday\", \"Friday\"],\n      \"startTime\": \"09:00\",\n      \"endTime\": \"17:00\"\n    }\n  ],\n  \"overrides\": [\n    {\n      \"date\": \"2026-08-10\",\n      \"startTime\": \"11:00\",\n      \"endTime\": \"15:00\"\n    }\n  ]\n}\n```\n\n| Field | Constraint |\n|---|---|\n| `name` | Required non-empty string |\n| `timeZone` | Required non-empty string |\n| `isDefault` | Required boolean |\n| `availability` | Optional array of weekly intervals |\n| `overrides` | Optional array of dated intervals |\n\nBoth arrays may be empty. Additional fields are rejected at the schedule and\ninterval object boundaries.\n\n### Weekly availability\n\nEach `availability` entry requires:\n\n| Field | Constraint |\n|---|---|\n| `days` | Non-empty array with unique weekday values |\n| `startTime` | `HH:MM` in the range `00:00` through `23:59` |\n| `endTime` | The same `HH:MM` format |\n\nThe exact weekday enum is:\n\n```text\nMonday | Tuesday | Wednesday | Thursday | Friday | Saturday | Sunday\n```\n\nWeekday values are case-sensitive.\n\n### Dated overrides\n\nEach `overrides` entry requires an ISO date `date`, plus `startTime` and\n`endTime` in the same 24-hour format. One object represents one dated interval.\n\nThe connector schema does not verify that a start precedes its end, that\nintervals do not overlap, that override dates are unique, or that a named time\nzone makes a local time valid. Validate those rules before approval and rely on\nCal.diy for provider-owned schedule semantics.\n\nCreate is medium risk. It names `schedule.delete` as best-effort compensation.\nCompensation requires separate approval and is not automatic.\n\n## Update a schedule\n\nUpdate requires only `schedule_id`; every schedule property is optional:\n\n```json\n{\n  \"schedule_id\": 41,\n  \"name\": \"Customer calls and demos\",\n  \"isDefault\": true\n}\n```\n\nThe optional fields use the same schemas as create: `name`, `timeZone`,\n`isDefault`, `availability`, and `overrides`. The connector sends supplied\nfields as a provider patch but does not define provider merge or replacement\nsemantics for the two arrays.\n\nUnlike get and delete, update accepts `schedule_id` as either a string or an\ninteger. Its string branch has no minimum length. An identifier-only update or\nan empty string id can pass the published schema without expressing a useful\nprovider change; use an id obtained from a trusted schedule read and include an\nintentional patch field.\n\nBefore update, the connector reads the schedule selected by the same id. A\nsuccessful preflight does not lock the schedule or validate the proposed\navailability.\n\nUpdate is medium risk and has no compensating capability.\n\n## Delete a schedule\n\nDelete uses the same integer-only input as public get:\n\n```json\n{\n  \"schedule_id\": 41\n}\n```\n\nThe connector reads the selected schedule before deletion. Delete is high risk\nand destructive, and it has no rollback contract. Creating another schedule\nlater is a separate provider mutation; the connector declares no restoration\nof the original id, default assignment, or availability.\n\n## Shared read contract\n\nThe three reads are synchronous, retry-safe, and eligible for connector retry.\nTheir idempotency key is optional, action-scoped, and collision-checked against\nthe input hash. No capability-level human approval is required.\n\n## Shared mutation contract\n\nAll three mutations require:\n\n| Contract field | Value |\n|---|---|\n| Human approval | Required |\n| Approval selector | Tenant policy |\n| Approval validity window | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope |\n| Collision behavior | Revalidate input hash |\n| Connector retry | Not supported |\n| Retry safety | Unsafe |\n| Execution | Synchronous only |\n| Transaction modes | `dry_run`, `plan`, `commit`, `reconcile` |\n| Plan before commit | Not required |\n| Dry-run fidelity | Policy and schema only |\n\nCreate and update are medium risk. Delete is high risk, destructive, and uses\nthe destructive approval reason. None carries `send_message`.\n\nOnly create declares best-effort delete compensation. Update and delete declare\nrollback as not supported.\n\n## Data and result contract\n\nThe family is classified as confidential. Its contract does not declare PII\nand does not require redaction. Deployment policy may apply stricter handling\nto provider output or tenant-specific schedule names.\n\nThe connector returns the validated provider JSON body. A non-empty string\n`status` is required. `data`, `pagination`, and additional provider fields are\noptional and provider-owned.\n\nThe common response scrubber still replaces secret-, key-, and token-named\nvalues with `[REDACTED]`. It is not a general confidential-data filter.\n\n## Failures and recovery\n\n| Failure | Relevant cause | Safe response |\n|---|---|---|\n| `connector.cal_diy.invalid_action` | Invalid id, weekday, time, date, or unknown field | Correct the exact input before another call |\n| `connector.cal_diy.policy` | Mutation omitted its required idempotency key | Preserve approved input and add the missing key |\n| `connector.cal_diy.idempotency_collision` | One key owns different mutation input | Stop and inspect the original action |\n| `connector.cal_diy.in_flight` | A matching schedule mutation is executing | Read durable state and wait |\n| `connector.cal_diy.outcome_unknown` | Prior provider dispatch cannot be proved | Reconcile; do not create a replacement key |\n| `connector.cal_diy.authentication` | Provider returned `401` or `403` | Verify account binding, credentials, and schedule ownership |\n| `connector.cal_diy.state_conflict` | Provider returned `409` or `412` | Refresh the schedule and review the change |\n| `connector.cal_diy.rate_limited` | Provider returned `429` | Retry reads within policy; reconcile mutations |\n| `connector.cal_diy.remote_temporary` | Provider returned a server error | Retry reads within policy; reconcile mutations |\n| `connector.cal_diy.transport` | Provider exchange failed | Retry reads only; treat dispatched mutations as uncertain |\n| `connector.cal_diy.invalid_provider_output` | Successful response lacked valid `status` | Preserve evidence and reconcile a mutation |\n\nPermanent rejection, invalid credentials, oversized responses, and durable\nsettlement failures use the common Cal.diy error family. Gateway and lifecycle\nerrors are described in the [global error reference](../../../reference/errors.md).\n\n## Verify schedule handling\n\nFor a read, retain the capability, schedule selector, actor, tenant, external\naccount, response status, and provider request id when present.\n\nFor a mutation, also retain approval evidence and the original idempotency key.\nWait for a completed durable result, then read the exact schedule or list\nschedules and compare only the intended fields. For uncertain dispatch,\nreconcile the original operation before another mutation.\n\nThese checks validate application handling. They do not prove bookability,\ntime-zone correctness, non-overlap, event-type propagation, live-provider\nqualification, or production readiness.\n\n## Related documentation\n\n- [Cal.diy capability index](README.md)\n- [Event types, private links, and webhooks](event-types-and-private-links.md)\n- [Calendars and free/busy](calendars-and-free-busy.md)\n- [Approvals and policy](../../../concepts/approvals-and-policy.md)\n- [Transactions and compensation](../../../concepts/transactions-and-compensation.md)\n",
    "text": "Cal.diy schedules\n\nUse these capabilities to list or read schedules and to create, update, or\ndelete weekly availability with dated overrides. This page owns all six\nschedule operations.\n\nSchedule operations use provider API version 2024-06-11, rather than the\ngeneral Cal.diy version used by most other capability families.\n\nChoose an operation\n\n| Capability | Provider request | Risk | Approval |\n\n| cap:caldiy:schedule.list | GET /v2/schedules | Low | No |\n| cap:caldiy:schedule.default.get | GET /v2/schedules/default | Low | No |\n| cap:caldiy:schedule.get | GET /v2/schedules/{scheduleid} | Low | No |\n| cap:caldiy:schedule.create | POST /v2/schedules | Medium | Required |\n| cap:caldiy:schedule.update | PATCH /v2/schedules/{scheduleid} | Medium | Required |\n| cap:caldiy:schedule.delete | DELETE /v2/schedules/{scheduleid} | High | Required |\n\nList or read schedules\n\nList and default get both accept an empty object:\n\n{}\n\nRead one owned schedule with an integer provider id:\n\n{\n  \"scheduleid\": 41\n}\n\nThe public get schema does not set a minimum for scheduleid; Cal.diy can\nreject an integer outside the provider's domain. Additional fields are rejected.\n\nAll three reads are low risk and approval-free at the capability level. The\nconnector does not publish the provider response field shape.\n\nCreate a schedule\n\nCreate requires a name, time zone, and explicit default choice:\n\n{\n  \"name\": \"Customer calls\",\n  \"timeZone\": \"Europe/London\",\n  \"isDefault\": false,\n  \"availability\": [\n    {\n      \"days\": [\"Monday\", \"Tuesday\", \"Wednesday\", \"Thursday\", \"Friday\"],\n      \"startTime\": \"09:00\",\n      \"endTime\": \"17:00\"\n    }\n  ],\n  \"overrides\": [\n    {\n      \"date\": \"2026-08-10\",\n      \"startTime\": \"11:00\",\n      \"endTime\": \"15:00\"\n    }\n  ]\n}\n\n| Field | Constraint |\n\n| name | Required non-empty string |\n| timeZone | Required non-empty string |\n| isDefault | Required boolean |\n| availability | Optional array of weekly intervals |\n| overrides | Optional array of dated intervals |\n\nBoth arrays may be empty. Additional fields are rejected at the schedule and\ninterval object boundaries.\n\nWeekly availability\n\nEach availability entry requires:\n\n| Field | Constraint |\n\n| days | Non-empty array with unique weekday values |\n| startTime | HH:MM in the range 00:00 through 23:59 |\n| endTime | The same HH:MM format |\n\nThe exact weekday enum is:\n\nMonday | Tuesday | Wednesday | Thursday | Friday | Saturday | Sunday\n\nWeekday values are case-sensitive.\n\nDated overrides\n\nEach overrides entry requires an ISO date date, plus startTime and\nendTime in the same 24-hour format. One object represents one dated interval.\n\nThe connector schema does not verify that a start precedes its end, that\nintervals do not overlap, that override dates are unique, or that a named time\nzone makes a local time valid. Validate those rules before approval and rely on\nCal.diy for provider-owned schedule semantics.\n\nCreate is medium risk. It names schedule.delete as best-effort compensation.\nCompensation requires separate approval and is not automatic.\n\nUpdate a schedule\n\nUpdate requires only scheduleid; every schedule property is optional:\n\n{\n  \"scheduleid\": 41,\n  \"name\": \"Customer calls and demos\",\n  \"isDefault\": true\n}\n\nThe optional fields use the same schemas as create: name, timeZone,\nisDefault, availability, and overrides. The connector sends supplied\nfields as a provider patch but does not define provider merge or replacement\nsemantics for the two arrays.\n\nUnlike get and delete, update accepts scheduleid as either a string or an\ninteger. Its string branch has no minimum length. An identifier-only update or\nan empty string id can pass the published schema without expressing a useful\nprovider change; use an id obtained from a trusted schedule read and include an\nintentional patch field.\n\nBefore update, the connector reads the schedule selected by the same id. A\nsuccessful preflight does not lock the schedule or validate the proposed\navailability.\n\nUpdate is medium risk and has no compensating capability.\n\nDelete a schedule\n\nDelete uses the same integer-only input as public get:\n\n{\n  \"scheduleid\": 41\n}\n\nThe connector reads the selected schedule before deletion. Delete is high risk\nand destructive, and it has no rollback contract. Creating another schedule\nlater is a separate provider mutation; the connector declares no restoration\nof the original id, default assignment, or availability.\n\nShared read contract\n\nThe three reads are synchronous, retry-safe, and eligible for connector retry.\nTheir idempotency key is optional, action-scoped, and collision-checked against\nthe input hash. No capability-level human approval is required.\n\nShared mutation contract\n\nAll three mutations require:\n\n| Contract field | Value |\n\n| Human approval | Required |\n| Approval selector | Tenant policy |\n| Approval validity window | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope |\n| Collision behavior | Revalidate input hash |\n| Connector retry | Not supported |\n| Retry safety | Unsafe |\n| Execution | Synchronous only |\n| Transaction modes | dryrun, plan, commit, reconcile |\n| Plan before commit | Not required |\n| Dry-run fidelity | Policy and schema only |\n\nCreate and update are medium risk. Delete is high risk, destructive, and uses\nthe destructive approval reason. None carries sendmessage.\n\nOnly create declares best-effort delete compensation. Update and delete declare\nrollback as not supported.\n\nData and result contract\n\nThe family is classified as confidential. Its contract does not declare PII\nand does not require redaction. Deployment policy may apply stricter handling\nto provider output or tenant-specific schedule names.\n\nThe connector returns the validated provider JSON body. A non-empty string\nstatus is required. data, pagination, and additional provider fields are\noptional and provider-owned.\n\nThe common response scrubber still replaces secret-, key-, and token-named\nvalues with [REDACTED]. It is not a general confidential-data filter.\n\nFailures and recovery\n\n| Failure | Relevant cause | Safe response |\n\n| connector.caldiy.invalidaction | Invalid id, weekday, time, date, or unknown field | Correct the exact input before another call |\n| connector.caldiy.policy | Mutation omitted its required idempotency key | Preserve approved input and add the missing key |\n| connector.caldiy.idempotencycollision | One key owns different mutation input | Stop and inspect the original action |\n| connector.caldiy.inflight | A matching schedule mutation is executing | Read durable state and wait |\n| connector.caldiy.outcomeunknown | Prior provider dispatch cannot be proved | Reconcile; do not create a replacement key |\n| connector.caldiy.authentication | Provider returned 401 or 403 | Verify account binding, credentials, and schedule ownership |\n| connector.caldiy.stateconflict | Provider returned 409 or 412 | Refresh the schedule and review the change |\n| connector.caldiy.ratelimited | Provider returned 429 | Retry reads within policy; reconcile mutations |\n| connector.caldiy.remotetemporary | Provider returned a server error | Retry reads within policy; reconcile mutations |\n| connector.caldiy.transport | Provider exchange failed | Retry reads only; treat dispatched mutations as uncertain |\n| connector.caldiy.invalidprovideroutput | Successful response lacked valid status | Preserve evidence and reconcile a mutation |\n\nPermanent rejection, invalid credentials, oversized responses, and durable\nsettlement failures use the common Cal.diy error family. Gateway and lifecycle\nerrors are described in the global error reference (../../../reference/errors.md).\n\nVerify schedule handling\n\nFor a read, retain the capability, schedule selector, actor, tenant, external\naccount, response status, and provider request id when present.\n\nFor a mutation, also retain approval evidence and the original idempotency key.\nWait for a completed durable result, then read the exact schedule or list\nschedules and compare only the intended fields. For uncertain dispatch,\nreconcile the original operation before another mutation.\n\nThese checks validate application handling. They do not prove bookability,\ntime-zone correctness, non-overlap, event-type propagation, live-provider\nqualification, or production readiness.\n\nRelated documentation\n• Cal.diy capability index (README.md)\n• Event types, private links, and webhooks (event-types-and-private-links.md)\n• Calendars and free/busy (calendars-and-free-busy.md)\n• Approvals and policy (../../../concepts/approvals-and-policy.md)\n• Transactions and compensation (../../../concepts/transactions-and-compensation.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "544df42cec7fc706e5dc09821c001220bc4b396c1c75b423b4cd94e850242a94"
  }
}