[factory-droid]

Requested by Sherry Bai (@factory-sherry) in Slack.

Summary

Adds a usage guide for POST /api/v0/droid/execute under Docs → Reference (docs/reference/droid-execute-api.mdx, linked in docs.json).

The API Reference tab, which is generated from https://api.factory.ai/api/v0/openapi.json, covers the full request and response schema, so this page doesn't repeat the field and error tables. It covers:

• What the endpoint does, and when to use each target kind (environment, computer, session)
• Behavior the schema can't express: provisioning latency, unlisted computers that are cleaned up when idle, and model settings that apply only to new sessions
• curl examples for each target
• Polling for results through the Sessions API, with a completion check tied to the returned messageId and a JS example

Validation

• docs.json parses as valid JSON
• mint broken-links: no broken links found

[factory-droid]

Droid finished @factory-droid[bot]'s task —— View job

---

Both candidates are confirmed against the example and the public Sessions API contract. The polling loop never exits on permanent API errors, and transcript retrieval stops after the first page, omitting replies from longer sessions.

2 inline comments posted

[factory-droid]

[P2] Stop polling when the Sessions API returns a permanent error

The loop ignores every non-2xx response, not just the transient 404 described below. If the API key expires or is revoked during execution, subsequent polls return 401 indefinitely, leaving status unchanged and preventing the example from completing or surfacing the failure. The Sessions API also documents 403 for this endpoint. Handle the expected 404 retry separately and surface other errors rather than polling forever.

Suggested change

	if (session.ok) ({ status } = await session.json());
	if (!session.ok && session.status !== 404) {
	throw new Error(await session.text());
	}
	if (session.ok) ({ status } = await session.json());

[factory-droid]

[P2] Follow message pagination when retrieving the transcript

The messages endpoint is paginated: its public OpenAPI contract returns pagination.hasMore and pagination.nextCursor, and limits each request to 100 messages. A long agent turn, or an existing session with accumulated assistant messages, can exceed that limit. This example fetches only one page and silently omits the remaining replies despite presenting the operation as retrieving the results. Follow nextCursor until hasMore is false, or explicitly explain that the example returns only one page.