Issue: SDK Discrepancy in Scheduled Workflow API — Missing actor and Inconsistent repeats Handling in Python

[nsgoneape]

---

🐞 Issue: SDK Discrepancy in Scheduled Workflow API — Missing actor and Inconsistent repeats Handling in Python

Overview

There are two key inconsistencies between the Python and JavaScript (Node.js) SDKs for the createSchedules workflow API in Knock:

---

❗ Discrepancy 1: actor Not Supported in Python SDK

• Node.js SDK explicitly allows passing an actor:

  await knock.workflows.createSchedules(workflowKey, {
    recipients,
    scheduled_at,
    data,
    actor  // ✅ Supported
  });
  

• Python SDK neither accepts actor as a parameter nor includes it in the request payload:

  async def create(...):
      ...
      return await self._post("/v1/schedules", body={...})  # actor missing
  

• This is a functional gap. The Python SDK claims in its docstring to support inline identification for actor, recipient, and tenant, yet only recipient and tenant are actually handled.

🔧 Recommendation:

• Add an actor parameter to the Python SDK’s create() method.

• Ensure it is included in the request payload and transformed appropriately.

---

❗ Discrepancy 2: repeats is Required in Python but Optional in Node.js

• Node.js SDK allows simple one-time schedules without specifying repeats:

  await knock.workflows.createSchedules(workflowKey, {
    recipients,
    scheduled_at,
    data,
    actor
  });
  

• Python SDK enforces repeats as a mandatory argument:

  async def create(
      *,
      recipients: List[RecipientRequestParam],
      repeats: Iterable[ScheduleRepeatRuleParam],  # ⛔ Required
      ...
  )
  

• This makes one-time scheduling more complex than necessary in Python, unlike the intuitive experience in JavaScript.

🔧 Recommendation:

• Make repeats optional in the Python SDK.

• Default to one-time scheduling when scheduled_at is provided but repeats is not.

---

🚨 Why This Matters

• These inconsistencies lead to a fragmented developer experience across platforms.

• Python developers currently face extra friction and functional limitations, even for common use cases like one-time workflows with an actor.

• This violates the principle of SDK parity and can cause confusion, bugs, or incorrect implementation.

---

✅ Proposed Fix Summary

Feature	Node.js SDK	Python SDK	Action Needed
actor	✅ Supported	❌ Missing	Add actor param + body support
repeats	✅ Optional	❌ Required	Make optional + default to one-time

---

[linear]

KNO-8750 Schedule Endpoint Should Accept Actor Request.

[nsgoneape]

@cjbell

Hi Chris,

I'm writing to report two bugs in the Python SDK (knockapi), both confirmed in the latest release (v1.3.0):

1. actor is still not accepted by schedules.create()
   Even though the Knock API accepts actor in POST /v1/schedules, the Python SDK throws:

TypeError: AsyncSchedulesResource.create() got an unexpected keyword argument 'actor'
This prevents setting the actor inline when creating a schedule, unlike the Node SDK or raw API. It forces a two-step workaround (create → update) just to get attribution right — which breaks expected behavior, especially for personalized workflows like reminders or nudges.

2. repeats is still required in create() — even for one-time schedules
   The SDK forces a non-empty repeats param even when just using scheduled_at. This contradicts your own API docs, where repeats is clearly optional:

“Use scheduled_at for one-time schedules and repeats for recurring ones.”

This means even simple one-off jobs (like a single reminder) require us to pass repeats=[] just to satisfy the client.

Why this matters
This breaks parity with your Node SDK, violates your own documented API spec, and adds avoidable complexity in environments where schedule creation is part of an automation pipeline.

Suggested Fix
Both of these should be straightforward fixes in your OpenAPI generator or model definitions:

Include actor in ScheduleCreateParams

Mark repeats as optional (or default to [])

If you want help validating or patching this, I’m happy to assist — just point me at the relevant model or schema.

Thanks,
Neil
CEO, THEBLOCK

[nsgoneape]

This is how I am temporarily circumavigating the problem.

    def __init__(self):
        """Initialize the Knock client."""
        # Get Knock API key from server config
        self.knock_api_key = server_config.KNOCK_API_KEY
        if not self.knock_api_key:
            logger.warning("KNOCK_API_KEY not found in server config")
        
        # Initialize async Knock client
        self.knock_client = AsyncKnock(api_key=self.knock_api_key) if self.knock_api_key else None

        # ----------------------------------------------------------------
        # Monkey-patch schedules.create so it supports `actor`
        #   and makes `repeats` optional (works in Docker, no local edits
        #   to site-packages required).
        # ----------------------------------------------------------------
        if self.knock_client:
            async def _patched_create(
                self,
                *,
                recipients: List[str],
                workflow: str,
                scheduled_at: datetime,
                data: Optional[Dict[str, object]] = None,
                actor: Optional[str] = None,
                repeats: Optional[list] = None,
                ending_at: Optional[datetime] = None,
                tenant: Optional[str] = None,
                extra_headers: Headers | None = None,
                extra_query: Query | None = None,
                extra_body: Body | None = None,
                timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
                **kwargs,
            ) -> ScheduleCreateResponse:
                body = {
                    "recipients": recipients,
                    "workflow": workflow,
                    "scheduled_at": scheduled_at,
                    "data": data,
                    "actor": actor,
                    "repeats": repeats if repeats is not None else NOT_GIVEN,
                    "ending_at": ending_at,
                    "tenant": tenant,
                }
                return await self._post(                       # ✅ use the resource helper
                    "/v1/schedules",
                    body=await async_maybe_transform(body, schedule_create_params.ScheduleCreateParams),
                    options=make_request_options(
                        extra_headers=extra_headers,
                        extra_query=extra_query,
                        extra_body=extra_body,
                        timeout=timeout,
                    ),
                    cast_to=ScheduleCreateResponse,
                )

            
            # Attach the patched method to the schedules resource
            self.knock_client.schedules.create = types.MethodType(
                _patched_create, self.knock_client.schedules
            )
        # ----------------------------------------------------------------

[meryldakin]

@nsgoneape thanks for the bug report and sorry for the trouble here, we're patching this up now.