Create, update, or cancel a locally authoritative event

The approved contract does not provide a longer purpose statement for this operation.

App

Calendar

Contract

Calendar API 1.6.0

Lifecycle

preview

Runtime

restricted

Operation ID

Not declared (legacy exception)

Canonical origin

Not declared; gateway routing required

Purpose and use cases

Create, update, or cancel a locally authoritative event

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

Business use cases and out-of-scope behavior are not yet declared in the approved OpenAPI description.

Request

POST /calendar/v1/event-commands

This contract intentionally declares no direct server URL. Obtain the routed App origin before attempting the request.

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:event: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

Request body

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

Runnable examples

curl '${APP_BASE_URL}/calendar/v1/event-commands' \
  --request POST \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "title": "<title>",
    "description": "<description>",
    "location": "<location>",
    "startsAt": "2026-08-21T18:00:00Z",
    "endsAt": "2026-08-21T18:00:00Z",
    "timezone": "<timezone>",
    "allDay": false,
    "status": "confirmed",
    "visibility": "standard",
    "attendeeActorReferences": [
      "<attendeeActorReferences>"
    ],
    "checkConflicts": true,
    "recurrence": null,
    "operation": "create",
    "collectionReference": "<collectionReference>"
  }'

const response = await fetch('${APP_BASE_URL}/calendar/v1/event-commands', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
  "title": "<title>",
  "description": "<description>",
  "location": "<location>",
  "startsAt": "2026-08-21T18:00:00Z",
  "endsAt": "2026-08-21T18:00:00Z",
  "timezone": "<timezone>",
  "allDay": false,
  "status": "confirmed",
  "visibility": "standard",
  "attendeeActorReferences": [
    "<attendeeActorReferences>"
  ],
  "checkConflicts": true,
  "recurrence": null,
  "operation": "create",
  "collectionReference": "<collectionReference>"
}),
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()

import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    '${APP_BASE_URL}/calendar/v1/event-commands',
    data=json.dumps({"title":"<title>","description":"<description>","location":"<location>","startsAt":"2026-08-21T18:00:00Z","endsAt":"2026-08-21T18:00:00Z","timezone":"<timezone>","allDay":false,"status":"confirmed","visibility":"standard","attendeeActorReferences":["<attendeeActorReferences>"],"checkConflicts":true,"recurrence":null,"operation":"create","collectionReference":"<collectionReference>"}).encode(),
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "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

Success response schema

{
  "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

• No detailed operation description.
• No stable operation ID (legacy exception).
• No direct server URL; gateway routing is unresolved here.
• 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.

Related operations and workflows

• POST /calendar/v1/attendance-commands — Record the authorized actor's response to an internal invitation
• POST /calendar/v1/recurrence-commands — Modify or cancel one materialized occurrence in a local series
• POST /calendar/v1/hold-commands — Create or release an expiring scheduling hold

Contract history and evidence

• Contract version: 1.6.0
• Approved snapshot SHA-256: 51244aff8a88e7985ddd9b3552be65108b7fab1fe0c81a3b93fda8a5c5e20dab
• Approval: Calendar lane (Claude), authorized by Anthony, 2026-08-21T23:03:07.458Z (calendar-readiness-endpoint-20260821)
• Download the authoritative OpenAPI 3.1 snapshot