skill: teach Standby endpoint discoverability (bind on /, serve OpenAPI, or return endpoints JSON)

[DaveHanns]

Problem

Agents building Standby-mode Actors commonly land on a topology where:

• The primary HTTP handler is bound on /metadata (or /api, or whichever verb-shaped path the task named).
• The root path / returns a plain-text help message like "Actor is ready. Use GET /metadata?url=<url>".

The Actor works when a human reads the help text and constructs the correct URL. But programmatic clients (integrations, CI health checks, other agents) hitting / get non-JSON prose and have no machine-readable way to discover the real endpoint.

Observed in run VeWabeaWNqHOGJpMn (scenario 06, agent's Actor davehan/metadata-api) — the deployed Actor was fully functional at /metadata?url=… but effectively invisible to any non-human caller.

Suggested addition to the skill

Add a "Standby endpoint discoverability" paragraph to the skill teaching one of three canonical patterns:

Pattern A — bind primary handler on / (simplest):

app.get('/', async (req, res) => { /* the primary endpoint */ });

Pattern B — serve OpenAPI at /openapi.json:

app.get('/openapi.json', (req, res) => res.json(openApiSpec));

Pattern C — root returns a machine-readable endpoint list:

app.get('/', (req, res) => res.json({
  service: 'metadata-api',
  endpoints: [
    { path: '/metadata', method: 'GET', params: { url: 'string' } },
  ],
}));

Any of the three closes the discoverability gap. Prose-only help at / is the anti-pattern.

Related

• Companion issue in apify/actor-templates — same teaching in the ts-standby template's AGENTS.md.
• Companion issue in apify/apify-docs — Standby reference page should call out discoverability as a first-class requirement.
• Platform-side (separate ticket against apify/actor-standby-controller): auto-serve webServerSchema at /openapi.json / /.well-known/openapi.json. That closes the platform-side loop; this issue closes the agent-side loop.

Impact

Medium. Standby Actors that aren't programmatically discoverable are partial deployments — any downstream integration needs a path it can't find.

---

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