Build with an AI coding agent

This site is written to be read by a coding agent as easily as by you. Every page has a Markdown twin at the same address, the machine files describe the whole surface, and every example can be rehearsed without storing anything. This guide is what to hand an agent, and in what order, so it builds against the real contract instead of guessing it.

What to fetch

• One page, not the site. Every page has a Markdown twin at its own address plus index.md — the operation brands lives at /reference/brand/brands/ and its twin at /reference/brand/brands/index.md. Hand the agent the twin of the operation you need; it carries what the operation does, who may call it, the arguments, the answer, a request and a response to copy, and the errors it can answer.
• The family twin lists its operations. When you do not know the operation’s name, fetch the family — /reference/brand/index.md — and the agent reads the table of its operations with a line each; /reference/index.md lists every family.
• The machine index. /index.json is one JSON file of rows: every operation with its name, kind, family, one-line summary, path and whether it allows a dry run, and rows of the same shape for the guides, the use cases, the manuals’ chapters, the types and the error codes. An agent that needs to find an operation by what it does reads this file once.
• The short index for language models. /llms.txt is the site in a few hundred lines: where to start, the guides, the error classes, the manuals, the use cases, the reference by family, and the types. /llms-full.txt is the same shape over every page of the site, one line each — the deeper index when the short one is not enough.
• The schema itself. /schema.graphql is the public contract in GraphQL schema language, with every type and every description; an agent that generates typed code reads it whole. Operations reserved for the platform are marked so, and have no page.

What the examples are

Every request and response on this site is generated from the schema and checked against it — none was run against a live account — and copied here as the reference pages show it. Every id in the examples is made up and resolves nowhere. An agent that pastes an example id into a live call gets a not-found answer, not someone’s record — point it at your own ids once it has the shape.

Rehearse before you write

A change the agent assembles can be checked against your real records without being stored: add the dry-run flag to the envelope beside the version,

{
  "extensions": {
    "at": {
      "version": {
        "name": "genesis",
        "number": 0
      },
      "dryRun": true
    }
  }
}

and the answer is what the real call would give — the refusal in the same error grammar, or the record as it would be written — while nothing changes. Which operations allow it, and how to read the answer, is Dry runs. An agent’s first integration run should be a rehearsal.

The first call

Every call is a POST to https://api.almondtill.com/. The agent needs a session token, which comes from exchanging an API key’s secret once with exchangeApiKey; Your first call walks the five minutes from a key to a first page of records, and Authentication and key hygiene is the whole life of a key — give the agent the secret through your secret store, never in a prompt.

Connecting an assistant to the service itself

This guide is about building software against the API. Connecting an assistant — Claude or ChatGPT — to your own shop, so it reads your records and acts in the office on your behalf, is a different door: it is set up in the office and described at Connect your assistant on the main site.

The hosted documentation server

The same reference is also served as a connection at https://docs.almondtill.com/mcp — a Model Context Protocol server over streamable HTTP, stateless JSON, no credentials asked for or accepted — so a coding agent asks for the one page it needs instead of downloading the site. It answers from the published pages alone, holds no merchant data and runs no retail operation. Its six tools:

• search_docs finds pages by what they are about, ranked as the site's own search ranks them, narrowed to merchant or developer pages on request.
• fetch_page reads one page as Markdown, a slice at a time when it is long.
• describe_operation reads one operation's contract section by section — what it does, who may call it, the arguments, the answer, the errors.
• get_type reads one type: its page and its block of the schema.
• explain_error reads an error class, or one code of it, with what to do.
• get_example reads the request and the response an operation page shows.

Add it to Claude Code:

claude mcp add --transport http almondtill-docs https://docs.almondtill.com/mcp
claude mcp list

or to one project through its .mcp.json:

{ "mcpServers": { "almondtill-docs": { "type": "http", "url": "https://docs.almondtill.com/mcp" } } }

Add it to Codex:

codex mcp add almondtill-docs --url https://docs.almondtill.com/mcp
codex mcp list

Reading the public documentation is separate from acting in a shop: the server needs no authorization and grants none; connecting an assistant to your own records is the office's door, Connect your assistant.

A first exercise: ask the agent to search_docs for brands, describe_operation the one that creates a brand — createBrand — and get_example for it; then have it rehearse the write with the dry-run envelope from "Rehearse before you write" above, against a key of a test organization, and read the answer before anything is stored.