Vision Developers
POST/calendar/v1/collection-commands

Create, rename, recolor or archive a calendar; set the default write target or per-actor preferences

create, rename, recolor and archive change the calendar record and require OWNERSHIP plus an expectedVersion — a writer grant lets an actor add events, not rename the calendar. default.set and preference.set write the calling actor's own preference row and carry no expectedVersion. The default write target must be writable (403 otherwise) and unique per actor, enforced by a partial unique index. Archiving a calendar clears it as every actor's default, because an archived calendar refuses every event create. A reference the actor cannot see returns 404, indistinguishable from a nonexistent one and from another workspace's. Requires an Idempotency-Key header.

App
Calendar
Contract
Calendar API 1.20.0
Lifecycle
preview
Runtime
restricted
Operation ID
createCollectionCommand
Canonical origin
https://calendar.runonvision.com

Availability: This is a preview contract with runtime status restricted. Publication documents an approved interface; it does not imply public production access.

Purpose and use cases

Create, rename, recolor or archive a calendar; set the default write target or per-actor preferences

The owning App is Vision Calendar. Calendar owns scheduling resources, workspace and actor bindings, visibility, recurrence, conflict, and concurrency rules.

Request

POST https://calendar.runonvision.com/calendar/v1/collection-commands

Authentication and authorization

Send a Vision-issued bearer token for the exact App audience. The token must include the calendar entitlement and satisfy the calendar workspace reference required binding.

  • Required scope: calendar:collection:write

Human roles are not declared in OpenAPI. Record-level and business permission checks remain the owning App's authority.

Headers

  • Authorization: Bearer <access-token> — required.
  • Accept: application/json — recommended where a JSON response is declared.
  • Content-Type: application/json — required for the documented request representation.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

NameLocationTypeRulesDescription
Idempotency-Keyheaderstringrequired; minimum length 16; maximum length 160; pattern ^[A-Za-z0-9._:-]+$Actor-scoped key. Reusing it with an identical parsed command replays the durable result; reusing it for a different command returns IDEMPOTENCY_CONFLICT.

Request body

Media type: application/json. The body is required.

object | object | object | object | object | object

Runnable examples

Placeholder values are generated from the approved schema and are not live credentials or customer data. Replace every angle-bracket or shell variable value. Examples cannot be run until the App has a routed base URL and your client has the required grant.

Create

Set operation to "create".

FieldTypeRulesDescription
operation"create"requiredNot described in the contract.
namestringrequired; minimum length 1; maximum length 120Not described in the contract.
colornull | HexColouroptional; default nullNot described in the contract.
kindpersonal | shared | resourceoptional; default "personal"provider_mapped and subscribed are deliberately not creatable: there is no provider OAuth or synchronisation in this version, so such a calendar would name a provider that was never contacted. Both remain valid stored kinds.
visibilityPolicyprivate | workspace_standard | workspace_availabilityoptional; default "private"Not described in the contract.
makeDefaultbooleanoptional; default falseNot described in the contract.
Create — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "create",
    "name": "<name>",
    "color": null,
    "kind": "personal",
    "visibilityPolicy": "private",
    "makeDefault": false
  }'
Create — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "create",
  "name": "<name>",
  "color": null,
  "kind": "personal",
  "visibilityPolicy": "private",
  "makeDefault": false
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Create — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"create","name":"<name>","color":null,"kind":"personal","visibilityPolicy":"private","makeDefault":false}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

Rename

Set operation to "rename".

FieldTypeRulesDescription
operation"rename"requiredNot described in the contract.
collectionReferencestringrequired; pattern ^COL-[A-Z0-9]{12}$Not described in the contract.
expectedVersionintegerrequired; minimum 1Not described in the contract.
namestringrequired; minimum length 1; maximum length 120Not described in the contract.
Rename — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "rename",
    "collectionReference": "<collectionReference>",
    "expectedVersion": 1,
    "name": "<name>"
  }'
Rename — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "rename",
  "collectionReference": "<collectionReference>",
  "expectedVersion": 1,
  "name": "<name>"
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Rename — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"rename","collectionReference":"<collectionReference>","expectedVersion":1,"name":"<name>"}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

Recolor

Set operation to "recolor".

FieldTypeRulesDescription
operation"recolor"requiredNot described in the contract.
collectionReferencestringrequired; pattern ^COL-[A-Z0-9]{12}$Not described in the contract.
expectedVersionintegerrequired; minimum 1Not described in the contract.
colornull | HexColourrequiredRequired and nullable. Send null to clear the colour; omitting the key is a malformed command rather than "leave it alone".
Recolor — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "recolor",
    "collectionReference": "<collectionReference>",
    "expectedVersion": 1,
    "color": "<color>"
  }'
Recolor — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "recolor",
  "collectionReference": "<collectionReference>",
  "expectedVersion": 1,
  "color": "<color>"
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Recolor — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"recolor","collectionReference":"<collectionReference>","expectedVersion":1,"color":"<color>"}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

Archive

Set operation to "archive".

FieldTypeRulesDescription
operation"archive"requiredNot described in the contract.
collectionReferencestringrequired; pattern ^COL-[A-Z0-9]{12}$Not described in the contract.
expectedVersionintegerrequired; minimum 1Not described in the contract.
Archive — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "archive",
    "collectionReference": "<collectionReference>",
    "expectedVersion": 1
  }'
Archive — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "archive",
  "collectionReference": "<collectionReference>",
  "expectedVersion": 1
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Archive — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"archive","collectionReference":"<collectionReference>","expectedVersion":1}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

Default Set

Set operation to "default.set".

FieldTypeRulesDescription
operation"default.set"requiredNot described in the contract.
collectionReferencestringrequired; pattern ^COL-[A-Z0-9]{12}$Not described in the contract.
Default Set — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "default.set",
    "collectionReference": "<collectionReference>"
  }'
Default Set — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "default.set",
  "collectionReference": "<collectionReference>"
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Default Set — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"default.set","collectionReference":"<collectionReference>"}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

Preference Set

Set operation to "preference.set".

FieldTypeRulesDescription
operation"preference.set"requiredNot described in the contract.
collectionReferencestringrequired; pattern ^COL-[A-Z0-9]{12}$Not described in the contract.
visiblebooleanoptionalNot described in the contract.
includeInAvailabilitybooleanoptionalNot described in the contract.
Preference Set — cURL
curl 'https://calendar.runonvision.com/calendar/v1/collection-commands' \
  --request POST \
  --header 'authorization: Bearer ***' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "operation": "preference.set",
    "collectionReference": "<collectionReference>",
    "visible": true,
    "includeInAvailability": true
  }'
Preference Set — JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/collection-commands', {
  method: 'POST',
  headers: {
  "authorization": "Bearer <ACCESS_TOKEN>",
  "accept": "application/json",
  "content-type": "application/json"
},
  body: JSON.stringify({
  "operation": "preference.set",
  "collectionReference": "<collectionReference>",
  "visible": true,
  "includeInAvailability": true
}),
})

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Preference Set — Python 3 standard library
import json
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/collection-commands',
    data=json.dumps({"operation":"preference.set","collectionReference":"<collectionReference>","visible":true,"includeInAvailability":true}).encode(),
    headers={
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Accept": "application/json",
    "content-type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

StatusMeaningSchema
200Command applied (rename, recolor, archive, default.set, preference.set)object
201Calendar createdobject
400Request validation failedobject
401Credential missing or invalidobject
403Credential lacks entitlement, scope, or active bindingobject
404No accessible record was foundobject
409Time conflict, stale record version, invalid state, or idempotency-key conflictobject
503Database or required configuration unavailableobject

Success response schema

FieldTypeRulesDescription
schemaVersion"vision-calendar-command-result.v1"requiredNot described in the contract.
operationevent.create | event.update | event.unlink | event.cancel | hold.create | hold.release | attendance.respond | recurrence.exception.cancel | recurrence.exception.modify | recurrence.series.update | availability.policy.set | availability.policy.reset | availability.exception.create | availability.exception.delete | collection.create | collection.rename | collection.recolor | collection.archive | collection.default.set | collection.preference.set | person.sharing.set | request_call.hold | request_call.confirm | request_call.release | request_call.cancelrequiredNot described in the contract.
outcome"succeeded"requiredNot described in the contract.
publicReferencestringrequiredNot described in the contract.
recordVersionintegerrequired; minimum 1Not described in the contract.
replayedbooleanrequiredNot described in the contract.
200 illustrative response
{
  "schemaVersion": "vision-calendar-command-result.v1",
  "operation": "event.create",
  "outcome": "succeeded",
  "publicReference": "<publicReference>",
  "recordVersion": 1,
  "replayed": true
}

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

  • 400 — Request validation failed
  • 401 — Credential missing or invalid
  • 403 — Credential lacks entitlement, scope, or active binding
  • 404 — No accessible record was found
  • 409 — Time conflict, stale record version, invalid state, or idempotency-key conflict
  • 503 — Database or required configuration unavailable

Collection behavior

Pagination: not declared. Filtering/search: not declared. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

  • Rate limit: No operation-specific limit or 429 response is declared.
  • Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
  • Idempotency: No idempotency header or replay window is declared.
  • Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

  • Keep client credentials and bearer tokens on trusted servers.
  • Send only to the exact approved HTTPS origin and audience.
  • Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
  • Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

  • The request body has no purpose or conditional-rule description.
  • Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Contract history and evidence