Agent Discovery Surfaces

OpenTrain is designed so an autonomous agent can discover the entire platform in-band — no human pasting documentation into a prompt. The app itself serves onboarding instructions, full API specs, and OAuth discovery metadata; this docs site additionally exports every page in agent-friendly formats.

Surfaces Served by the App

All paths are relative to https://app.opentrain.ai:

Surface	What it contains
/llms.txt	The complete agent surface on one page: the 5-call zero-to-live-job quickstart, hiring and payment lifecycle, rich Instructions authoring workflow, and operational rules.
/auth.md	The agent authentication protocol: anonymous registration, the claim ceremony, token polling, revocation, and rotation — with copy-pasteable requests. This is the canonical in-band auth bootstrap.
/api/public/v1/openapi.json	OpenAPI spec for the Public API — the machine-readable contract of record for every endpoint, parameter, and response shape.
/api/partner/v1/openapi.json	OpenAPI spec for the Platform API.
/.well-known/oauth-protected-resource	RFC 9728 protected-resource metadata: supported scopes, bearer methods, documentation pointer.
/.well-known/oauth-authorization-server	RFC 8414 authorization-server metadata, extended with an agent_auth block: the identity and claim endpoints, the claim grant type, and the polling interval.
/api/public/v1/capabilities	Per-token agent-surface discovery, including whether job_operations is available, required and granted scopes, and authorization for every operation. CLI: opentrain capabilities; MCP: opentrain_capabilities.
/api/public/v1/job-drafts/capabilities	Runtime feature discovery for your token (requires auth) — see below.
/api/public/v1/instructions/capabilities	Runtime schema, rich-node, import, limit, and safety guarantees for canonical Job Instructions.
/api/public/v1/instructions/jobs/{jobId}	The canonical Instructions tree, pages, folder inheritance, and employer URL for one job. Requires instructions:read and employer access to the job.
/api/public/v1/project-todos?jobId={jobId}	The canonical Project To-do catalog, assignments, roster, and summary for one job. Requires project_todos:read, a claimed account, and the Project To-dos agent surface.
/api/public/v1/project-todos/quizzes/forms?jobId={jobId}	The native forms and quizzes available to that job, including drafts and immutable published versions. Uses the same Project To-dos scopes and feature gate.
/api/public/v1/project-todos/quizzes/coaching/capabilities	Static selective-coaching operations, scopes, limits, export/image workflow, and typed errors. Requires project_todos:read but intentionally works before the Project To-dos feature gate is enabled.
/api/public/v1/job-operations/jobs/{jobId}/context	The shared operational view an authorized employer team member or agent reads before managing an existing job: objective, readiness, deterministic priorities and evaluator health, effective policies, dynamic per-job Work Catalog, Agent Guide digest, blockers, claims, recent changes, and evidence IDs. Requires jobs:read; this family is always on.
/api/public/v1/job-operations/jobs/{jobId}/sync/poll	One bounded wait for a fresh private-session context delivery. Official CLI/MCP/SDK clients thread and redact the synchronization credential automatically.
/api/public/v1/job-feedback?jobId={jobId}	Employer-private Reviewer Feedback reports, search, status counts, and pagination. Requires job_feedback:read, a claimed employer account, exact job access, and the default-off operation family.
/api/public/v1/job-checklists?jobId={jobId}	Adaptive checklist definitions in worker display order plus the job’s enabled state. Requires job_checklists:read, a claimed employer account, exact job access, and the default-off operation family.

Surfaces Served by This Docs Site

Every page in this documentation is exported for machine consumption:

Surface	What it contains
/docs/llms.txt	A compact starting point organized by task, with complete page indexes for each language.
/docs/llms-index.txt	Every published page across all languages, with one-line summaries and Markdown links.
/docs/llms-en-full.txt	English documentation in one optional download. Fetch individual pages when you need less context.
/docs/llms-full.txt	The entire documentation site concatenated into one file.
A page’s Markdown alternate	Use Use with AI → View as Markdown, or replace the trailing slash with .md, for example /docs/developers/quickstart-http.md. The docs home is /docs/index.md. Code blocks and tab contents survive the export.
/docs/mcp	A public, read-only documentation MCP endpoint using Streamable HTTP. Its tools search and read documentation; no account or API key is required.

To let an agent read documentation, add https://www.opentrain.ai/docs/mcp as a remote HTTP MCP server in your client. Use with AI on each page includes Cursor and VS Code installation links and a configuration you can copy.

The documentation server provides:

• search_docs: search by query, with an optional locale (en, es, fr, de, or ja). Results include excerpts and canonical source URLs.
• read_doc: read the complete Markdown for a returned canonical URL or page slug, such as developers/quickstart-http.
• search and fetch: equivalent search/retrieval tools with stable document IDs and structured citation URLs for clients that expect those tool names. search accepts query; fetch accepts an id from a search result.

Start with search_docs, read the relevant page, and cite its canonical URL. You can also request an ordinary docs page with Accept: text/markdown. Each HTML page advertises its Markdown alternate and the llms.txt that covers it. Translated indexes contain only published translations; the developer reference is currently in English.

Note

The documentation MCP is separate from the product MCP. It cannot inspect your account, publish jobs, hire, or move money. Use the product integration and its authentication, capabilities, and human-approval flow for those actions. Never send an API token to the public documentation server.

Recommended Bootstrap Order

For an agent starting with zero context:

Fetch the App's llms.txt

GET https://app.opentrain.ai/llms.txt — one fetch gives you the full endpoint map and the operational rules.

Read auth.md and Register

GET https://app.opentrain.ai/auth.md, then POST /api/agent/identity to get an ot_pat_ token. (Or skip raw HTTP entirely: the MCP server and CLI named in llms.txt wrap the whole flow.)

Verify and Probe Capabilities

GET /api/public/v1/auth/me confirms identity, scopes, and claim status. GET /api/public/v1/capabilities reports whether each agent surface, including job_operations, is available to the current token. GET /api/public/v1/job-drafts/capabilities reports the separate job-draft and publishing feature state.

Load Shared Context Before Managing an Existing Job

For a live employer job, call GET /api/public/v1/job-operations/jobs/ {jobId}/context before deciding what to do. Use its revision, fresh priority signals, evaluator health, effective policies, guide digest, blockers, action claims, inconsistencies, and evidence IDs to triage. Its synchronized Work Catalog packet automatically teaches the agent to define this job’s own atomic work, coordinate provisional work, or present a pending inferred definition for human approval; there are no platform business work types. The bootstrap envelope’s sync.nextOperations ends with job_operations.agent_guide.get: read the Agent Guide once (the typed projection plus the human-published Playbook), then follow recommendation.agent_guide_changed only when it names an exact Playbook delta. Claim signal-driven or catalog work before investigating it, then re-read the affected canonical record immediately before a consequential action. The CLI uses opentrain manager context get; MCP uses opentrain_get_job_context, and the MCP initialize response teaches this protocol automatically. On current packages, every covered native or bridged call then carries the same private session forward and returns additive conflicts, recommendations, next operations, and coverage diagnostics. See Manage a Live Job With Shared Context.

Discover, Inspect, and Preflight Job Instructions

If the task involves worker guidelines, call GET /api/public/v1/instructions/capabilities, then GET /api/public/v1/instructions/jobs/{jobId} to inspect the job’s real instruction tree. Preview a complete TipTap document at POST /api/public/v1/instructions/jobs/{jobId}/preview, then preflight the exact operation. Set confirmLive: true only with the returned signed token after review because mutations are immediately worker-visible. After writing, use /api/public/v1/instructions/visual to render the real employer or designated test-worker surface into agent-readable PNG, ARIA, diagnostics, and provenance evidence. See Job Instructions.

Inspect Project To-dos Before Assigning

For post-hire requirements, read GET /api/public/v1/project-todos?jobId= {jobId} first. Use the no-write response as the availability probe because the general capabilities payload does not yet enumerate this default-off family. Then use the no-write preflight action before creating or assigning anything; broad audiences require the signed receipt returned by that exact preview. See Project To-dos.

Inspect Job Quality Workflows

For Reviewer Feedback or Task Checklists, first inspect the matching agentSurfaces family in GET /api/public/v1/capabilities. Then read the job-scoped settings and canonical data before writing. Reviewer Feedback uses /api/public/v1/job-feedback; adaptive Task Checklists use /api/public/v1/job-checklists. Keep feedback employer-private, and use checklist validate, resolve, and exact-revision browser preview before publishing. See Reviewer Feedback and Task Checklists.

Pull the OpenAPI Spec on Demand

When you need exact request and response shapes beyond what llms.txt covers, fetch /api/public/v1/openapi.json — it is generated from the same code that serves the endpoints.

Deep-Dive in These Docs

For concepts that need prose — the claim ceremony, co-signed spending, webhook signature verification — fetch the relevant docs page with .md appended.

Capabilities: Runtime Feature Discovery

Endpoint families behind feature flags (publishing, hiring, messaging writes, payments writes, credits, webhooks) can be enabled or disabled per account. The static docs can’t tell you what your account can do right now — the capabilities endpoint can:

curl -s https://app.opentrain.ai/api/public/v1/job-drafts/capabilities \
  -H "Authorization: Bearer $OT_API_TOKEN"

The response reports which features are on for your token (for example capabilities.publish), plus the accepted job-draft formats and field enums.

Tip

Always probe capabilities at startup instead of assuming a feature is available. A disabled feature returns a structured error naming the missing flag — but probing first avoids burning a write attempt to find out. See Scopes and Capabilities.

Keeping Specs and Docs Straight

• The served openapi.json files are the contract of record — generated from the same code that handles requests. If this site and the spec ever disagree, trust the spec (and tell us).
• auth.md and llms.txt are served by the app itself and versioned with it, so they always describe the deployed behavior. Instructions also has its own capability document because rich-document vocabularies need more detail than a top-level feature flag.
• A scope grant does not override an account capability. Project To-dos and quizzes require the default-off project_todos_integrations agent-surface family in addition to project_todos:read or project_todos:write; a disabled family returns 403 with details.reason = "AGENT_SURFACE_DISABLED". Static coaching-capability discovery is the no-tenant-data exception. Worker coaching uses a worker-minted project_todos:respond key that employer Full access deliberately excludes.
• Reviewer Feedback and Task Checklists use the same fail-closed discovery pattern through the job_feedback and job_checklists families. Their per-job switches are independent and default off; disabling a job surface preserves its private records, definitions, versions, grants, and results.
• Shared job operations context is different: it is baseline employer job-management infrastructure with no environment, app, or UI rollout flag. jobs:read authorizes reads; supported decisions, observations, coordination actions, checkpoints, handoffs, and sweeps require jobs:write.
• When job_operations is available, every writable live-job session follows the same automatic startup contract: read context, sweep with that revision, continue with each returned contextRevision until hasMore=false, then read context again. Review evaluator health, fresh priority signals, effective policies, the Agent Guide digest, and current claims before selecting work. Read-only sessions stop after the read. CLI root/manager help and both MCP initialize responses carry this protocol, so agents do not depend on a copied prompt or local memory file.
• Deterministic attention signals are an investigation queue, not automatic authorization. Shadow-rule findings do not enter the default queue, and stale or incomplete evaluators are surfaced as health rather than current work. Claiming a signal creates or reuses its shared action lease; acknowledging, snoozing, and dismissing change triage only. Only the evaluator clears the underlying condition.
• Job-wide operating changes belong in attributed typed policies, not local agent prompts. The Agent Guide is the shared AGENTS.md-equivalent: a typed projection derived from current state plus the human-published Playbook; canonical records and effective typed policies remain authoritative, and agents change the Playbook only through recommended proposals that a human publishes. MCP hosts can also read the guide as Markdown at opentrain://jobs/{jobId}/operations/agent-guide; resource discovery is optional because the normal context response already includes the guide digest and the bootstrap envelope directs the one guide read.
• Managed outbound messages use the signed action receipt and the exact latest message ID in jobOperationsGuard; the exact CLI manager messages send alias and MCP opentrain_send_managed_job_message tool fail closed before network access when any field is missing. They use the synchronized messaging_management.messages.send operation with both messages:write and messages:manage. Generic message send remains intentionally unsynchronized.
• Shared context begins in CLI/MCP 0.8.0+ and SDK 0.7.0+. Deterministic signals, typed policies, and the canonical guide projection require CLI/MCP 0.10.0+ and SDK 0.9.0+. Automatic cross-command synchronization, bounded polling, write-ahead intents, reviewable proposals, and scoped TEAM/PERSONAL/SESSION overlays require CLI/MCP 0.11.0+ or SDK 0.10.0+. Official clients retain the server credential privately and expose only redacted sync plus exhaustive syncCoverage diagnostics to the agent. If npm latest is older, treat the package release as pending even if these docs are already visible.
• The dynamic per-job Work Catalog, human-only coordination modes, bounded external attestations, action renewal/handoff, and shared work-presence projection require CLI/MCP 0.23.0+ and SDK 0.21.0+. Every covered response drives missing catalog setup through sync.workCatalog, recommendations, and exact next operations. The user should not need to know that setup exists or ask the agent to run it. An inferred definition is a review proposal, not an active type, until an authorized non-agent manager approves the exact semantics.
• The composite Agent Guide, Playbook versions and exact deltas, Playbook proposals, and human publication require CLI/MCP 0.26.0+ and SDK 0.24.0+. The bootstrap envelope directs exactly one guide read; later envelopes name the exact delta only when the published head moved past the version the agent could have held. Agents acknowledge only revisions that were actually delivered, and the CLI keeps that sync state only under a stable agent identity (PASEO_AGENT_ID or OPENTRAIN_AGENT_INSTANCE).
• Hosted LMS visual proof requires CLI/MCP 0.17.0+ and SDK 0.15.0+. It renders the real worker player into revision-bound PNG, ARIA, diagnostics, and manifest evidence; exposes a closed typed step vocabulary; and can mint short-lived observe-only employer review links. Preview evidence is isolated from learner progress and must not be reported as proof of assignment delivery.
• Hosted Instructions and Native Forms visual proof requires CLI/MCP 0.23.0+ and SDK 0.21.0+. Direct render operations return agent-readable PNG, ARIA, diagnostics, and provenance evidence from the real product renderer; they do not require a browser or Vercel login. Human observe links are separate, short-lived, and bound to normal OpenTrain authorization. Native Forms preview is zero-write simulated worker evidence. Instructions worker proof requires a designated real test-worker contract, and captured evidence never claims real-time collaboration delivery.
• Canonical LMS authoring diagnostics require CLI/MCP 0.20.0+ and SDK 0.18.0+. Read authoringDiagnostics from opentrain lms capabilities --json instead of hard-coding finding codes or thresholds. Local and remote validation use the same analyzer. Publishing fails closed on contradictions and requires the exact, content-bound acknowledgement IDs returned by the latest validation for reviewed warnings; acknowledgements are request-only and do not become stored course state.
• Canonical LMS draft authoringIntent and deterministic, strictly no-write individualized-retraining scaffolds require CLI/MCP 0.21.0+ and SDK 0.19.0+. Preserve the intent across checkout, diff, push, publish, and Preview; INDIVIDUAL_MASTERY with EMPLOYER_REVIEW is a typed contradiction rather than an implicit mode conversion.
• The API reference in these docs is hand-written for readability and checked against the served specs.