Open bookable slots across one or more actors

Returns the slots that are actually bookable for the requested actors, with working hours, availability exceptions, existing events, expanded recurrence occurrences and ACTIVE UNEXPIRED HOLDS already applied. Calendar performs the timezone and interval arithmetic so a caller does not have to; GET /calendar/v1/availability/{actorReference} returns the raw inputs instead and does not account for holds. An actor with no active availability policy contributes no bookable time.

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

Open bookable slots across one or more actors

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

Request

POST /calendar/v1/availability/slots

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:availability:read

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

This operation declares no path or query parameters.

Request body

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

Runnable examples

curl '${APP_BASE_URL}/calendar/v1/availability/slots' \
  --request POST \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "actorReferences": [
      "<actorReferences>"
    ],
    "from": "2026-08-21T18:00:00Z",
    "to": "2026-08-21T18:00:00Z",
    "durationMinutes": 5,
    "slotIntervalMinutes": 5,
    "requirement": "any",
    "limit": 100
  }'

const response = await fetch('${APP_BASE_URL}/calendar/v1/availability/slots', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
  "actorReferences": [
    "<actorReferences>"
  ],
  "from": "2026-08-21T18:00:00Z",
  "to": "2026-08-21T18:00:00Z",
  "durationMinutes": 5,
  "slotIntervalMinutes": 5,
  "requirement": "any",
  "limit": 100
}),
}

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/availability/slots',
    data=json.dumps({"actorReferences":["<actorReferences>"],"from":"2026-08-21T18:00:00Z","to":"2026-08-21T18:00:00Z","durationMinutes":5,"slotIntervalMinutes":5,"requirement":"any","limit":100}).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-availability-slots.v1",
  "range": {
    "from": "2026-08-21T18:00:00Z",
    "to": "2026-08-21T18:00:00Z"
  },
  "durationMinutes": 1,
  "requirement": "any",
  "slots": [
    {
      "startsAt": "2026-08-21T18:00:00Z",
      "endsAt": "2026-08-21T18:00:00Z",
      "actorReferences": [
        "<actorReferences>"
      ]
    }
  ]
}

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
• 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 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

• GET /calendar/v1/agenda — Authorized, visibility-filtered agenda
• GET /calendar/v1/events/{reference} — Authorized event details
• GET /calendar/v1/availability/{actorReference} — Working hours, exceptions, and free/busy without event details
• POST /calendar/v1/conflicts — Find event and active-hold conflicts without record details
• POST /calendar/v1/availability-commands — Set working hours, or create and delete availability exceptions
• GET /calendar/v1/presentation — Calendar's interface, described for this caller

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