> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Discovery Surfaces

> Every machine-readable entry point OpenTrain serves for autonomous agents, and the recommended bootstrap order.

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`](https://app.opentrain.ai/llms.txt)                                                             | The complete agent surface on one page: the 5-call zero-to-live-job quickstart, every lifecycle endpoint (hiring, contracts, milestones, credits, webhooks), and the operational notes (scopes, flags, claim and co-sign rules). |
| [`/auth.md`](https://app.opentrain.ai/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`](https://app.opentrain.ai/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`](https://app.opentrain.ai/api/partner/v1/openapi.json)                       | OpenAPI spec for the [Platform API](/docs/developers/annotation-platforms/overview).                                                                                                                                                  |
| [`/.well-known/oauth-protected-resource`](https://app.opentrain.ai/.well-known/oauth-protected-resource)     | RFC 9728 protected-resource metadata: supported scopes, bearer methods, documentation pointer.                                                                                                                                   |
| [`/.well-known/oauth-authorization-server`](https://app.opentrain.ai/.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/job-drafts/capabilities`                                                                     | Runtime feature discovery for *your* token (requires auth) — see below.                                                                                                                                                          |

## Surfaces Served by This Docs Site

Every page in this documentation is exported for machine consumption:

| Surface                                                              | What it contains                                                                                                                                                                                                                  |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/docs/llms.txt`](https://www.opentrain.ai/docs/llms.txt)           | Index of all documentation pages with one-line summaries.                                                                                                                                                                         |
| [`/docs/llms-full.txt`](https://www.opentrain.ai/docs/llms-full.txt) | The entire documentation site concatenated into one file.                                                                                                                                                                         |
| Any page + `.md`                                                     | Append `.md` to any docs URL for clean Markdown of that page — for example [`/docs/developers/quickstart-http.md`](https://www.opentrain.ai/docs/developers/quickstart-http.md). Code blocks and tab contents survive the export. |

## Recommended Bootstrap Order

For an agent starting with zero context:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.)
  </Step>

  <Step title="Verify and Probe Capabilities">
    `GET /api/public/v1/auth/me` confirms identity, scopes, and claim
    status. `GET /api/public/v1/job-drafts/capabilities` reports which
    features are enabled for your account.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Deep-Dive in These Docs">
    For concepts that need prose — the [claim
    ceremony](/docs/developers/concepts/authentication), [co-signed
    spending](/docs/developers/concepts/human-approvals), [webhook signature
    verification](/docs/developers/guides/verify-webhook-signatures) — fetch the
    relevant docs page with `.md` appended.
  </Step>
</Steps>

## 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:

```bash theme={null}
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](/docs/developers/concepts/scopes-and-capabilities).
</Tip>

## 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.
* The [API reference](/docs/developers/api-reference/overview) in these docs is hand-written for readability and checked against the served specs.