docs(standby): call out endpoint discoverability as a first-class Standby requirement

Open Beginner friendly
  • Is something wrong?
#2,742 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
javascript
Domain
documentation

Research direction

Start with the Standby documentation page at platform/actors/development/programming-interface/standby and check how it explains endpoint routing and webServerSchema in actor.json. Add an “Endpoint discoverability” subsection covering the three suggested patterns and identifying root-path prose as an anti-pattern. Done means the page communicates these recommendations and cross-references the schema.

Written by the indexing model from the issue text.

Description

Problem

The Apify Standby documentation (platform/actors/development/programming-interface/standby) describes how to build a Standby Actor but does not call out endpoint discoverability as a first-class concern.

Agents (and human authors) commonly land on a topology where:

  • Primary HTTP handler is bound on /metadata (or /api, or another verb-shaped path).
  • Root / returns plain-text help: "Actor is ready. Use GET /metadata?url=<url>".

The Actor is reachable, but only by a human reading the help text — programmatic clients hitting / get non-JSON prose and have no machine-readable way to find the real endpoint.

Observed in an eval run (scenario 06, agent's Actor davehan/metadata-api) — deployed Actor was fully functional at /metadata?url=… but invisible to any programmatic client.

Suggested change

Add a "Endpoint discoverability" subsection to the Standby documentation calling out that a well-formed Standby Actor should adopt one of three patterns:

  1. Bind the primary handler on / — simplest; the URL you hand out IS the URL clients hit.
  2. Serve an OpenAPI spec at /openapi.json — clients can auto-discover the shape. Cross-reference the webServerSchema in actor.json.
  3. Return a machine-readable {"endpoints": [...]} JSON at / — minimal escape hatch when / is reserved for something else.

Root-path prose (Actor is ready. Use GET /metadata?...) should be explicitly called out as an anti-pattern.

Related

  • Sibling change in apify/agent-skills — the same teaching in the public skill.
  • Sibling change in apify/actor-templates — teaching baked into the ts-standby template AGENTS.md.
  • Platform-side (apify/actor-standby-controller #340): auto-serve webServerSchema at /openapi.json on the Standby URL. That closes the platform-side loop; docs closes the human-authoring loop.

Impact

Medium. Docs are the primary teaching surface — agents that pre-train on Apify docs and human authors both benefit.

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

Dominant language
JavaScript
Stars
82
Forks
240
Avg merge
3d 17h
Merged PRs (30d)
73

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from apify/apify-docs

All issues in apify/apify-docs

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.