{
  "openapi": "3.0.1",
  "info": {
    "title": "Shift Recovery Roster Source (Cal.com)",
    "description": "Retrieves authorized scheduling data from Cal.com, enriches it with a configurable workforce metadata source, and emits a normalized, deduplicated, validated roster/shift dataset for an autonomous shift-recovery workflow.",
    "version": "1.0",
    "x-build-id": "Qdtzk3reDewZh4rnt"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/yassyass~shift-recovery-roster/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-yassyass-shift-recovery-roster",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/yassyass~shift-recovery-roster/runs": {
      "post": {
        "operationId": "runs-sync-yassyass-shift-recovery-roster",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/yassyass~shift-recovery-roster/run-sync": {
      "post": {
        "operationId": "run-sync-yassyass-shift-recovery-roster",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "mode",
          "startTime",
          "endTime"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "live",
              "hybrid",
              "demo"
            ],
            "type": "string",
            "description": "live = Cal.com scheduling data only. hybrid = Cal.com scheduling data plus synthetic demo workforce metadata for any Cal.com user with no metadata entry. demo = fully synthetic hospital roster, no API calls, no credentials needed.",
            "default": "live"
          },
          "apiKey": {
            "title": "Cal.com API key",
            "type": "string",
            "description": "Cal.com API key (starts with `cal_`). Required for `live` and `hybrid` modes. Sent as an `Authorization: Bearer` header. Never logged. Falls back to the CAL_COM_API_KEY environment variable when left empty."
          },
          "baseUrl": {
            "title": "Cal.com API base URL",
            "type": "string",
            "description": "Base URL of the Cal.com API v2. Change only for self-hosted Cal.com instances.",
            "default": "https://api.cal.com/v2"
          },
          "startTime": {
            "title": "Window start",
            "type": "string",
            "description": "Start of the scheduling window. Accepts an ISO-8601 timestamp (2026-09-26T00:00:00Z), a date (2026-09-26), `now`, or a relative offset such as `now-1d` / `now+2h`.",
            "default": "now"
          },
          "endTime": {
            "title": "Window end",
            "type": "string",
            "description": "End of the scheduling window. Same formats as the window start. Must be after the window start.",
            "default": "now+7d"
          },
          "maxDateRangeDays": {
            "title": "Maximum window length (days)",
            "minimum": 1,
            "maximum": 730,
            "type": "integer",
            "description": "Safety cap on the window length. The run fails fast instead of paginating through an unbounded range.",
            "default": 90
          },
          "teamIds": {
            "title": "Team IDs",
            "type": "array",
            "description": "Restrict retrieval to these Cal.com team IDs. Empty = all teams the key can access.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "eventTypeIds": {
            "title": "Event type IDs",
            "type": "array",
            "description": "Restrict bookings to these Cal.com event type IDs. Empty = all event types.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "usernames": {
            "title": "Cal.com usernames",
            "type": "array",
            "description": "Restrict event-type lookups to these Cal.com usernames. Empty = the authenticated user and every accessible team.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "bookingStatuses": {
            "title": "Booking statuses",
            "type": "array",
            "description": "Cal.com booking statuses to retrieve. Each status is a separate paginated API walk. Empty = a single unfiltered walk across all statuses.",
            "items": {
              "type": "string",
              "enum": [
                "upcoming",
                "recurring",
                "past",
                "cancelled",
                "unconfirmed"
              ]
            },
            "default": [
              "upcoming"
            ]
          },
          "includeTeamMemberships": {
            "title": "Retrieve team memberships",
            "type": "boolean",
            "description": "Call /v2/teams and /v2/teams/{id}/memberships to discover the workforce roster. This is the primary worker source in live mode.",
            "default": true
          },
          "includeEventTypes": {
            "title": "Retrieve event types",
            "type": "boolean",
            "description": "Call /v2/event-types and /v2/teams/{id}/event-types to discover additional hosts and to resolve shift roles from event types.",
            "default": true
          },
          "includeSchedules": {
            "title": "Retrieve availability schedules",
            "type": "boolean",
            "description": "Call /v2/schedules and project the authenticated user's weekly availability into the requested window. Cal.com only exposes schedules for the authenticated user.",
            "default": true
          },
          "emitSchedulingEvents": {
            "title": "Emit raw scheduling events",
            "type": "boolean",
            "description": "Also emit one schedulingEvent record per Cal.com booking, next to the derived shift records. Useful for auditing what the scheduling system actually returned.",
            "default": true
          },
          "employeeMetadata": {
            "title": "Employee metadata (inline)",
            "type": "array",
            "description": "Array of employee metadata objects, matched to Cal.com users by email (case-insensitive), then calUsername, then calUserId. Example item: {\"employeeId\": \"E101\", \"email\": \"sarah@example.com\", \"role\": \"ICU_NURSE\", \"department\": \"ICU\", \"skills\": [\"ICU\", \"BLS\"], \"contractedHoursPerWeek\": 36}",
            "default": []
          },
          "employeeMetadataUrl": {
            "title": "Employee metadata URL",
            "type": "string",
            "description": "HTTPS URL returning a JSON array of employee metadata objects, or an object with an `employees` array. Merged with the inline list; inline entries win on conflict."
          },
          "employeeMetadataStoreKey": {
            "title": "Employee metadata key-value store key",
            "type": "string",
            "description": "Key in an Apify key-value store holding a JSON array of employee metadata objects. Handy for keeping the roster out of the run input."
          },
          "employeeMetadataStoreId": {
            "title": "Employee metadata key-value store ID",
            "type": "string",
            "description": "ID or name of the key-value store to read the metadata key from. Defaults to the run's own key-value store."
          },
          "shiftTypeMetadata": {
            "title": "Shift type metadata",
            "type": "array",
            "description": "Maps Cal.com event types to shift requirements. Match on eventTypeId or eventTypeSlug. Example item: {\"eventTypeSlug\": \"icu-night-shift\", \"role\": \"ICU_NURSE\", \"department\": \"ICU\", \"requiredSkills\": [\"ICU\", \"BLS\"]}",
            "default": []
          },
          "useDemoWorkforceMetadata": {
            "title": "Fall back to demo workforce metadata",
            "type": "boolean",
            "description": "When a Cal.com user has no metadata entry, synthesize a clearly-labelled demo one. Always on in hybrid and demo modes. Such records are labelled demo-workforce-metadata and flagged synthetic true.",
            "default": false
          },
          "pageSize": {
            "title": "Page size",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Items requested per API page. Cal.com caps bookings at 100.",
            "default": 100
          },
          "maxPagesPerResource": {
            "title": "Max pages per resource",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Hard stop on pagination loops per API resource. Reaching it is reported as a warning and marks the run partial.",
            "default": 100
          },
          "maxRecordsPerResource": {
            "title": "Max records per resource",
            "minimum": 1,
            "maximum": 500000,
            "type": "integer",
            "description": "Hard stop on how many raw records are pulled per API resource.",
            "default": 5000
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (seconds)",
            "minimum": 1,
            "maximum": 300,
            "type": "integer",
            "description": "Per-request timeout. Timed-out requests are retried according to the retry limit.",
            "default": 30
          },
          "maxRetries": {
            "title": "Max retries",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Retries for network errors, request timeouts, HTTP 429 and HTTP 5xx, using exponential backoff with jitter and honouring Retry-After.",
            "default": 4
          },
          "failOnEmptyResult": {
            "title": "Fail when no workers are found",
            "type": "boolean",
            "description": "Fail the run when the API call succeeded but produced zero worker records. Leave off to get a successful run whose summary record carries emptyResult true. Either way, an API failure always fails the run - it never turns into an empty dataset.",
            "default": false
          },
          "debug": {
            "title": "Debug logging",
            "type": "boolean",
            "description": "Raise the log level to DEBUG. Credentials are censored at every log level.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}