# Agent-readable surfaces

> The plain-text and machine-readable copies of these docs and of the task catalogue, for AI agents and code generators.

An agent does not need to scrape HTML. The docs site and the API both publish copies made for
machines: Markdown pages, `llms.txt` indexes and OpenAPI documents. This page is the one list of
which host serves which file.

## Surfaces

| Surface | Host | What it holds | Needs a key? | Can spend credits? | Read-only? |
|---|---|---|---|---|---|
| `/docs/llms.txt` | docs site | an index of every docs page, one line each | no | no | yes |
| `/docs/llms-full.txt` | docs site | every docs page in Markdown, in one file | no | no | yes |
| `<page URL>.md` | docs site | one docs page in Markdown | no | no | yes |
| `/docs/sitemap.xml` | docs site | every docs page URL | no | no | yes |
| `GET /v1/llms.txt` | API | what the API is, its tasks and its operations | no | no | yes |
| `GET /v1/tasks/llms.txt` | API | one line per task, grouped by category | no | no | yes |
| `GET /v1/tasks/{name}/llms.txt` | API | one task's page: inputs, examples, output, errors and limits | no | no | yes |
| `GET /v1/tasks/{name}/openapi.json` | API | one task's OpenAPI document, its input and output as named schemas | no | no | yes |
| `GET /v1/openapi.json` | API | the whole public OpenAPI document | no | no | yes |
| `GET /v1/tasks`, `GET /v1/tasks/{name}` | API | the catalogue, with each task's input and output schema | no (`?surface=` needs a key) | no | yes |
| `GET /v1/tasks/{name}/examples` | API | a task's published examples: the request, its input files and its output files | no | no | yes |
| `GET /v1/vocab`, `/v1/concepts`, `/v1/recipes`, `/v1/errors`, `/v1/meta` | API | the closed options, concepts, recipes, error codes and service limits | no | no | yes |
| `POST /v1/tasks/{name}/estimate` | API | the most a request can cost | yes (`tasks:read`) | no | yes |
| `POST /v1/tasks/{name}` | API | runs the task | yes (`tasks:run`) | **yes** | no |

Reads that need no key are limited per IP address; a key gets its own allowance
([Limits](https://docs.refabric.com/task-apis/limits#rate-limits)). The API's `llms.txt` documents and OpenAPI documents are
listed on [Agent surfaces](https://docs.refabric.com/api-reference/platform/platform/agent-surfaces).

## Per-task schemas

For one task, an agent reads either:

- `GET /v1/tasks/{name}/llms.txt` — the task's page as text, written to be read by a model; or
- `GET /v1/tasks/{name}/openapi.json` — the task as an OpenAPI document, to generate a tool
  definition or a typed client.

Both cover published tasks; an unpublished name answers `404`, a removed task `410`.

## Page as Markdown

Every docs page has a Markdown copy at its own URL with `.md` added. The page's **Copy page** menu
copies it or opens it.

## Suggested order

1. `GET /v1/llms.txt` — what the API is.
2. `GET /v1/tasks/llms.txt` — which task fits the job.
3. `GET /v1/tasks/{name}/llms.txt` — that task's inputs and output.
4. The docs pages it links to, as `.md`, when it needs more.

## Agent workflow

| Step | What the agent does | Refabric operation |
|---|---|---|
| search | find the task | `GET /v1/tasks/llms.txt` or `GET /v1/tasks` |
| schema | read its input and output | `GET /v1/tasks/{name}/llms.txt` or `GET /v1/tasks/{name}` |
| estimate | price the exact request | `POST /v1/tasks/{name}/estimate` |
| run | submit it, once | `POST /v1/tasks/{name}` |
| poll | follow the same job | `GET /v1/jobs/{job_id}` |
| result | read its files | `GET /v1/jobs/{job_id}/result` |

## Rules for agents

`/docs/llms.txt` opens with these rules:

- Show the estimate (`POST /v1/tasks/{name}/estimate`) and ask for approval before you run a task.
- Do not submit again to check on a job: every submit starts a new job.
- Poll the same `job_id` (`GET /v1/jobs/{job_id}`) until its `lifecycle` is `terminal`.
- On a 4xx answer, read the error's `field` and `ctx`, fix that part of the request, then send it again.
- The server cannot read a file path on your machine: send a URL, or upload the file first (`POST /v1/files`).

:::note
These instructions are for the agent; a key with the `tasks:run` scope can start jobs on its own.
:::

## Related

::::cards
:::card{title="Agent surfaces" href="/api-reference/platform/platform/agent-surfaces"}
The API's `llms.txt` and OpenAPI documents in detail.
:::
:::card{title="Pricing" href="/task-apis/pricing"}
What an estimate is and how a job is charged.
:::
::::