Skip to content

docs: fix medium-severity inaccuracies in Actors pages #2726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mtrunkat wants to merge 3 commits into
base: master
Choose a base branch
from
+142 −137
Open

docs: fix medium-severity inaccuracies in Actors pages #2726

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e769556
docs: fix medium-severity inaccuracies in Actors pages
claude Jul 2, 2026
a1dde23
docs: align markdown tables to satisfy MD060
claude Jul 2, 2026
1670b7e
docs: restore emoji table alignment in publish-task
claude Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion sources/platform/actors/development/actor_definition/actor_json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on
| `environmentVariables` | Optional | A map of environment variables to be used during local development. These variables will also be applied to the Actor when deployed on the Apify platform. For more details, see the [environment variables](/cli/docs/vars) section of the Apify CLI documentation. |
| `dockerfile` | Optional | The path to the Dockerfile to be used for building the Actor on the platform. If not specified, the system will search for Dockerfiles in the `.actor/Dockerfile` and `Dockerfile` paths, in that order. Refer to the [Dockerfile](./docker.md) section for more information. |
| `dockerContextDir` | Optional | The path to the directory to be used as the Docker context when building the Actor. The path is relative to the location of the `actor.json` file. This property is useful for monorepos containing multiple Actors. Refer to the [Actor monorepos](../deployment/source_types.md#actor-monorepos) section for more details. |
| `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/README.md` and `README.md` paths, in that order of preference. Check out [Apify Marketing Playbook to learn how to write a quality README files](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2) guidance. |
| `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/ACTOR.md`, `.actor/README.md`, root `README.md`, and root `README` paths, in that order of preference. Check out [Apify Marketing Playbook to learn how to write a quality README files](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2) guidance. |
| `input` | Optional | You can embed your [input schema](./input_schema/index.md) object directly in `actor.json` under the `input` field. You can also provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` or `INPUT_SCHEMA.json` is used, in this order of preference. You can also use the `inputSchema` alias interchangeably. |
| `output` | Optional | You can embed your [output schema](./output_schema/index.md) object directly in `actor.json` under the `output` field. You can also provide a path to a custom output schema. [Read more](/platform/actors/development/actor-definition/output-schema) about Actor output schemas. You can also use the `outputSchema` alias interchangeably. |
| `changelog` | Optional | The path to the CHANGELOG file displayed in the Information tab of the Actor in Apify Console next to Readme. If not provided, the CHANGELOG at `.actor/CHANGELOG.md` or `CHANGELOG.md` is used, in this order of preference. Your Actor doesn't need to have a CHANGELOG but it is a good practice to keep it updated for published Actors. |
Expand Down
2 changes: 1 addition & 1 deletion sources/platform/actors/development/actor_definition/dataset_schema/validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ Dataset schema needs to be a valid JSON schema draft-07, so the `$schema` line i

When you define a schema of your default dataset, the schema is then always used when you insert data into the dataset to perform validation (we use [AJV](https://ajv.js.org/)).

If the validation succeeds, nothing changes from the current behavior, data is stored and an empty response with status code `201` is returned.
If the validation succeeds, the data is stored and a response with status code `201` is returned. When the schema defines `fields`, the response body contains the computed [field statistics](#dataset-field-statistics) under a `fieldStatistics` property; otherwise the response body is empty.

If the data you attempt to store in the dataset is _invalid_ (meaning any of the items received by the API fails validation), _the entire request will be discarded_, The API will return a response with status code `400` and the following JSON response:

Expand Down
19 changes: 7 additions & 12 deletions sources/platform/actors/development/actor_definition/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,20 +152,15 @@ To use a custom `Dockerfile`, you can either:
If no `Dockerfile` is provided, the system uses the following default:

```dockerfile
FROM apify/actor-node:24

COPY --chown=myuser:myuser package*.json ./
FROM apify/actor-node:20

RUN npm --quiet set progress=false \
&& npm install --only=prod --no-optional \
&& echo "Installed NPM packages:" \
&& (npm list --only=prod --no-optional --all || true) \
&& echo "Node.js version:" \
&& node --version \
&& echo "NPM version:" \
&& npm --version
# Copy all files and directories from the directory to the Docker image
COPY . ./

COPY --chown=myuser:myuser . ./
# Install NPM packages, skip optional and development dependencies to keep the image small,
# avoid logging too much and show the dependency tree
RUN npm install --quiet --only=prod --no-optional \
&& (npm list || true)
```

For more information about `Dockerfile` syntax and commands, see the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/).
Expand Down
1 change: 1 addition & 0 deletions sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,7 @@ After the expression is evaluated, the memory value goes through these steps:
- 900 → 1024 MB
- 3,600 → 4096 MB

1. The value is capped to the maximum Actor memory allowed by your subscription plan. If an expression requests more memory than your plan allows, the run gets the plan limit instead, even when the requested value is below 32 GB.
1. If the Actor has minimum or maximum memory limits defined (`minMemoryMbytes` / `maxMemoryMbytes`), the value is adjusted to stay within those limits.
1. The value is adjusted to stay within platform limits (128 MB to 32 GB).

Expand Down
2 changes: 1 addition & 1 deletion sources/platform/actors/development/actor_definition/input_schema/secret_input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ If you read the `INPUT` key from the Actor run's default key-value store directl

## Encryption mechanism

The encryption mechanism used for encrypting the secret input fields is the same dual encryption as in [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#/media/File:PGP_diagram.svg). The secret input field is encrypted using a random key, using the `aes-256-gcm` cipher, and then the key is encrypted using a 2048-bit RSA key.
The encryption mechanism used for encrypting the secret input fields is the same dual encryption as in [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#/media/File:PGP_diagram.svg). The secret input field is encrypted using a random key, using the `aes-256-ctr` cipher, and then the key is encrypted using a 2048-bit RSA key.

The RSA key is unique for each combination of user and Actor, ensuring that no Actor can decrypt input intended for runs of another Actor by the same user, and no user can decrypt input runs of the same Actor by a different user. This isolation of decryption keys enhances the security of sensitive input data.

Expand Down
24 changes: 12 additions & 12 deletions sources/platform/actors/development/actor_definition/output_schema/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,28 +70,28 @@ The output schema defines the collections of keys and their properties. It allow

### Output schema object definition

| Property | Type | Required | Description |
|-----------------------------------|-------------------------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `actorOutputSchemaVersion` | integer | true | Specifies the version of output schema structure document. <br/>Currently only version 1 is available. |
| `title` | string | true | Title of the schema |
| `description` | string | false | Description of the schema |
| `properties` | Object | true | An object where each key is an output ID and its value is an Output object definition (see below). |
| Property | Type | Required | Description |
|----------------------------|---------|----------|--------------------------------------------------------------------------------------------------------|
| `actorOutputSchemaVersion` | integer | true | Specifies the version of output schema structure document. <br/>Currently only version 1 is available. |
| `title` | string | true | Title of the schema |
| `description` | string | false | Description of the schema |
| `properties` | Object | true | An object where each key is an output ID and its value is an Output object definition (see below). |

### Output object definition

| Property | Type | Required | Description |
|----------------|--------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `title` | string | true | The output's title, shown in the run's output tab if there are multiple outputs and in API as key for the generated output URL. |
| `description` | string | false | A description of the output. Only used when reading the schema (useful for LLMs). |
| `template` | string | true | Defines a URL template that generates the output link using `{{variable}}` syntax. See [How templates work](#how-templates-work) for details. |
| Property | Type | Required | Description |
|---------------|--------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `title` | string | true | The output's title, shown in the run's output tab if there are multiple outputs. In the API response, the generated output URL is keyed by the property name (output ID), not by `title`. |
| `description` | string | false | A description of the output. Only used when reading the schema (useful for LLMs). |
| `template` | string | true | Defines a URL template that generates the output link using `{{variable}}` syntax. See [How templates work](#how-templates-work) for details. |

### Available template variables

| Variable | Type | Description |
|-----------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|
| `links` | object | Contains quick links to most commonly used URLs |
| `links.publicRunUrl` | string | Public run url in format `https://console.apify.com/view/runs/:runId` |
| `links.consoleRunUrl` | string | Console run url in format `https://console.apify.com/actors/runs/:runId` |
| `links.consoleRunUrl` | string | Console run url in format `https://console.apify.com/actors/:actorId/runs/:runId` |
| `links.apiRunUrl` | string | API run url in format `https://api.apify.com/v2/actor-runs/:runId` |
| `links.apiDefaultDatasetUrl` | string | API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId` |
| `links.apiDefaultKeyValueStoreUrl` | string | API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId` |
Expand Down
16 changes: 8 additions & 8 deletions sources/platform/actors/development/actor_definition/web_server_schema/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
title: Web server schema
sidebar_label: Web server schema
sidebar_position: 7
description: Attach an OpenAPI specification to your Actor to enable the interactive Standby tab in Apify Console and Apify Store, where you can browse and test endpoints.
description: Attach an OpenAPI specification to your Actor to enable the interactive Endpoints tab in Apify Console and Apify Store, where you can browse and test endpoints.
slug: /actors/development/actor-definition/web-server-schema
---

The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/platform/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Standby** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser.
The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/platform/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Endpoints** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser.

![Apify Console showing the Standby tab with the Endpoints section rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png)
![Apify Console showing the Endpoints tab rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png)

## Define the web server schema

Expand Down Expand Up @@ -92,7 +92,7 @@ Follow the standard [OpenAPI 3.x format](https://spec.openapis.org/oas/latest.ht

The build process validates `webServerSchema`, similar to other Actor schemas like [input schema](/platform/actors/development/actor-definition/input-schema) and [dataset schema](/platform/actors/development/actor-definition/dataset-schema). If the spec is malformed, the build fails with a validation error.

Once deployed, the **Standby** tab appears automatically on the Actor's detail page when you enable [standby mode](/platform/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens.
Once deployed, the **Endpoints** tab appears automatically on the Actor's detail page when you enable [standby mode](/platform/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens.

:::note Servers field is overwritten

Expand All @@ -102,7 +102,7 @@ Your `servers` array is replaced with the Actor's standby URL at display time. C

## Related fields

| Field | Description |
| --- | --- |
| `usesStandbyMode` | Must be `true` for the **Standby** tab to appear. See [standby mode](/platform/actors/development/programming-interface/standby). |
| `webServerSchema` | The OpenAPI spec that powers the **Standby** tab. Defined in [`.actor/actor.json`](/platform/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. |
| Field | Description |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `usesStandbyMode` | Must be `true` for the **Endpoints** tab to appear. See [standby mode](/platform/actors/development/programming-interface/standby). |
| `webServerSchema` | The OpenAPI spec that powers the **Endpoints** tab. Defined in [`.actor/actor.json`](/platform/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. |
4 changes: 2 additions & 2 deletions sources/platform/actors/development/deployment/continuous_integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,8 +143,8 @@ When using the webhook approach, the Actor must have its source set to a Git rep
:::

1. Go to your Actor's detail page in Apify Console.
1. Go to the **API** tab.
1. Select **API Endpoints** and copy the **Build Actor** API endpoint URL:
1. Select the **API** dropdown button.
1. Select **API endpoints** and copy the **Build Actor** API endpoint URL:

```text
https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=latest&waitForFinish=60
Expand Down
2 changes: 1 addition & 1 deletion sources/platform/actors/development/deployment/source_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Remember that each key can only be used once per Git hosting service (GitHub, Bi

### Actor monorepos

To manage multiple Actors in a single repository, use the `dockerContextDir` property in the [Actor definition](/platform/actors/development/actor-definition/actor-json) to set the Docker context directory (if not provided then the repository root is used). In the Dockerfile, copy both the Actor's source and any shared code into the Docker image.
To manage multiple Actors in a single repository, use the `dockerContextDir` property in the [Actor definition](/platform/actors/development/actor-definition/actor-json) to set the Docker context directory (if not provided, the Actor's source directory - the directory selected as the Actor's root - is used). In the Dockerfile, copy both the Actor's source and any shared code into the Docker image.

To enable sharing Dockerfiles between multiple Actors, the Actor build process passes the `ACTOR_PATH_IN_DOCKER_CONTEXT` build argument to the Docker build.
It contains the relative path from `dockerContextDir` to the directory selected as the root of the Actor in Apify Console (the "directory" part of the Actor's git URL).
Expand Down
2 changes: 1 addition & 1 deletion sources/platform/actors/development/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ slug: /actors/development

This section will guide you through the whole story of [Actor](../index.mdx) development.

You can follow chapters sequentially from [Quick start](/platform/actors/development/quick-start), where you learn how to create your first Actor in just a few minutes, through the more technical sections describing the whole Actor model, up to the [Performance](/sources/platform/actors/development/performance.md) section, where you learn how to fine-tune your Actor to get the most out of the Apify platform.
You can follow chapters sequentially from [Quick start](/platform/actors/development/quick-start), where you learn how to create your first Actor in just a few minutes, through the more technical sections describing the whole Actor model, up to the [Performance](/platform/actors/development/performance) section, where you learn how to fine-tune your Actor to get the most out of the Apify platform.

import Card from "@site/src/components/Card";
import CardGrid from "@site/src/components/CardGrid";
Expand Down
2 changes: 1 addition & 1 deletion sources/platform/actors/development/performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ When you build a Docker image, Docker caches the layers that haven't changed. Th
Consider the following Dockerfile:

```dockerfile
FROM apify/actor-node:16
FROM apify/actor-node:24

COPY package*.json ./

Expand Down
Loading
Loading