Skip to content

Automate browser based workflows with AI

feat(SKY-8585): expose schedule routes in OpenAPI for SDK generation (#5408)

Aaron Perez2d4ed49b7ecb
diff --git a/skyvern/forge/agent_functions.py b/skyvern/forge/agent_functions.py
index c1384aaaa..4b1a1b80c 100644
--- a/skyvern/forge/agent_functions.py
+++ b/skyvern/forge/agent_functions.py
@@ -431,6 +431,13 @@ async def _convert_css_shape_to_string(
class AgentFunction:
+ workflow_schedules_enabled: bool = False
+ """Whether the workflow scheduler routes should serve traffic on this build.
+
+ OSS Skyvern has no scheduling backend wired up by default, so the routes return 501.
+ Cloud overrides this to True and provides the Temporal-backed implementations below.
+ """
+
async def validate_step_execution(
self,
task: Task,
@@ -493,6 +500,45 @@ class AgentFunction:
async def post_cache_step_execution(self, task: Task, step: Step) -> None:
return
+ def build_workflow_schedule_id(self, workflow_schedule_id: str) -> str | None:
+ """Return the backend-specific schedule id used by the execution engine.
+
+ OSS has no execution backend, so this returns None and the schedule simply
+ lives in the database. Cloud overrides this to derive a Temporal schedule id.
+ """
+ return None
+
+ async def upsert_workflow_schedule(
+ self,
+ backend_schedule_id: str,
+ organization_id: str,
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ cron_expression: str,
+ timezone: str,
+ enabled: bool,
+ parameters: dict[str, Any] | None = None,
+ ) -> None:
+ """Upsert a recurring schedule with the execution backend (e.g. Temporal).
+
+ OSS base is a no-op so the route layer can stay backend-agnostic.
+ Cloud overrides this to register the schedule with Temporal.
+ Implementations must be idempotent.
+ """
+ return None
+
+ async def set_workflow_schedule_enabled(self, backend_schedule_id: str, enabled: bool) -> None:
+ """Pause or resume a schedule on the execution backend. OSS no-op."""
+ return None
+
+ async def delete_workflow_schedule(self, backend_schedule_id: str) -> None:
+ """Delete a schedule from the execution backend. OSS no-op.
+
+ Implementations must be idempotent — deleting an already-absent schedule
+ should succeed silently rather than raising.
+ """
+ return None
+
async def auto_solve_captchas(self, page: Page) -> bool:
"""Proactively detect and solve captchas on the current page.
Returns True if a captcha was detected and solved.
diff --git a/skyvern/forge/sdk/db/agent_db.py b/skyvern/forge/sdk/db/agent_db.py
index 5cd02de79..b0b82e941 100644
--- a/skyvern/forge/sdk/db/agent_db.py
+++ b/skyvern/forge/sdk/db/agent_db.py
@@ -547,8 +547,8 @@ class AgentDB(BaseAlchemyDB):
async def create_workflow_schedule_with_limit(self, *args: Any, **kwargs: Any) -> Any:
return await self.schedules.create_workflow_schedule_with_limit(*args, **kwargs)
- async def set_temporal_schedule_id(self, *args: Any, **kwargs: Any) -> Any:
- return await self.schedules.set_temporal_schedule_id(*args, **kwargs)
+ async def set_backend_schedule_id(self, *args: Any, **kwargs: Any) -> Any:
+ return await self.schedules.set_backend_schedule_id(*args, **kwargs)
async def update_workflow_schedule(self, *args: Any, **kwargs: Any) -> Any:
return await self.schedules.update_workflow_schedule(*args, **kwargs)
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index a58470a19..afbc5fe8e 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -352,7 +352,7 @@ class WorkflowScheduleModel(Base):
timezone = Column(String, nullable=False)
enabled = Column(Boolean, nullable=False, default=True, server_default=sqlalchemy.true())
parameters = Column(JSON, nullable=True)
- temporal_schedule_id = Column(String, nullable=True)
+ backend_schedule_id = Column("temporal_schedule_id", String, nullable=True)
name = Column(String, nullable=True)
description = Column(String, nullable=True)
diff --git a/skyvern/forge/sdk/db/repositories/schedules.py b/skyvern/forge/sdk/db/repositories/schedules.py
index ac318de3f..84bbcf7ed 100644
--- a/skyvern/forge/sdk/db/repositories/schedules.py
+++ b/skyvern/forge/sdk/db/repositories/schedules.py
@@ -50,7 +50,7 @@ class SchedulesRepository(BaseRepository):
timezone: str,
enabled: bool,
parameters: dict[str, Any] | None = None,
- temporal_schedule_id: str | None = None,
+ backend_schedule_id: str | None = None,
name: str | None = None,
description: str | None = None,
) -> WorkflowSchedule:
@@ -62,7 +62,7 @@ class SchedulesRepository(BaseRepository):
timezone=timezone,
enabled=enabled,
parameters=parameters,
- temporal_schedule_id=temporal_schedule_id,
+ backend_schedule_id=backend_schedule_id,
name=name,
description=description,
)
@@ -181,12 +181,12 @@ class SchedulesRepository(BaseRepository):
await session.refresh(workflow_schedule)
return convert_to_workflow_schedule(workflow_schedule, self.debug_enabled), count
- @db_operation("set_temporal_schedule_id")
- async def set_temporal_schedule_id(
+ @db_operation("set_backend_schedule_id")
+ async def set_backend_schedule_id(
self,
workflow_schedule_id: str,
organization_id: str,
- temporal_schedule_id: str,
+ backend_schedule_id: str,
) -> WorkflowSchedule | None:
async with self.Session() as session:
workflow_schedule = (
@@ -202,7 +202,7 @@ class SchedulesRepository(BaseRepository):
if not workflow_schedule:
return None
- workflow_schedule.temporal_schedule_id = temporal_schedule_id
+ workflow_schedule.backend_schedule_id = backend_schedule_id
workflow_schedule.modified_at = datetime.now(UTC)
await session.commit()
await session.refresh(workflow_schedule)
@@ -217,7 +217,7 @@ class SchedulesRepository(BaseRepository):
timezone: str,
enabled: bool,
parameters: dict[str, Any] | None = None,
- temporal_schedule_id: str | None | object = _UNSET,
+ backend_schedule_id: str | None | object = _UNSET,
name: str | None | object = _UNSET,
description: str | None | object = _UNSET,
) -> WorkflowSchedule | None:
@@ -239,8 +239,8 @@ class SchedulesRepository(BaseRepository):
workflow_schedule.timezone = timezone
workflow_schedule.enabled = enabled
workflow_schedule.parameters = parameters
- if temporal_schedule_id is not _UNSET:
- workflow_schedule.temporal_schedule_id = temporal_schedule_id
+ if backend_schedule_id is not _UNSET:
+ workflow_schedule.backend_schedule_id = backend_schedule_id
if name is not _UNSET:
workflow_schedule.name = name
if description is not _UNSET:
diff --git a/skyvern/forge/sdk/routes/__init__.py b/skyvern/forge/sdk/routes/__init__.py
index 4c06f74a3..21cf69d28 100644
--- a/skyvern/forge/sdk/routes/__init__.py
+++ b/skyvern/forge/sdk/routes/__init__.py
@@ -10,6 +10,7 @@ from skyvern.forge.sdk.routes import scripts # noqa: F401
from skyvern.forge.sdk.routes import sdk # noqa: F401
from skyvern.forge.sdk.routes import webhooks # noqa: F401
from skyvern.forge.sdk.routes import workflow_copilot # noqa: F401
+from skyvern.forge.sdk.routes import workflow_schedules # noqa: F401
from skyvern.forge.sdk.routes.streaming import cdp_input # noqa: F401
from skyvern.forge.sdk.routes.streaming import messages # noqa: F401
from skyvern.forge.sdk.routes.streaming import screenshot # noqa: F401
diff --git a/skyvern/forge/sdk/routes/workflow_schedules.py b/skyvern/forge/sdk/routes/workflow_schedules.py
new file mode 100644
index 000000000..a5fac194f
--- /dev/null
+++ b/skyvern/forge/sdk/routes/workflow_schedules.py
@@ -0,0 +1,672 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+import structlog
+from fastapi import Depends, HTTPException, Query, status
+
+from skyvern.forge import app
+from skyvern.forge.sdk.core.permissions.schedule_limit_checker import ScheduleLimitCheckerFactory
+from skyvern.forge.sdk.db.agent_db import ScheduleLimitExceededError
+from skyvern.forge.sdk.routes.routers import base_router, legacy_base_router
+from skyvern.forge.sdk.schemas.organizations import Organization
+from skyvern.forge.sdk.schemas.workflow_schedules import (
+ DeleteScheduleResponse,
+ OrganizationScheduleListResponse,
+ WorkflowSchedule,
+ WorkflowScheduleListResponse,
+ WorkflowScheduleResponse,
+ WorkflowScheduleUpsertRequest,
+)
+from skyvern.forge.sdk.services import org_auth_service
+from skyvern.forge.sdk.workflow.models.workflow import Workflow
+from skyvern.forge.sdk.workflow.schedules import (
+ calculate_next_runs,
+ validate_cron_expression,
+ validate_timezone_name,
+)
+
+LOG = structlog.get_logger()
+DEFAULT_NEXT_RUNS_COUNT = 5
+SCHEDULE_SYNC_ERROR_DETAIL = "Failed to sync schedule with scheduling service"
+
+
+def _require_schedules_enabled() -> None:
+ if not app.AGENT_FUNCTION.workflow_schedules_enabled:
+ raise HTTPException(
+ status_code=501,
+ detail=(
+ "Workflow schedules are disabled in this Skyvern build. "
+ "Use Skyvern Cloud or override AgentFunction with a scheduling backend."
+ ),
+ )
+
+
+def _schedule_sync_error() -> HTTPException:
+ return HTTPException(status_code=502, detail=SCHEDULE_SYNC_ERROR_DETAIL)
+
+
+async def _ensure_workflow_exists(workflow_permanent_id: str, organization_id: str) -> Workflow:
+ workflow = await app.DATABASE.workflows.get_workflow_by_permanent_id(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ )
+ if not workflow:
+ raise HTTPException(status_code=404, detail=f"Workflow {workflow_permanent_id} not found")
+ return workflow
+
+
+async def _get_schedule_or_404(
+ workflow_schedule_id: str,
+ organization_id: str,
+) -> WorkflowSchedule:
+ schedule = await app.DATABASE.schedules.get_workflow_schedule_by_id(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization_id,
+ )
+ if not schedule:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+ return schedule
+
+
+def _next_runs(
+ schedule: WorkflowSchedule,
+ count: int = DEFAULT_NEXT_RUNS_COUNT,
+) -> list[datetime]:
+ return calculate_next_runs(schedule.cron_expression, schedule.timezone, count)
+
+
+def _strip_none_parameters(params: dict[str, Any] | None) -> dict[str, Any] | None:
+ """Remove keys whose value is None so they fall through to defaults at execution time."""
+ if params is None:
+ return None
+ stripped = {k: v for k, v in params.items() if v is not None}
+ return stripped or None
+
+
+def _validate_request(cron_expression: str, timezone: str) -> None:
+ try:
+ validate_cron_expression(cron_expression)
+ validate_timezone_name(timezone)
+ except ValueError as e:
+ raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+async def _set_schedule_enabled(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ organization: Organization,
+ enabled: bool,
+) -> WorkflowScheduleResponse:
+ # Guard lives on both enable/disable route signatures via Depends, so no
+ # direct call here — the dependency has already run by the time we arrive.
+ await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ existing = await _get_schedule_or_404(
+ workflow_schedule_id,
+ organization.organization_id,
+ )
+ if existing.workflow_permanent_id != workflow_permanent_id:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+
+ backend_schedule_id = existing.backend_schedule_id or app.AGENT_FUNCTION.build_workflow_schedule_id(
+ existing.workflow_schedule_id
+ )
+ if backend_schedule_id is None and app.AGENT_FUNCTION.workflow_schedules_enabled:
+ # Defensive: schedules are enabled but no backend id is available, so the
+ # DB toggle below would drift from the execution backend. Surface it loudly
+ # — callers (route Depends, batch jobs) should have caught this earlier.
+ LOG.warning(
+ "Toggling workflow schedule enabled state with no backend_schedule_id; DB and backend may drift",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ )
+ previous_enabled = existing.enabled
+
+ schedule = await app.DATABASE.schedules.update_workflow_schedule_enabled(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ enabled=enabled,
+ )
+ if not schedule:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+
+ if backend_schedule_id:
+ try:
+ await app.AGENT_FUNCTION.set_workflow_schedule_enabled(backend_schedule_id, enabled)
+ except Exception as e:
+ LOG.exception(
+ "Failed to update workflow schedule enabled state on execution backend",
+ workflow_schedule_id=workflow_schedule_id,
+ backend_schedule_id=backend_schedule_id,
+ enabled=enabled,
+ error_type=type(e).__name__,
+ )
+ try:
+ await app.DATABASE.schedules.update_workflow_schedule_enabled(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ enabled=previous_enabled,
+ )
+ except Exception as rollback_err:
+ LOG.exception(
+ "CRITICAL: DB rollback failed after backend sync failure, DB and backend may be out of sync",
+ workflow_schedule_id=workflow_schedule_id,
+ backend_schedule_id=backend_schedule_id,
+ rollback_error=str(rollback_err),
+ original_error=str(e),
+ )
+ raise _schedule_sync_error() from e
+
+ LOG.info(
+ "Workflow schedule enabled state updated",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ enabled=enabled,
+ )
+ return WorkflowScheduleResponse(schedule=schedule, next_runs=_next_runs(schedule))
+
+
+# Each route is double-decorated: the legacy `@legacy_base_router.*` decorator is
+# applied first (schema-hidden, mounted at /api/v1/ for backward compatibility),
+# then `@base_router.*` wraps the already-registered function with the public
+# /v1/ schema entry. Keep this order — reversing it would change which decorator
+# sees the raw function if a future contributor adds middleware.
+@legacy_base_router.get("/schedules", include_in_schema=False)
+@base_router.get(
+ "/schedules",
+ response_model=OrganizationScheduleListResponse,
+ tags=["Schedules"],
+ operation_id="schedules_list_all",
+ summary="List all schedules for the organization",
+)
+async def list_organization_schedules(
+ page: int = Query(default=1, ge=1),
+ page_size: int = Query(default=10, ge=1, le=100),
+ status: Literal["active", "paused"] | None = Query(
+ default=None, description="Filter by status: 'active' or 'paused'"
+ ),
+ search: str | None = Query(default=None, description="Search by workflow title or schedule name"),
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> OrganizationScheduleListResponse:
+ enabled_filter: bool | None = None
+ if status == "active":
+ enabled_filter = True
+ elif status == "paused":
+ enabled_filter = False
+
+ schedules, total_count = await app.DATABASE.schedules.list_organization_schedules(
+ organization_id=organization.organization_id,
+ page=page,
+ page_size=page_size,
+ enabled_filter=enabled_filter,
+ search=search,
+ )
+
+ return OrganizationScheduleListResponse(
+ schedules=schedules,
+ total_count=total_count,
+ page=page,
+ page_size=page_size,
+ )
+
+
+@legacy_base_router.post("/workflows/{workflow_permanent_id}/schedules", include_in_schema=False)
+@base_router.post(
+ "/workflows/{workflow_permanent_id}/schedules",
+ response_model=WorkflowScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_create",
+ summary="Create a schedule for a workflow",
+)
+async def create_workflow_schedule(
+ workflow_permanent_id: str,
+ body: WorkflowScheduleUpsertRequest,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleResponse:
+ _validate_request(body.cron_expression, body.timezone)
+ workflow = await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ await app.WORKFLOW_SERVICE.validate_schedule_parameters(
+ workflow=workflow,
+ organization=organization,
+ request_data=body.parameters,
+ )
+ stored_parameters = _strip_none_parameters(body.parameters)
+
+ # Atomic limit check + insert
+ max_schedules = await ScheduleLimitCheckerFactory.get_instance().get_schedule_limit(
+ organization,
+ workflow_permanent_id,
+ )
+
+ try:
+ schedule, count = await app.DATABASE.schedules.create_workflow_schedule_with_limit(
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ max_schedules=max_schedules,
+ cron_expression=body.cron_expression,
+ timezone=body.timezone,
+ enabled=body.enabled,
+ parameters=stored_parameters,
+ name=body.name,
+ description=body.description,
+ )
+ except ScheduleLimitExceededError as e:
+ LOG.info(
+ "Schedule limit exceeded",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ current_count=e.current_count,
+ max_allowed=e.max_allowed,
+ )
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT,
+ detail=f"Maximum of {e.max_allowed} schedules per workflow reached",
+ ) from e
+
+ # Auto-generate name if not provided
+ if not body.name:
+ auto_name = f"{workflow.title} - Schedule #{count + 1}"
+ updated = await app.DATABASE.schedules.update_workflow_schedule(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ cron_expression=body.cron_expression,
+ timezone=body.timezone,
+ enabled=body.enabled,
+ parameters=stored_parameters,
+ name=auto_name,
+ description=body.description,
+ )
+ if updated:
+ schedule = updated
+
+ backend_schedule_id = app.AGENT_FUNCTION.build_workflow_schedule_id(schedule.workflow_schedule_id)
+ # The 501 guard above ensures this route only runs when schedules are enabled,
+ # in which case a conforming AgentFunction override must return a non-None id.
+ if backend_schedule_id is None:
+ LOG.error(
+ "AgentFunction.build_workflow_schedule_id returned None while schedules are enabled",
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ )
+ await app.DATABASE.schedules.delete_workflow_schedule(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+ raise _schedule_sync_error()
+
+ try:
+ result = await app.DATABASE.schedules.set_backend_schedule_id(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ backend_schedule_id=backend_schedule_id,
+ )
+ if not result:
+ await app.DATABASE.schedules.delete_workflow_schedule(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+ raise _schedule_sync_error()
+ schedule = result
+ except HTTPException:
+ raise
+ except Exception as e:
+ LOG.exception(
+ "Failed to persist backend schedule id, cleaning up",
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ )
+ await app.DATABASE.schedules.delete_workflow_schedule(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+ raise _schedule_sync_error() from e
+
+ # Sync to execution backend. On failure, soft-delete the DB record as cleanup.
+ try:
+ await app.AGENT_FUNCTION.upsert_workflow_schedule(
+ backend_schedule_id=backend_schedule_id,
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow.workflow_permanent_id,
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ cron_expression=body.cron_expression,
+ timezone=body.timezone,
+ enabled=body.enabled,
+ parameters=stored_parameters,
+ )
+ except Exception as e:
+ LOG.exception(
+ "Failed to register schedule with execution backend, cleaning up DB record",
+ workflow_permanent_id=workflow_permanent_id,
+ error_type=type(e).__name__,
+ )
+ try:
+ await app.DATABASE.schedules.delete_workflow_schedule(
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+ except Exception as cleanup_err:
+ LOG.exception(
+ "CRITICAL: Failed to clean up DB record after backend sync failure, "
+ "orphaned schedule may block future creates until manually deleted",
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ organization_id=organization.organization_id,
+ cleanup_error=str(cleanup_err),
+ original_error=str(e),
+ )
+ raise _schedule_sync_error() from e
+
+ LOG.info(
+ "Workflow schedule created",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=schedule.workflow_schedule_id,
+ cron_expression=body.cron_expression,
+ enabled=body.enabled,
+ )
+ return WorkflowScheduleResponse(schedule=schedule, next_runs=_next_runs(schedule))
+
+
+@legacy_base_router.get("/workflows/{workflow_permanent_id}/schedules", include_in_schema=False)
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/schedules",
+ response_model=WorkflowScheduleListResponse,
+ tags=["Schedules"],
+ operation_id="schedules_list",
+ summary="List schedules for a workflow",
+)
+async def list_workflow_schedules(
+ workflow_permanent_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleListResponse:
+ await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ schedules = await app.DATABASE.schedules.get_workflow_schedules(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization.organization_id,
+ )
+ return WorkflowScheduleListResponse(schedules=schedules)
+
+
+@legacy_base_router.get("/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}", include_in_schema=False)
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}",
+ response_model=WorkflowScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_get",
+ summary="Get a workflow schedule by id",
+)
+async def get_workflow_schedule(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleResponse:
+ await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ schedule = await _get_schedule_or_404(
+ workflow_schedule_id,
+ organization.organization_id,
+ )
+ if schedule.workflow_permanent_id != workflow_permanent_id:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+ return WorkflowScheduleResponse(schedule=schedule, next_runs=_next_runs(schedule))
+
+
+@legacy_base_router.put("/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}", include_in_schema=False)
+@base_router.put(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}",
+ response_model=WorkflowScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_update",
+ summary="Update a workflow schedule",
+)
+async def update_workflow_schedule(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ body: WorkflowScheduleUpsertRequest,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleResponse:
+ workflow = await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ existing = await _get_schedule_or_404(
+ workflow_schedule_id,
+ organization.organization_id,
+ )
+ if existing.workflow_permanent_id != workflow_permanent_id:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+
+ _validate_request(body.cron_expression, body.timezone)
+ await app.WORKFLOW_SERVICE.validate_schedule_parameters(
+ workflow=workflow,
+ organization=organization,
+ request_data=body.parameters,
+ )
+ stored_parameters = _strip_none_parameters(body.parameters)
+
+ # Prefer the id already persisted on the row; only re-derive when it's missing.
+ # The `or` short-circuits, so a non-empty existing id is never overwritten.
+ backend_schedule_id = existing.backend_schedule_id or app.AGENT_FUNCTION.build_workflow_schedule_id(
+ existing.workflow_schedule_id
+ )
+ if backend_schedule_id is None:
+ # The route-level _require_schedules_enabled dependency guarantees we only
+ # reach this point when schedules are enabled, so a None here means a
+ # misconfigured AgentFunction override (build returned None even though
+ # workflow_schedules_enabled is True). Bail out so the DB doesn't drift.
+ LOG.error(
+ "AgentFunction.build_workflow_schedule_id returned None while schedules are enabled",
+ workflow_schedule_id=workflow_schedule_id,
+ )
+ raise _schedule_sync_error()
+
+ old_cron = existing.cron_expression
+ old_timezone = existing.timezone
+ old_enabled = existing.enabled
+ old_parameters = existing.parameters
+ old_name = existing.name
+ old_description = existing.description
+
+ schedule = await app.DATABASE.schedules.update_workflow_schedule(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ cron_expression=body.cron_expression,
+ timezone=body.timezone,
+ enabled=body.enabled,
+ parameters=stored_parameters,
+ backend_schedule_id=backend_schedule_id,
+ name=body.name,
+ description=body.description,
+ )
+ if not schedule:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+
+ try:
+ await app.AGENT_FUNCTION.upsert_workflow_schedule(
+ backend_schedule_id=backend_schedule_id,
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow.workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ cron_expression=body.cron_expression,
+ timezone=body.timezone,
+ enabled=body.enabled,
+ parameters=stored_parameters,
+ )
+ except Exception as e:
+ LOG.exception(
+ "Failed to update schedule on execution backend",
+ workflow_permanent_id=workflow_permanent_id,
+ backend_schedule_id=backend_schedule_id,
+ error_type=type(e).__name__,
+ )
+ try:
+ await app.DATABASE.schedules.update_workflow_schedule(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ cron_expression=old_cron,
+ timezone=old_timezone,
+ enabled=old_enabled,
+ parameters=old_parameters,
+ backend_schedule_id=backend_schedule_id,
+ name=old_name,
+ description=old_description,
+ )
+ except Exception as rollback_err:
+ LOG.exception(
+ "CRITICAL: DB rollback failed after backend sync failure, DB and backend may be out of sync",
+ workflow_permanent_id=workflow_permanent_id,
+ backend_schedule_id=backend_schedule_id,
+ rollback_error=str(rollback_err),
+ original_error=str(e),
+ )
+ raise _schedule_sync_error() from e
+
+ LOG.info(
+ "Workflow schedule updated",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ cron_expression=body.cron_expression,
+ enabled=body.enabled,
+ )
+ return WorkflowScheduleResponse(schedule=schedule, next_runs=_next_runs(schedule))
+
+
+@legacy_base_router.post(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/enable",
+ include_in_schema=False,
+)
+@base_router.post(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/enable",
+ response_model=WorkflowScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_enable",
+ summary="Enable a workflow schedule",
+)
+async def enable_workflow_schedule(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleResponse:
+ return await _set_schedule_enabled(
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ organization=organization,
+ enabled=True,
+ )
+
+
+@legacy_base_router.post(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/disable",
+ include_in_schema=False,
+)
+@base_router.post(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/disable",
+ response_model=WorkflowScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_disable",
+ summary="Disable a workflow schedule",
+)
+async def disable_workflow_schedule(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> WorkflowScheduleResponse:
+ return await _set_schedule_enabled(
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ organization=organization,
+ enabled=False,
+ )
+
+
+@legacy_base_router.delete(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}", include_in_schema=False
+)
+@base_router.delete(
+ "/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}",
+ response_model=DeleteScheduleResponse,
+ tags=["Schedules"],
+ operation_id="schedules_delete",
+ summary="Delete a workflow schedule",
+)
+async def delete_workflow_schedule_route(
+ workflow_permanent_id: str,
+ workflow_schedule_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+ _: None = Depends(_require_schedules_enabled),
+) -> DeleteScheduleResponse:
+ await _ensure_workflow_exists(workflow_permanent_id, organization.organization_id)
+ existing = await _get_schedule_or_404(
+ workflow_schedule_id,
+ organization.organization_id,
+ )
+ if existing.workflow_permanent_id != workflow_permanent_id:
+ raise HTTPException(
+ status_code=404,
+ detail=f"Schedule {workflow_schedule_id} not found",
+ )
+
+ await app.DATABASE.schedules.delete_workflow_schedule(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+
+ if not existing.backend_schedule_id:
+ LOG.warning(
+ "Deleting workflow schedule with no backend_schedule_id; skipping backend sync",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ )
+ else:
+ try:
+ await app.AGENT_FUNCTION.delete_workflow_schedule(existing.backend_schedule_id)
+ except Exception as e:
+ LOG.exception(
+ "Failed to delete schedule on execution backend, restoring DB record",
+ backend_schedule_id=existing.backend_schedule_id,
+ )
+ try:
+ await app.DATABASE.schedules.restore_workflow_schedule(
+ workflow_schedule_id=workflow_schedule_id,
+ organization_id=organization.organization_id,
+ )
+ except Exception as rollback_err:
+ LOG.exception(
+ "CRITICAL: DB rollback failed after backend sync failure, DB and backend may be out of sync",
+ workflow_schedule_id=workflow_schedule_id,
+ backend_schedule_id=existing.backend_schedule_id,
+ rollback_error=str(rollback_err),
+ original_error=str(e),
+ )
+ raise _schedule_sync_error() from e
+
+ LOG.info(
+ "Workflow schedule deleted",
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_schedule_id=workflow_schedule_id,
+ )
+ return DeleteScheduleResponse(ok=True)
diff --git a/skyvern/forge/sdk/schemas/workflow_schedules.py b/skyvern/forge/sdk/schemas/workflow_schedules.py
index d05ab1f30..dec4f8fb4 100644
--- a/skyvern/forge/sdk/schemas/workflow_schedules.py
+++ b/skyvern/forge/sdk/schemas/workflow_schedules.py
@@ -5,7 +5,14 @@ from pydantic import BaseModel, ConfigDict, Field
class WorkflowSchedule(BaseModel):
- model_config = ConfigDict(from_attributes=True)
+ # populate_by_name + serialize_by_alias keep the wire format stable at
+ # `temporal_schedule_id` (the already-deployed name external clients see)
+ # while the Python attribute stays backend-agnostic.
+ model_config = ConfigDict(
+ from_attributes=True,
+ populate_by_name=True,
+ serialize_by_alias=True,
+ )
workflow_schedule_id: str
organization_id: str
@@ -14,7 +21,7 @@ class WorkflowSchedule(BaseModel):
timezone: str
enabled: bool
parameters: dict[str, Any] | None = None
- temporal_schedule_id: str | None = None
+ backend_schedule_id: str | None = Field(default=None, alias="temporal_schedule_id")
name: str | None = None
description: str | None = None
created_at: datetime
@@ -23,6 +30,14 @@ class WorkflowSchedule(BaseModel):
class OrganizationScheduleItem(BaseModel):
+ """Compact schedule projection for the org-wide list endpoint.
+
+ Intentionally omits `backend_schedule_id` — the list view is for browsing
+ schedules in the dashboard, not for managing the underlying execution-backend
+ binding. Callers that need the backend id should fetch the individual
+ schedule via the per-workflow get endpoint.
+ """
+
workflow_schedule_id: str
organization_id: str
workflow_permanent_id: str
@@ -70,3 +85,16 @@ class OrganizationScheduleListResponse(BaseModel):
total_count: int
page: int
page_size: int
+
+
+class DeleteScheduleResponse(BaseModel):
+ ok: bool
+
+
+class WorkflowScheduleUpsertRequest(BaseModel):
+ cron_expression: str
+ timezone: str
+ enabled: bool = True
+ parameters: dict[str, Any] | None = None
+ name: str | None = None
+ description: str | None = None
diff --git a/tests/unit/forge/sdk/test_workflow_schedules_routes.py b/tests/unit/forge/sdk/test_workflow_schedules_routes.py
new file mode 100644
index 000000000..a0c5fa669
--- /dev/null
+++ b/tests/unit/forge/sdk/test_workflow_schedules_routes.py
@@ -0,0 +1,95 @@
+"""OSS-side tests for the workflow schedules route module.
+
+The OSS Skyvern build ships these routes wired into the OpenAPI spec so the
+auto-generated SDKs include the schedules namespace, but the underlying
+execution backend is not implemented in OSS. The route handlers must therefore
+return HTTP 501 unless the AgentFunction override flips
+``workflow_schedules_enabled`` on (which Skyvern Cloud does).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from fastapi import HTTPException
+
+import skyvern.forge.sdk.routes.workflow_schedules as workflow_schedule_routes
+from skyvern.forge.agent_functions import AgentFunction
+
+
[email protected](autouse=True)
+def _install_oss_agent_function(monkeypatch: pytest.MonkeyPatch) -> AgentFunction:
+ agent = AgentFunction()
+ monkeypatch.setattr(workflow_schedule_routes.app, "AGENT_FUNCTION", agent)
+ return agent
+
+
+def _organization() -> SimpleNamespace:
+ return SimpleNamespace(organization_id="org_oss")
+
+
+def test_oss_agent_function_disables_workflow_schedules() -> None:
+ assert AgentFunction().workflow_schedules_enabled is False
+
+
+def test_require_schedules_enabled_raises_501_in_oss() -> None:
+ with pytest.raises(HTTPException) as exc_info:
+ workflow_schedule_routes._require_schedules_enabled()
+ assert exc_info.value.status_code == 501
+ assert "disabled" in exc_info.value.detail.lower()
+
+
+def test_oss_build_workflow_schedule_id_returns_none() -> None:
+ assert AgentFunction().build_workflow_schedule_id("ws_123") is None
+
+
+async def test_oss_upsert_workflow_schedule_is_noop() -> None:
+ result = await AgentFunction().upsert_workflow_schedule(
+ backend_schedule_id="ws_123",
+ organization_id="org_oss",
+ workflow_permanent_id="wpid_123",
+ workflow_schedule_id="ws_123",
+ cron_expression="0 */6 * * *",
+ timezone="UTC",
+ enabled=True,
+ parameters=None,
+ )
+ assert result is None
+
+
+async def test_oss_set_workflow_schedule_enabled_is_noop() -> None:
+ assert await AgentFunction().set_workflow_schedule_enabled("ws_123", enabled=False) is None
+
+
+async def test_oss_delete_workflow_schedule_is_noop() -> None:
+ assert await AgentFunction().delete_workflow_schedule("ws_123") is None
+
+
+ "prefix,router_name",
+ [("/v1", "base_router"), ("/api/v1", "legacy_base_router")],
+)
+def test_oss_route_returns_501_via_testclient(prefix: str, router_name: str) -> None:
+ """End-to-end: route resolves through the FastAPI dependency chain and returns 501
+ on both the public `/v1` mount and the legacy `/api/v1` alias."""
+ from fastapi import FastAPI
+ from fastapi.testclient import TestClient
+
+ from skyvern.forge.sdk.routes import routers as routers_module
+ from skyvern.forge.sdk.services import org_auth_service
+
+ async def _fake_org() -> SimpleNamespace:
+ return SimpleNamespace(organization_id="org_oss")
+
+ fastapi_app = FastAPI()
+ fastapi_app.dependency_overrides[org_auth_service.get_current_org] = _fake_org
+ fastapi_app.include_router(getattr(routers_module, router_name), prefix=prefix)
+
+ client = TestClient(fastapi_app)
+ response = client.get(f"{prefix}/schedules")
+ assert response.status_code == 501
+ assert "disabled" in response.json()["detail"].lower()