feat: add Actor task publication endpoints (#985)

- Add publish() / unpublish() methods to TaskClient and TaskClientAsync — convenience wrappers over update() that toggle the task's publication on its public landing page.
- Add is_public and public_config_* arguments (SEO title/description, input schema fields, dataset name/view) to TaskClient.update() and TaskCollectionClient.create(), sync and async.
- Regenerate models from the updated OpenAPI spec (apify-docs #2840): new TaskPublicConfig model, plus is_public and public_config fields on Task, CreateTaskRequest, and UpdateTaskRequest.
- Add unit tests for task publication (tests/unit/test_task_publication.py) and move the shared sync_client / async_client fixtures into tests/unit/conftest.py.

---------

Co-authored-by: Jan (Honza) Jiráň <jan.jiran@apify.com>

Author: apify-service-account

src/apify_client/_models.py

@@ -883,6 +883,13 @@ class CreateTaskRequest(BaseModel):
     input: TaskInput | None = None
     title: str | None = None
     actor_standby: ActorStandby | None = None
+    public_config: TaskPublicConfig | None = None
+    """
+    Public-facing display configuration of the task's public landing page. The task is not
+    published by setting it — set `isPublic` via the [Update task](https://docs.apify.com/api/v2/actor-task-put)
+    endpoint for that. Setting `publicConfig` requires write permission to the task's Actor.
+
+    """
 
 
 @docs_group('Models')
@@ -3496,6 +3503,14 @@ class Task(BaseModel):
     title: str | None = None
     actor_standby: ActorStandby | None = None
     standby_url: AnyUrl | None = None
+    is_public: Annotated[bool | None, Field(examples=[False])] = None
+    """
+    Whether the task is published on its public landing page. Derived from
+    `publicConfig.publishedAt`. Set it via the [Update task](https://docs.apify.com/api/v2/actor-task-put)
+    endpoint to publish or unpublish the task.
+
+    """
+    public_config: TaskPublicConfig | None = None
 
 
 @docs_group('Models')
@@ -3527,6 +3542,52 @@ class TaskOptions(BaseModel):
     restart_on_error: Annotated[bool | None, Field(examples=[False])] = None
 
 
+@docs_group('Models')
+class TaskPublicConfig(BaseModel):
+    """Public-facing configuration of a published task, used by the task's public landing page.
+    The task's publication state is determined by `publishedAt` - a task is published when
+    `publishedAt` is set and unpublished when it is `null`.
+
+    """
+
+    model_config = ConfigDict(
+        extra='allow',
+        populate_by_name=True,
+        alias_generator=to_camel,
+    )
+    published_at: Annotated[AwareDatetime | None, Field(examples=['2025-06-16T09:20:45.777Z'])] = None
+    """
+    Time when the task was published, or `null` if the task is not published.
+    This field is server-controlled - to publish or unpublish a task, set `isPublic`
+    via the [Update task](https://docs.apify.com/api/v2/actor-task-put) endpoint.
+
+    """
+    seo_title: Annotated[str | None, Field(examples=['Scrape data from a website'])] = None
+    """
+    SEO title of the public task page. Defaults to the task title when not set.
+    """
+    seo_description: str | None = None
+    """
+    SEO description of the public task page. Defaults to the task description when not set.
+    """
+    categorization: str | None = None
+    """
+    Use-case category of the public task.
+    """
+    input_schema_fields: list[str] | None = None
+    """
+    Names of the task input fields displayed on the public task page.
+    """
+    dataset_name: str | None = None
+    """
+    Name of the dataset from the Actor's dataset schema whose results are displayed.
+    """
+    dataset_view: str | None = None
+    """
+    Key of the dataset view from the Actor's dataset schema used to display results.
+    """
+
+
 @docs_group('Models')
 class TaskResponse(BaseModel):
     """Response containing Actor task data."""
@@ -3802,6 +3863,22 @@ class UpdateTaskRequest(BaseModel):
     input: TaskInput | None = None
     title: str | None = None
     actor_standby: ActorStandby | None = None
+    public_config: TaskPublicConfig | None = None
+    """
+    Public-facing display configuration of the task's public landing page. The provided
+    fields are merged into the stored configuration and validated. The stored configuration
+    cannot be cleared this way. Set `isPublic` to change the publication state.
+    Updating `publicConfig` requires write permission to the task's Actor.
+
+    """
+    is_public: Annotated[bool | None, Field(examples=[True])] = None
+    """
+    Set to `true` to publish the task on its public landing page, or `false` to unpublish it.
+    Sending the value the task already has does nothing. Publishing requires the task's
+    `publicConfig` to be filled in and write permission to the task's Actor; it fails if the
+    task is not ready to be published, leaving the rest of the update unapplied.
+
+    """
 
 
 @docs_group('Models')

src/apify_client/_resource_clients/task.py

@@ -10,6 +10,7 @@
     Task,
     TaskInput,
     TaskOptions,
+    TaskPublicConfig,
     TaskResponse,
     UpdateTaskRequest,
 )
@@ -83,6 +84,12 @@ def update(
         actor_standby_idle_timeout: timedelta | None = None,
         actor_standby_build: str | None = None,
         actor_standby_memory_mbytes: int | None = None,
+        is_public: bool | None = None,
+        public_config_seo_title: str | None = None,
+        public_config_seo_description: str | None = None,
+        public_config_input_schema_fields: list[str] | None = None,
+        public_config_dataset_name: str | None = None,
+        public_config_dataset_view: str | None = None,
         timeout: Timeout = 'short',
     ) -> Task:
         """Update the task with specified fields.
@@ -111,6 +118,16 @@ def update(
                 it will be shut down.
             actor_standby_build: The build tag or number to run when the Actor is in Standby mode.
             actor_standby_memory_mbytes: The memory in megabytes to use when the Actor is in Standby mode.
+            is_public: Set to `True` to publish the task on its public landing page, or `False` to unpublish it.
+                Passing the value the task already has does nothing. Publishing requires the public display
+                configuration to be filled in, and write access to the task's Actor.
+            public_config_seo_title: SEO title of the public task page. Defaults to the task title when not set.
+            public_config_seo_description: SEO description of the public task page. Defaults to the task description
+                when not set.
+            public_config_input_schema_fields: Names of the task input fields displayed on the public task page.
+            public_config_dataset_name: Name of the dataset from the Actor's dataset schema whose results are
+                displayed on the public task page.
+            public_config_dataset_view: View key from the Actor's dataset schema shown on the public task page.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -123,6 +140,14 @@ def update(
             name=name,
             title=title,
             input=task_input,
+            is_public=is_public,
+            public_config=TaskPublicConfig(
+                seo_title=public_config_seo_title,
+                seo_description=public_config_seo_description,
+                input_schema_fields=public_config_input_schema_fields,
+                dataset_name=public_config_dataset_name,
+                dataset_view=public_config_dataset_view,
+            ),
             options=TaskOptions(
                 build=build,
                 max_items=max_items,
@@ -141,6 +166,40 @@ def update(
         result = self._update(timeout=timeout, **task_fields.model_dump(by_alias=True, exclude_none=True))
         return TaskResponse.model_validate(result).data
 
+    def publish(self, *, timeout: Timeout = 'short') -> Task:
+        """Publish the task on its public landing page.
+
+        Convenience wrapper over `update` with `is_public` set to `True`. The task's Actor must be public and
+        the task must have its public display configuration set up. Requires write access to the task and to its
+        Actor. Publishing an already published task does nothing.
+
+        https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/update-task
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The published task.
+        """
+        return self.update(is_public=True, timeout=timeout)
+
+    def unpublish(self, *, timeout: Timeout = 'short') -> Task:
+        """Unpublish the task from its public landing page.
+
+        Convenience wrapper over `update` with `is_public` set to `False`. The public display configuration is
+        preserved, so the task can be published again without re-entering it. Requires write access to the task
+        and to its Actor. Unpublishing a task that is not published does nothing.
+
+        https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/update-task
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The unpublished task.
+        """
+        return self.update(is_public=False, timeout=timeout)
+
     def delete(self, *, timeout: Timeout = 'short') -> None:
         """Delete the task.
 
@@ -406,6 +465,12 @@ async def update(
         actor_standby_idle_timeout: timedelta | None = None,
         actor_standby_build: str | None = None,
         actor_standby_memory_mbytes: int | None = None,
+        is_public: bool | None = None,
+        public_config_seo_title: str | None = None,
+        public_config_seo_description: str | None = None,
+        public_config_input_schema_fields: list[str] | None = None,
+        public_config_dataset_name: str | None = None,
+        public_config_dataset_view: str | None = None,
         timeout: Timeout = 'short',
     ) -> Task:
         """Update the task with specified fields.
@@ -434,6 +499,16 @@ async def update(
                 it will be shut down.
             actor_standby_build: The build tag or number to run when the Actor is in Standby mode.
             actor_standby_memory_mbytes: The memory in megabytes to use when the Actor is in Standby mode.
+            is_public: Set to `True` to publish the task on its public landing page, or `False` to unpublish it.
+                Passing the value the task already has does nothing. Publishing requires the public display
+                configuration to be filled in, and write access to the task's Actor.
+            public_config_seo_title: SEO title of the public task page. Defaults to the task title when not set.
+            public_config_seo_description: SEO description of the public task page. Defaults to the task description
+                when not set.
+            public_config_input_schema_fields: Names of the task input fields displayed on the public task page.
+            public_config_dataset_name: Name of the dataset from the Actor's dataset schema whose results are
+                displayed on the public task page.
+            public_config_dataset_view: View key from the Actor's dataset schema shown on the public task page.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -446,6 +521,14 @@ async def update(
             name=name,
             title=title,
             input=task_input,
+            is_public=is_public,
+            public_config=TaskPublicConfig(
+                seo_title=public_config_seo_title,
+                seo_description=public_config_seo_description,
+                input_schema_fields=public_config_input_schema_fields,
+                dataset_name=public_config_dataset_name,
+                dataset_view=public_config_dataset_view,
+            ),
             options=TaskOptions(
                 build=build,
                 max_items=max_items,
@@ -464,6 +547,40 @@ async def update(
         result = await self._update(timeout=timeout, **task_fields.model_dump(by_alias=True, exclude_none=True))
         return TaskResponse.model_validate(result).data
 
+    async def publish(self, *, timeout: Timeout = 'short') -> Task:
+        """Publish the task on its public landing page.
+
+        Convenience wrapper over `update` with `is_public` set to `True`. The task's Actor must be public and
+        the task must have its public display configuration set up. Requires write access to the task and to its
+        Actor. Publishing an already published task does nothing.
+
+        https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/update-task
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The published task.
+        """
+        return await self.update(is_public=True, timeout=timeout)
+
+    async def unpublish(self, *, timeout: Timeout = 'short') -> Task:
+        """Unpublish the task from its public landing page.
+
+        Convenience wrapper over `update` with `is_public` set to `False`. The public display configuration is
+        preserved, so the task can be published again without re-entering it. Requires write access to the task
+        and to its Actor. Unpublishing a task that is not published does nothing.
+
+        https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/update-task
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The unpublished task.
+        """
+        return await self.update(is_public=False, timeout=timeout)
+
     async def delete(self, *, timeout: Timeout = 'short') -> None:
         """Delete the task.
 

src/apify_client/_resource_clients/task_collection.py

@@ -11,6 +11,7 @@
     Task,
     TaskInput,
     TaskOptions,
+    TaskPublicConfig,
     TaskResponse,
 )
 from apify_client._pagination import get_items_iterator, get_items_iterator_async
@@ -116,10 +117,18 @@ def create(
         actor_standby_idle_timeout: timedelta | None = None,
         actor_standby_build: str | None = None,
         actor_standby_memory_mbytes: int | None = None,
+        public_config_seo_title: str | None = None,
+        public_config_seo_description: str | None = None,
+        public_config_input_schema_fields: list[str] | None = None,  # ty: ignore[invalid-type-form]
+        public_config_dataset_name: str | None = None,
+        public_config_dataset_view: str | None = None,
         timeout: Timeout = 'medium',
     ) -> Task:
         """Create a new task.
 
+        The `public_config_*` arguments set the public display configuration of the task's landing page, which
+        requires write access to the task's Actor and the task itself. Use `TaskClient.publish` for publishing.
+
         https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/create-task
 
         Args:
@@ -145,6 +154,13 @@ def create(
                 it will be shut down.
             actor_standby_build: The build tag or number to run when the Actor is in Standby mode.
             actor_standby_memory_mbytes: The memory in megabytes to use when the Actor is in Standby mode.
+            public_config_seo_title: SEO title of the public task page. Defaults to the task title when not set.
+            public_config_seo_description: SEO description of the public task page. Defaults to the task description
+                when not set.
+            public_config_input_schema_fields: Names of the task input fields displayed on the public task page.
+            public_config_dataset_name: Name of the dataset from the Actor's dataset schema whose results are
+                displayed on the public task page.
+            public_config_dataset_view: View key from the Actor's dataset schema shown on the public task page.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -158,6 +174,13 @@ def create(
             name=name,
             title=title,
             input=task_input,
+            public_config=TaskPublicConfig(
+                seo_title=public_config_seo_title,
+                seo_description=public_config_seo_description,
+                input_schema_fields=public_config_input_schema_fields,
+                dataset_name=public_config_dataset_name,
+                dataset_view=public_config_dataset_view,
+            ),
             options=TaskOptions(
                 build=build,
                 max_items=max_items,
@@ -267,10 +290,18 @@ async def create(
         actor_standby_idle_timeout: timedelta | None = None,
         actor_standby_build: str | None = None,
         actor_standby_memory_mbytes: int | None = None,
+        public_config_seo_title: str | None = None,
+        public_config_seo_description: str | None = None,
+        public_config_input_schema_fields: list[str] | None = None,  # ty: ignore[invalid-type-form]
+        public_config_dataset_name: str | None = None,
+        public_config_dataset_view: str | None = None,
         timeout: Timeout = 'medium',
     ) -> Task:
         """Create a new task.
 
+        The `public_config_*` arguments set the public display configuration of the task's landing page, which
+        requires write access to the task's Actor and the task itself. Use `TaskClientAsync.publish` for publishing.
+
         https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/create-task
 
         Args:
@@ -296,6 +327,13 @@ async def create(
                 it will be shut down.
             actor_standby_build: The build tag or number to run when the Actor is in Standby mode.
             actor_standby_memory_mbytes: The memory in megabytes to use when the Actor is in Standby mode.
+            public_config_seo_title: SEO title of the public task page. Defaults to the task title when not set.
+            public_config_seo_description: SEO description of the public task page. Defaults to the task description
+                when not set.
+            public_config_input_schema_fields: Names of the task input fields displayed on the public task page.
+            public_config_dataset_name: Name of the dataset from the Actor's dataset schema whose results are
+                displayed on the public task page.
+            public_config_dataset_view: View key from the Actor's dataset schema shown on the public task page.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -309,6 +347,13 @@ async def create(
             name=name,
             title=title,
             input=task_input,
+            public_config=TaskPublicConfig(
+                seo_title=public_config_seo_title,
+                seo_description=public_config_seo_description,
+                input_schema_fields=public_config_input_schema_fields,
+                dataset_name=public_config_dataset_name,
+                dataset_view=public_config_dataset_view,
+            ),
             options=TaskOptions(
                 build=build,
                 max_items=max_items,