From cbd3d593f205f0e54e74d2660be7d336a8564222 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Sun, 2 Aug 2026 22:40:43 +0200
Subject: [PATCH 1/7] feat: add Actor task publication endpoints

---
 .../components/schemas/actor-tasks/Task.yaml  |  4 ++
 .../schemas/actor-tasks/TaskPublicConfig.yaml | 38 +++++++++++++++
 .../actor-tasks/UpdateTaskRequest.yaml        | 11 +++++
 apify-api/openapi/openapi.yaml                |  4 ++
 .../actor-tasks@{actorTaskId}.yaml            |  5 ++
 .../actor-tasks@{actorTaskId}@publish.yaml    | 48 +++++++++++++++++++
 .../actor-tasks@{actorTaskId}@unpublish.yaml  | 41 ++++++++++++++++
 7 files changed, 151 insertions(+)
 create mode 100644 apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
 create mode 100644 apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
 create mode 100644 apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml

diff --git a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
index eff273d7e9..9ad7f23fa3 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
@@ -55,3 +55,7 @@ properties:
   standbyUrl:
     type: [string, "null"]
     format: uri
+  publicConfig:
+    anyOf:
+      - $ref: ./TaskPublicConfig.yaml
+      - type: "null"
diff --git a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
new file mode 100644
index 0000000000..3502e5fd64
--- /dev/null
+++ b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
@@ -0,0 +1,38 @@
+title: TaskPublicConfig
+type: object
+description: |
+  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`.
+properties:
+  publishedAt:
+    type: [string, "null"]
+    format: date-time
+    readOnly: true
+    description: |
+      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, use the
+      [Publish task](/api/v2/actor-task-publish-post) and
+      [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints.
+    examples: ["2025-06-16T09:20:45.777Z"]
+  seoTitle:
+    type: [string, "null"]
+    description: SEO title of the public task page. Defaults to the task title when not set.
+    examples: [Scrape data from a website]
+  seoDescription:
+    type: [string, "null"]
+    description: SEO description of the public task page. Defaults to the task description when not set.
+  categorization:
+    type: [string, "null"]
+    description: Use-case category of the public task.
+  inputSchemaFields:
+    type: [array, "null"]
+    description: Names of the task input fields displayed on the public task page.
+    items:
+      type: string
+  datasetName:
+    type: [string, "null"]
+    description: Name of the dataset from the Actor's dataset schema whose results are displayed.
+  datasetView:
+    type: [string, "null"]
+    description: Key of the dataset view from the Actor's dataset schema used to display results.
diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index d12c85c191..ea468c1787 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -18,3 +18,14 @@ properties:
     anyOf:
       - $ref: ../actors/ActorStandby.yaml
       - type: "null"
+  publicConfig:
+    anyOf:
+      - $ref: ./TaskPublicConfig.yaml
+      - type: "null"
+    description: |
+      Public-facing display configuration of the task's public landing page. The provided
+      fields are merged into the stored configuration and validated.
+      [Publish task](/api/v2/actor-task-publish-post) and
+      [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints to change the
+      publication state. Updating `publicConfig` requires write permission to the task's
+      Actor.
diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml
index 149e19e4fc..577151a8f6 100644
--- a/apify-api/openapi/openapi.yaml
+++ b/apify-api/openapi/openapi.yaml
@@ -592,6 +592,10 @@ paths:
     $ref: paths/actor-tasks/actor-tasks.yaml
   "/v2/actor-tasks/{actorTaskId}":
     $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}.yaml"
+  "/v2/actor-tasks/{actorTaskId}/publish":
+    $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml"
+  "/v2/actor-tasks/{actorTaskId}/unpublish":
+    $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml"
   "/v2/actor-tasks/{actorTaskId}/input":
     $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@input.yaml"
   "/v2/actor-tasks/{actorTaskId}/webhooks":
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
index 4b2d8acde8..063be65978 100644
--- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
+++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
@@ -52,6 +52,11 @@ put:
 
     If the object does not define a specific property, its value is not updated.
 
+    The `publicConfig` field carries the display configuration of the task's public
+    landing page. To publish or unpublish the task itself, use the
+    [Publish task](/api/v2/actor-task-publish-post) and
+    [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints.
+
     The response is the full task object as returned by the
     [Get task](/api/v2/actor-task-get) endpoint.
 
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
new file mode 100644
index 0000000000..eb2e015787
--- /dev/null
+++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
@@ -0,0 +1,48 @@
+post:
+  tags:
+    - Actor tasks
+  summary: Publish task
+  description: |
+    Publish the task on its public landing page. The task's public display configuration
+    is set beforehand via the `publicConfig` field of the
+    [Update task](/api/v2/actor-task-put) endpoint. This endpoint validates it and
+    publishes the task.
+
+    Publishing requires the task's Actor to be public, and the task must pass the
+    publication validation.
+    The publication state is stored in `publicConfig.publishedAt` (`null` means the task
+    is not published).
+
+    The endpoint requires write permission to the task's Actor.
+
+    The response is the full task object as returned by the
+    [Get task](/api/v2/actor-task-get) endpoint.
+  operationId: actorTask_publish_post
+  parameters:
+    - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorTaskId"
+  responses:
+    "200":
+      description: ""
+      headers: {}
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../components/schemas/actor-tasks/Task.yaml
+    "400":
+      $ref: ../../components/responses/BadRequest.yaml
+    "401":
+      $ref: ../../components/responses/Unauthorized.yaml
+    "403":
+      $ref: ../../components/responses/Forbidden.yaml
+    "404":
+      $ref: ../../components/responses/NotFound.yaml
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
+  deprecated: false
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml
new file mode 100644
index 0000000000..67a3a90f3d
--- /dev/null
+++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml
@@ -0,0 +1,41 @@
+post:
+  tags:
+    - Actor tasks
+  summary: Unpublish task
+  description: |
+    Unpublish the task from its public landing page. The public display configuration
+    (`publicConfig`) is preserved, so the task can be re-published without re-entering it.
+
+    The endpoint requires write permission to the task's Actor.
+
+    The response is the full task object as returned by the
+    [Get task](/api/v2/actor-task-get) endpoint.
+  operationId: actorTask_unpublish_post
+  parameters:
+    - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorTaskId"
+  responses:
+    "200":
+      description: ""
+      headers: {}
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../components/schemas/actor-tasks/Task.yaml
+    "400":
+      $ref: ../../components/responses/BadRequest.yaml
+    "401":
+      $ref: ../../components/responses/Unauthorized.yaml
+    "403":
+      $ref: ../../components/responses/Forbidden.yaml
+    "404":
+      $ref: ../../components/responses/NotFound.yaml
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
+  deprecated: false

From f0609b96ce84e8b7481aa980ab1204db9416ed29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Tue, 4 Aug 2026 17:27:30 +0200
Subject: [PATCH 2/7] feat: allow publicConfig on task create, tighten it on
 update

Task create now documents `publicConfig` (the API accepts the display fields and
ignores the server-controlled `publishedAt`/`renderableAt`), and the update
schema no longer offers a null the API rejects.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../components/schemas/actor-tasks/CreateTaskRequest.yaml  | 6 ++++++
 .../components/schemas/actor-tasks/UpdateTaskRequest.yaml  | 7 +++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
index 0d985ef897..8a4756b416 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
@@ -23,3 +23,9 @@ properties:
     anyOf:
       - $ref: ../actors/ActorStandby.yaml
       - type: "null"
+  publicConfig:
+    description: |
+      Public-facing display configuration of the task's public landing page. The task is not
+      published by setting it — use the [Publish task](/api/v2/actor-task-publish-post)
+      endpoint for that. Setting `publicConfig` requires write permission to the task's Actor.
+    $ref: ./TaskPublicConfig.yaml
diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index ea468c1787..b86fd48e15 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -19,13 +19,12 @@ properties:
       - $ref: ../actors/ActorStandby.yaml
       - type: "null"
   publicConfig:
-    anyOf:
-      - $ref: ./TaskPublicConfig.yaml
-      - type: "null"
     description: |
       Public-facing display configuration of the task's public landing page. The provided
-      fields are merged into the stored configuration and validated.
+      fields are merged into the stored configuration and validated. The stored configuration
+      cannot be cleared this way. Use the
       [Publish task](/api/v2/actor-task-publish-post) and
       [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints to change the
       publication state. Updating `publicConfig` requires write permission to the task's
       Actor.
+    $ref: ./TaskPublicConfig.yaml

From 41a4dbebb66d698d4ba19baf975f43f52a9f6068 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Thu, 6 Aug 2026 11:29:30 +0200
Subject: [PATCH 3/7] feat: publish tasks via isPublic on the task update

Replaces the dedicated publish/unpublish endpoints with a virtual `isPublic`
field on the task update, matching how Actors are published. `isPublic` is also
returned on the task, derived from `publicConfig.publishedAt`.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../actor-tasks/CreateTaskRequest.yaml        |  2 +-
 .../components/schemas/actor-tasks/Task.yaml  |  7 +++
 .../schemas/actor-tasks/TaskPublicConfig.yaml |  5 +-
 .../actor-tasks/UpdateTaskRequest.yaml        | 15 ++++--
 apify-api/openapi/openapi.yaml                |  4 --
 .../actor-tasks@{actorTaskId}.yaml            |  5 +-
 .../actor-tasks@{actorTaskId}@publish.yaml    | 48 -------------------
 .../actor-tasks@{actorTaskId}@unpublish.yaml  | 41 ----------------
 8 files changed, 22 insertions(+), 105 deletions(-)
 delete mode 100644 apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
 delete mode 100644 apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml

diff --git a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
index 8a4756b416..aae35f94a9 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
@@ -26,6 +26,6 @@ properties:
   publicConfig:
     description: |
       Public-facing display configuration of the task's public landing page. The task is not
-      published by setting it — use the [Publish task](/api/v2/actor-task-publish-post)
+      published by setting it — set `isPublic` via the [Update task](/api/v2/actor-task-put)
       endpoint for that. Setting `publicConfig` requires write permission to the task's Actor.
     $ref: ./TaskPublicConfig.yaml
diff --git a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
index 9ad7f23fa3..64802ab63d 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
@@ -55,6 +55,13 @@ properties:
   standbyUrl:
     type: [string, "null"]
     format: uri
+  isPublic:
+    type: boolean
+    description: |
+      Whether the task is published on its public landing page. Derived from
+      `publicConfig.publishedAt`. Set it via the [Update task](/api/v2/actor-task-put)
+      endpoint to publish or unpublish the task.
+    examples: [false]
   publicConfig:
     anyOf:
       - $ref: ./TaskPublicConfig.yaml
diff --git a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
index 3502e5fd64..c78979ae0e 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
@@ -11,9 +11,8 @@ properties:
     readOnly: true
     description: |
       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, use the
-      [Publish task](/api/v2/actor-task-publish-post) and
-      [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints.
+      This field is server-controlled - to publish or unpublish a task, set `isPublic`
+      via the [Update task](/api/v2/actor-task-put) endpoint.
     examples: ["2025-06-16T09:20:45.777Z"]
   seoTitle:
     type: [string, "null"]
diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index b86fd48e15..bad6a1a847 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -22,9 +22,14 @@ properties:
     description: |
       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. Use the
-      [Publish task](/api/v2/actor-task-publish-post) and
-      [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints to change the
-      publication state. Updating `publicConfig` requires write permission to the task's
-      Actor.
+      cannot be cleared this way. Set `isPublic` to change the publication state.
+      Updating `publicConfig` requires write permission to the task's Actor.
     $ref: ./TaskPublicConfig.yaml
+  isPublic:
+    type: boolean
+    description: |
+      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.
+    examples: [true]
diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml
index 577151a8f6..149e19e4fc 100644
--- a/apify-api/openapi/openapi.yaml
+++ b/apify-api/openapi/openapi.yaml
@@ -592,10 +592,6 @@ paths:
     $ref: paths/actor-tasks/actor-tasks.yaml
   "/v2/actor-tasks/{actorTaskId}":
     $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}.yaml"
-  "/v2/actor-tasks/{actorTaskId}/publish":
-    $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml"
-  "/v2/actor-tasks/{actorTaskId}/unpublish":
-    $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml"
   "/v2/actor-tasks/{actorTaskId}/input":
     $ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@input.yaml"
   "/v2/actor-tasks/{actorTaskId}/webhooks":
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
index 063be65978..17dc21fa4c 100644
--- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
+++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
@@ -53,9 +53,8 @@ put:
     If the object does not define a specific property, its value is not updated.
 
     The `publicConfig` field carries the display configuration of the task's public
-    landing page. To publish or unpublish the task itself, use the
-    [Publish task](/api/v2/actor-task-publish-post) and
-    [Unpublish task](/api/v2/actor-task-unpublish-post) endpoints.
+    landing page, and `isPublic` publishes or unpublishes the task itself. Both require
+    write permission to the task's Actor.
 
     The response is the full task object as returned by the
     [Get task](/api/v2/actor-task-get) endpoint.
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
deleted file mode 100644
index eb2e015787..0000000000
--- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@publish.yaml
+++ /dev/null
@@ -1,48 +0,0 @@
-post:
-  tags:
-    - Actor tasks
-  summary: Publish task
-  description: |
-    Publish the task on its public landing page. The task's public display configuration
-    is set beforehand via the `publicConfig` field of the
-    [Update task](/api/v2/actor-task-put) endpoint. This endpoint validates it and
-    publishes the task.
-
-    Publishing requires the task's Actor to be public, and the task must pass the
-    publication validation.
-    The publication state is stored in `publicConfig.publishedAt` (`null` means the task
-    is not published).
-
-    The endpoint requires write permission to the task's Actor.
-
-    The response is the full task object as returned by the
-    [Get task](/api/v2/actor-task-get) endpoint.
-  operationId: actorTask_publish_post
-  parameters:
-    - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorTaskId"
-  responses:
-    "200":
-      description: ""
-      headers: {}
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                $ref: ../../components/schemas/actor-tasks/Task.yaml
-    "400":
-      $ref: ../../components/responses/BadRequest.yaml
-    "401":
-      $ref: ../../components/responses/Unauthorized.yaml
-    "403":
-      $ref: ../../components/responses/Forbidden.yaml
-    "404":
-      $ref: ../../components/responses/NotFound.yaml
-    "405":
-      $ref: ../../components/responses/MethodNotAllowed.yaml
-    "429":
-      $ref: ../../components/responses/TooManyRequests.yaml
-  deprecated: false
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml
deleted file mode 100644
index 67a3a90f3d..0000000000
--- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@unpublish.yaml
+++ /dev/null
@@ -1,41 +0,0 @@
-post:
-  tags:
-    - Actor tasks
-  summary: Unpublish task
-  description: |
-    Unpublish the task from its public landing page. The public display configuration
-    (`publicConfig`) is preserved, so the task can be re-published without re-entering it.
-
-    The endpoint requires write permission to the task's Actor.
-
-    The response is the full task object as returned by the
-    [Get task](/api/v2/actor-task-get) endpoint.
-  operationId: actorTask_unpublish_post
-  parameters:
-    - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorTaskId"
-  responses:
-    "200":
-      description: ""
-      headers: {}
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                $ref: ../../components/schemas/actor-tasks/Task.yaml
-    "400":
-      $ref: ../../components/responses/BadRequest.yaml
-    "401":
-      $ref: ../../components/responses/Unauthorized.yaml
-    "403":
-      $ref: ../../components/responses/Forbidden.yaml
-    "404":
-      $ref: ../../components/responses/NotFound.yaml
-    "405":
-      $ref: ../../components/responses/MethodNotAllowed.yaml
-    "429":
-      $ref: ../../components/responses/TooManyRequests.yaml
-  deprecated: false

From e39a1685a0f4bf0ea451ea89a1fccd5f2796bd3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Tue, 11 Aug 2026 16:43:23 +0200
Subject: [PATCH 4/7] chore: docs copy update

---
 .../openapi/components/schemas/actor-tasks/Task.yaml   | 10 +++++++---
 .../schemas/actor-tasks/TaskPublicConfig.yaml          |  9 +++++++--
 .../schemas/actor-tasks/UpdateTaskRequest.yaml         |  4 ++++
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
index 64802ab63d..3cf8b70a67 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
@@ -58,9 +58,13 @@ properties:
   isPublic:
     type: boolean
     description: |
-      Whether the task is published on its public landing page. Derived from
-      `publicConfig.publishedAt`. Set it via the [Update task](/api/v2/actor-task-put)
-      endpoint to publish or unpublish the task.
+      Whether the task is published. Derived from `publicConfig.publishedAt`. Set it via the
+      [Update task](/api/v2/actor-task-put) endpoint to publish or unpublish the task.
+
+      Publishing lists the task among the Actor's examples and makes its input public, so anyone
+      can view and copy it. The task's own landing page is shown only while `publicConfig` still
+      validates against the Actor's current build - a new build can therefore stop the page from
+      being offered while the task stays published and copyable.
     examples: [false]
   publicConfig:
     anyOf:
diff --git a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
index c78979ae0e..3cfbd9f392 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
@@ -31,7 +31,12 @@ properties:
       type: string
   datasetName:
     type: [string, "null"]
-    description: Name of the dataset from the Actor's dataset schema whose results are displayed.
+    description: |
+      Name of the dataset from the Actor's dataset schema whose results are displayed. When
+      `null`, the Actor's default dataset is used - the only dataset it declares, or the one
+      named `default` when it declares several.
   datasetView:
     type: [string, "null"]
-    description: Key of the dataset view from the Actor's dataset schema used to display results.
+    description: |
+      Key of the dataset view from the Actor's dataset schema used to display results. Must be
+      one of the views declared on the resolved dataset; a task cannot be published without it.
diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index bad6a1a847..81b14d0323 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -32,4 +32,8 @@ properties:
       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.
+
+      Publishing makes the task's input public so it can be viewed and copied. Whether its
+      landing page is rendered is re-evaluated against the Actor's current build, so the page
+      can stop being offered after a new build while the task remains published.
     examples: [true]

From f0ac4da6656e5d5166a60bc5e9293823f5723a05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Wed, 12 Aug 2026 15:38:46 +0200
Subject: [PATCH 5/7] chore: remove categorization field from publicConfig

---
 .../components/schemas/actor-tasks/TaskPublicConfig.yaml       | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
index 3cfbd9f392..63893a0d2a 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
@@ -21,9 +21,6 @@ properties:
   seoDescription:
     type: [string, "null"]
     description: SEO description of the public task page. Defaults to the task description when not set.
-  categorization:
-    type: [string, "null"]
-    description: Use-case category of the public task.
   inputSchemaFields:
     type: [array, "null"]
     description: Names of the task input fields displayed on the public task page.

From ecce30a8ae4a793c29c5e799fe029f064635368d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Wed, 12 Aug 2026 17:38:19 +0200
Subject: [PATCH 6/7] feat: update copy based on review

---
 .../actor-tasks/CreateTaskRequest.yaml        |  5 ++---
 .../components/schemas/actor-tasks/Task.yaml  |  8 +------
 .../schemas/actor-tasks/TaskPublicConfig.yaml | 22 ++++++++++++-------
 .../actor-tasks/UpdateTaskRequest.yaml        | 18 ++++++---------
 .../actor-tasks@{actorTaskId}.yaml            | 10 +++++++++
 5 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
index aae35f94a9..447e31b63a 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
@@ -25,7 +25,6 @@ properties:
       - type: "null"
   publicConfig:
     description: |
-      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](/api/v2/actor-task-put)
-      endpoint for that. Setting `publicConfig` requires write permission to the task's Actor.
+      Configuration that controls how the published task appears on its public landing page.
+      Editing this object requires write permission to the Actor that the task belongs to.
     $ref: ./TaskPublicConfig.yaml
diff --git a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
index 3cf8b70a67..d9df867f5d 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/Task.yaml
@@ -58,13 +58,7 @@ properties:
   isPublic:
     type: boolean
     description: |
-      Whether the task is published. Derived from `publicConfig.publishedAt`. Set it via the
-      [Update task](/api/v2/actor-task-put) endpoint to publish or unpublish the task.
-
-      Publishing lists the task among the Actor's examples and makes its input public, so anyone
-      can view and copy it. The task's own landing page is shown only while `publicConfig` still
-      validates against the Actor's current build - a new build can therefore stop the page from
-      being offered while the task stays published and copyable.
+      Whether the task is published. Based on the `publicConfig.publishedAt` field.
     examples: [false]
   publicConfig:
     anyOf:
diff --git a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
index 63893a0d2a..42e8e474a9 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/TaskPublicConfig.yaml
@@ -10,17 +10,23 @@ properties:
     format: date-time
     readOnly: true
     description: |
-      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](/api/v2/actor-task-put) endpoint.
+      Time when the task was published, or `null` if the task isn't published.
+      This field is server-controlled. To publish or unpublish a task, use the
+      [Update task](/api/v2/actor-task-put) endpoint and set `isPublic`.
     examples: ["2025-06-16T09:20:45.777Z"]
   seoTitle:
     type: [string, "null"]
-    description: SEO title of the public task page. Defaults to the task title when not set.
+    maxLength: 60
+    description: |
+      Name of the Actor task to display by search engines such as Google. Defaults to the task
+      title. At most 60 characters.
     examples: [Scrape data from a website]
   seoDescription:
     type: [string, "null"]
-    description: SEO description of the public task page. Defaults to the task description when not set.
+    maxLength: 160
+    description: |
+      Description of the Actor task to display by search engines such as Google. Defaults to the
+      task description. At most 160 characters.
   inputSchemaFields:
     type: [array, "null"]
     description: Names of the task input fields displayed on the public task page.
@@ -30,10 +36,10 @@ properties:
     type: [string, "null"]
     description: |
       Name of the dataset from the Actor's dataset schema whose results are displayed. When
-      `null`, the Actor's default dataset is used - the only dataset it declares, or the one
-      named `default` when it declares several.
+      `null`, the Actor's default dataset is used. That is, the only dataset the Actor declares,
+      or the one named `default` when it declares several.
   datasetView:
     type: [string, "null"]
     description: |
       Key of the dataset view from the Actor's dataset schema used to display results. Must be
-      one of the views declared on the resolved dataset; a task cannot be published without it.
+      one of the views declared on the resolved dataset. You can't publish a task without it.
diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index 81b14d0323..36dc782760 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -20,20 +20,16 @@ properties:
       - type: "null"
   publicConfig:
     description: |
-      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.
+      Configuration that controls how the published task appears on its public landing page.
+      Editing this object requires write permission to the Actor that the task belongs to.
+
+      The fields you send are merged into the stored configuration. To clear a single field,
+      send it as an empty value, such as `""` or `[]`. Sending `publicConfig: null` is rejected,
+      so the object as a whole can't be cleared.
     $ref: ./TaskPublicConfig.yaml
   isPublic:
     type: boolean
     description: |
       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.
-
-      Publishing makes the task's input public so it can be viewed and copied. Whether its
-      landing page is rendered is re-evaluated against the Actor's current build, so the page
-      can stop being offered after a new build while the task remains published.
+      Sending the value the task already has does nothing.
     examples: [true]
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
index 17dc21fa4c..0343cd5cb5 100644
--- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
+++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml
@@ -56,6 +56,16 @@ put:
     landing page, and `isPublic` publishes or unpublishes the task itself. Both require
     write permission to the task's Actor.
 
+    To publish a task, its Actor must be public, `publicConfig.inputSchemaFields` and
+    `publicConfig.datasetView` must be set, and the Actor must have fewer than 50 published
+    tasks. If the task isn't ready to be published, the whole update fails and none of it
+    is applied.
+
+    Publishing lists the task among the Actor's examples and makes its input public, so anyone
+    can view and copy it. The landing page itself is shown only while `publicConfig` still
+    validates against the Actor's current build, so a new build can stop the page from being
+    offered while the task stays published and copyable.
+
     The response is the full task object as returned by the
     [Get task](/api/v2/actor-task-get) endpoint.
 

From 184bc269622b06af955b44780910a0f09ec8673f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20=28Honza=29=20Jir=C3=A1=C5=88?= <jan.jiran@apify.com>
Date: Wed, 12 Aug 2026 17:49:34 +0200
Subject: [PATCH 7/7] chore: fix update doc

---
 .../components/schemas/actor-tasks/UpdateTaskRequest.yaml   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
index 36dc782760..f8f2b7a295 100644
--- a/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
+++ b/apify-api/openapi/components/schemas/actor-tasks/UpdateTaskRequest.yaml
@@ -23,9 +23,9 @@ properties:
       Configuration that controls how the published task appears on its public landing page.
       Editing this object requires write permission to the Actor that the task belongs to.
 
-      The fields you send are merged into the stored configuration. To clear a single field,
-      send it as an empty value, such as `""` or `[]`. Sending `publicConfig: null` is rejected,
-      so the object as a whole can't be cleared.
+      The fields you send are merged into the stored configuration, so you only need to include
+      the ones you're changing. To clear a field, set it to `null`. Sending `publicConfig: null`
+      is rejected, so the object as a whole can't be cleared.
     $ref: ./TaskPublicConfig.yaml
   isPublic:
     type: boolean