Create or update host profile — Calendar

Create the first host or replace its editable profile fields.

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

Declared permission: app_topolo_calendar.host: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.host: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
`displayName`	required	string	Host or external calendar display name. host.update requires it; external-calendar displayName is optional.
`timezone`	required	string	Valid IANA host timezone, such as Asia/Dubai; it controls local weekly-rule and date-override interpretation.
`avatarUrl`	optional	nullable/union	Profile image URL. On host.update omission/null falls back to the account avatar; it does not reliably preserve or clear a prior custom URL.
`headline`	optional	nullable/union	Optional host headline; omission/null on host.update resets it to null.
`bio`	optional	nullable/union	Optional host biography; omission/null on host.update resets it to null.

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:

{
  "displayName": "Example Studio",
  "timezone": "Asia/Dubai",
  "headline": null,
  "bio": null
}

Illustrative HTTP 200 source response:

{
  "host": {
    "id": "hst_example",
    "organizationId": "org_example",
    "workspaceId": "ws_calendar_example",
    "topoloUserId": "usr_example",
    "handle": "example-generated-handle",
    "displayName": "Example Studio",
    "avatarUrl": null,
    "headline": null,
    "bio": null,
    "timezone": "Asia/Dubai"
  }
}

host includes a generated/preserved handle. This illustration assumes there is no account avatar. Always inspect the actual returned avatarUrl; the source falls back to the account avatar when avatarUrl is omitted or null.

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

Effects and verification

Creates a first host or updates the existing profile.
Omitted headline/bio reset to null, and omitted/null avatarUrl uses the account avatar rather than preserving the prior custom avatar.

Read host.get and compare name, timezone, profile copy, avatar and generated handle.

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.
400	`invalid_timezone`	Use a valid IANA timezone such as Asia/Dubai.
400	`display_name_required`	Supply a nonempty displayName.
409	`handle_taken`	Reconcile the returned/generated handle conflict; do not change another host.

Recovery: For an existing host, deliberately restore all saved editable fields through host.update. A newly created host has no published host-delete action; do not infer workspace deletion can remove an in-use host.

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

app_topolo_calendar.host.get: Read the selected workspace host, including the unconfigured host:null state.
app_topolo_calendar.host.avatar.upload: Upload an avatar image and obtain its URL.
app_topolo_calendar.availability.update: Replace the entire weekly availability schedule.

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": {
    "displayName": {
      "type": "string",
      "minLength": 1
    },
    "timezone": {
      "type": "string",
      "minLength": 1
    },
    "avatarUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "headline": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "bio": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "displayName",
    "timezone"
  ],
  "additionalProperties": false
}

Output schema:

{
  "type": "object",
  "title": "Create or update host profile response",
  "description": "Operation result returned by host.update.",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "title": "host record",
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier when the host 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-host.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.
An update is not a partial merge for every field. Preserve intended existing avatar/headline/bio explicitly.