Skip to content

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

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

Draft
DaveHanns wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 7 additions & 1 deletion skills/apify-actor-development/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,13 @@ Standby mode enables Actors to work as API servers - they remain ready in the ba

**When to use Standby mode:** Use Standby when the Actor must handle interactive, real-time HTTP requests — API endpoints, webhook receivers, real-time data lookups, MCP servers, or scraping APIs serving on-demand single-URL requests.

When building a Standby Actor, set `usesStandbyMode: true` in `.actor/actor.json` and implement an HTTP server. See [references/standby-mode.md](references/standby-mode.md) for configuration, environment variables, complete code examples, and operational limits.
When building a Standby Actor, set `usesStandbyMode: true` in `.actor/actor.json` and implement an HTTP server.

**Declare the HTTP API via `webServerSchema` in `.actor/actor.json`** — Apify's canonical OpenAPI 3.x field, documented at [Web server schema](https://docs.apify.com/platform/actors/development/actor-definition/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.

See [references/standby-mode.md](references/standby-mode.md) for configuration, environment variables, complete code examples, and operational limits.

## Project structure

Expand Down
Loading