# List user availabilities

Returns availability schedules. Use `userId` to filter results for a specific user; omit it to return all accessible schedules. Each item includes schedule metadata, weekday slots, and linked event IDs.

Endpoint: GET /v1/userAvailabilities
Version: 1.0.0
Security: oauth2, bearerAuth

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: availabilities:read

  - `bearerAuth` (unknown)
    http bearer JWT scopes: availabilities:read

## Query parameters:

  - `userId` (integer)
    Optional user ID to return availabilities for a specific user.

## Response 200:

  - `200` (unknown)
    Availability schedules matching the request

## Response 200 fields (application/json):

  - `data` (array, required)
    List of availability schedules matching the request filter.

  - `data.id` (number, required)
    User availability id.

  - `data.userId` (number, required)
    Owner user ID.

  - `data.name` (string, required)
    Availability name.

  - `data.timeZone` (string, required)
    IANA time zone for this availability schedule.

  - `data.isDefault` (boolean, required)
    Whether this is the default availability for the user.

  - `data.createdAt` (any)
    Timestamp when the availability was created.

  - `data.userAvailabilityDays` (array, required)
    Weekday availability matrix for the schedule.

  - `data.userAvailabilityDays.id` (number, required)
    Availability day id.

  - `data.userAvailabilityDays.name` (string, required)
    Weekday name for this day entry.
    Enum: "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"

  - `data.userAvailabilityDays.active` (boolean, required)
    Whether at least one timing slot exists for this weekday.

  - `data.userAvailabilityDays.timings` (array, required)
    Timing slots for this weekday (can be empty).

  - `data.userAvailabilityDays.timings.startTime` (string, required)
    Start time in HH:mm format in the availability time zone.

  - `data.userAvailabilityDays.timings.endTime` (string, required)
    End time in HH:mm format in the availability time zone.

  - `data.eventId` (array, required)
    Event IDs currently associated with this availability.

## Response 400:

  - `400` (unknown)
    Bad request or validation failed

## Response 400 fields (application/json):

  - `message` (string, required)
    Human-readable summary (first field/form error for Zod validation failures).

  - `details` (object)
    Present when the failure is from createZodBodyValidator / createZodQueryValidator.

  - `details.formErrors` (array, required)
    Global form-level error messages

  - `details.fieldErrors` (object, required)
    Field name to list of validation error messages

  - `stack` (string)
    Present only in non-production environments.

## Response 401:

  - `401` (unknown)
    Unauthorized – missing or invalid API key (Bearer token required)

## Response 401 fields (application/json):

  - `message` (string, required)
    e.g. "API key is required" or "Invalid API key"

  - `code` (string)
    Optional code e.g. MISSING_API_KEY when rate limiter runs before valid auth

## Response 403:

  - `403` (unknown)
    Forbidden – insufficient permissions

## Response 403 fields (application/json):

  - `message` (string, required)

## Response 404:

  - `404` (unknown)
    Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND, EVENT_NOT_FOUND)

## Response 404 fields (application/json):

  - `message` (string, required)
    e.g. "Resource not found!" or "Record not found!"

## Response 429:

  - `429` (unknown)
    Rate limit exceeded. Per-account, per-action limits apply. Response may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After headers.

## Response 429 fields (application/json):

  - `code` (string, required)
    Fixed code for rate limit responses
    Enum: "RATE_LIMIT_EXCEEDED"

  - `message` (string, required)
    e.g. "Too many requests, please try again later."

  - `retryAfter` (number)
    Seconds until the rate limit window resets

  - `limit` (object)
    Configured limit (when using account-based rate limiter)

  - `limit.points` (number, required)

  - `limit.windowSec` (number, required)

## Response 429 headers (application/json):

  - `RateLimit-Limit` (string)
    Maximum requests allowed in the current window

  - `RateLimit-Remaining` (string)
    Requests remaining in the current window

  - `RateLimit-Reset` (string)
    ISO 8601 timestamp when the rate limit window resets

  - `Retry-After` (string)
    Seconds until the client can retry (when applicable)

## Response 500:

  - `500` (unknown)
    Internal server error. Prisma and unhandled errors return a generic message; stack is only included in non-production.

## Response 500 fields (application/json):

  - `message` (string, required)
    Generic: "Something went wrong" for Prisma errors, or error message

  - `stack` (string)
    Present only in non-production

## Response 400 examples:

  - `Zod validation (body/query)` (unknown)

## Response 401 examples:

  - `Missing API key` (unknown)

  - `Invalid API key` (unknown)

  - `Missing auth when rate limiter runs first` (unknown)

## Response 404 examples:

  - `Generic not found` (unknown)

  - `Record not found` (unknown)

## Response 500 examples:

  - `Generic (e.g. Prisma errors)` (unknown)

  - `Error with message` (unknown)