For AI agents: this page is also available as Markdown at https://docs.refabric.com/setting-up/agent-readable-surfaces.md, and the index of every page is https://docs.refabric.com/llms.txt.
Setting Up
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). The API's llms.txt documents and OpenAPI documents are
listed on 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; orGET /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
GET /v1/llms.txt— what the API is.GET /v1/tasks/llms.txt— which task fits the job.GET /v1/tasks/{name}/llms.txt— that task's inputs and output.- 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 itslifecycleisterminal. - On a 4xx answer, read the error's
fieldandctx, 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).
These instructions are for the agent; a key with the tasks:run scope can start jobs on its own.