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] 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