Update availability — Calendar

Replace the entire weekly availability schedule.

Action: app_topolo_calendar.availability.update · PUT /api/admin/availability

Declared permission: app_topolo_calendar.availability:write. For authorized Calendar users; permissions and resource access still apply.

Before you start

Use the current credential to confirm the production organization and inspect this exact action before preparing a call.
Declared permission: app_topolo_calendar.availability:write. Permission discovery is not a grant.
Discover the authorized Calendar workspace and pass it as resourceType=workspace/resourceId separately from this action input. Calendar records and IDs are scoped to the selected host/workspace.
Validate and plan the exact payload, obtain effect-specific authorization, then execute unchanged only in a separately authorized operational task. Do not run these synthetic inputs.

Inputs and field meanings

Field	Presence	Declared constraint	Meaning
`rules`	required	array	Complete replacement weekly schedule. Omitted weekdays are unavailable; an empty array closes weekly availability.
`rules[].dayOfWeek`	required	integer; minimum=0; maximum=6	Weekday number 0 Sunday through 6 Saturday; Monday is 1.
`rules[].startMinute`	required	integer; minimum=0; maximum=1439	Integer minutes after local midnight. Must be less than endMinute when a window is supplied.
`rules[].endMinute`	required	integer; minimum=1; maximum=1440	Integer end minutes after local midnight; later than startMinute and at most1440.

Worked request and response

Source-reviewed illustration only. Nothing below was executed; all identifiers, counts, states, credentials and URLs are synthetic. Replace identifiers through discovery before any separately authorized call.

Resource context: workspace; it is not an extra action input field.

Illustrative action input:

{
  "rules": [
    {
      "dayOfWeek": 1,
      "startMinute": 540,
      "endMinute": 1020
    }
  ]
}

Illustrative HTTP 200 source response:

{
  "rules": [
    {
      "id": "rul_example",
      "hostId": "hst_example",
      "dayOfWeek": 1,
      "startMinute": 540,
      "endMinute": 1020
    }
  ],
  "overrides": [
    {
      "id": "ovr_example",
      "hostId": "hst_example",
      "date": "2026-11-20",
      "startMinute": null,
      "endMinute": null
    }
  ]
}

The result contains the replacement rules plus retained date overrides. Only Monday is offered by the weekly rule; omitted weekdays are unavailable. Rule IDs can change on replacement.

The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.

Effects and verification

Deletes prior weekly rules and inserts the supplied complete array.
Does not cancel existing bookings or remove date overrides.

Read availability.get and compare the full intended weekly schedule and retained overrides.

Refusals and recovery

Selected source refusals are listed below; runtime middleware can return additional structured errors.

HTTP	Error	Supported response
403	`forbidden`	Reconcile the declared permission, organization and verified resource grant with the legitimate access owner; do not switch context to bypass a refusal.
404	`no_host`	Read host.get; if it returns host:null, create the intended workspace host through host.update before retrying.
400	`invalid_availability_rule`	Each day must be 0–6, and integer minutes must satisfy0<=start<end<=1440.

Recovery: Retain the full previous rules array, then deliberately replace with that snapshot. This cannot undo bookings made while availability was changed.

After an uncertain mutation, reconcile the named records and provider/delivery evidence before repeating it.

app_topolo_calendar.availability.get: Read the current host’s complete weekly rules and date overrides.
app_topolo_calendar.availability.overrides.list: Discover date override IDs before updating or deleting one.

Declared schemas and provenance

The hidden action guide carries these exact current declared schemas. They are not rewritten to make the illustrations pass.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dayOfWeek": {
            "type": "integer",
            "minimum": 0,
            "maximum": 6
          },
          "startMinute": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1439
          },
          "endMinute": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1440
          }
        },
        "required": [
          "dayOfWeek",
          "startMinute",
          "endMinute"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "rules"
  ],
  "additionalProperties": false
}

Output schema:

{
  "type": "object",
  "title": "Update availability response",
  "description": "Operation result returned by availability.update.",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "title": "availability record",
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier when the availability exposes one."
            }
          },
          "additionalProperties": true
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "result": {
      "type": "object",
      "additionalProperties": true
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "x-topolo-contract-source": "derived-action-metadata",
  "x-topolo-contract-precision": "structural"
}

Source: TopoloCalendar@b378ceb73800ee1d1e6c4ff6f0b4179918cf632c, apps/api/src/routes/admin-availability.ts. Current catalog metadata and source were compared without executing the application.

Source-reviewed synthetic input/response; not captured or executed.
Source revision is not proof of current deployment, caller access, provider connection or notification delivery.
The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.