Skip to content

docs(apify-actor-development): declare Standby API via webServerSchema and self-serve /openapi.json#72

Draft
DaveHanns wants to merge 1 commit into
apify:mainfrom
DaveHanns:docs/skill-migration-7-standby-webserverschema
Draft

docs(apify-actor-development): declare Standby API via webServerSchema and self-serve /openapi.json#72
DaveHanns wants to merge 1 commit into
apify:mainfrom
DaveHanns:docs/skill-migration-7-standby-webserverschema

Conversation

@DaveHanns

Copy link
Copy Markdown

The current ## Standby mode section in skills/apify-actor-development/SKILL.md tells agents to set usesStandbyMode: true and implement an HTTP server, then defers everything else to references/standby-mode.md. Two teachings that materially improve every Standby Actor are missing from the primary skill:

  1. Declaring the HTTP API via webServerSchema in .actor/actor.json — Apify's canonical OpenAPI 3.x field. Declaring it gets a Console "Standby" tab rendered as Swagger UI for free and makes the Actor discoverable to programmatic OpenAPI consumers.
  2. Self-serving /openapi.json on the HTTP server itself — the platform does not currently auto-serve the schema at a conventional path on the public Standby URL, so a curl-and-go client that only has the Standby URL cannot fetch the schema unless the server exposes it directly.

This PR expands ## Standby mode with two short paragraphs covering both points, keeping the existing references/standby-mode.md link in place for the deeper reference material.

Added content (verbatim)

Declare the HTTP API via webServerSchema in .actor/actor.json — Apify's canonical OpenAPI 3.x field, documented at Web server schema. Two forms: a path reference ("webServerSchema": "./openapi.json" + ship .actor/openapi.json) — recommended — or an inline object. Declaring the schema gets you a Console "Standby" tab rendered as Swagger UI (users invoke endpoints from the browser with no auth setup) and makes the Actor discoverable to programmatic consumers (other agents, integrations, OpenAPI tooling).

Also self-serve /openapi.json (and /.well-known/openapi.json) on your HTTP server with the same document. Apify does not currently auto-serve the schema at a conventional path on the public Standby URL, so a curl-and-go client that doesn't have your actor id or an Apify token needs the server to expose it directly. If you also serve a welcome / index response at /, prefer JSON over plain text (e.g. {"name":"…","endpoints":[…],"openapi":"/openapi.json"}) so machine clients hitting the root get something parseable.

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants