Build with AI

These docs are published for two readers: you, and whatever agent is helping you integrate. Everything the human pages say also exists in a machine-shaped form — a markdown twin of every page, an index and a single-file corpus for LLMs, the OpenAPI description the reference is generated from, and two MCP servers: one that answers from the real pages, and one that reads — and, scope permitting, operates — a store's live data through the API itself. This page is where each one lives and how to point your tools at it.

None of it is required to use the API. It exists so an agent reads what these docs actually say instead of guessing from APIs that merely resemble ours.

Markdown for every page

Append .md to any docs URL and you get that page as raw markdown — no nav chrome, no highlighting markup, just the content:

The overview's twin is /developers.md, and the generated reference follows the same rule — /developers/reference/orders.md is the orders reference as markdown.

Two files cover the corpus as a whole:

• /llms.txt — the index, per the llms.txt convention: every page as an absolute .md link with a one-line summary. Give this to tools that crawl and follow links.
• /llms-full.txt — every page concatenated in sidebar reading order. Give this to tools that read: it fits comfortably in a modern context window, so pasting it into a chat hands the model the entire documentation at once.

Every page header also carries a Copy page button that copies the page's markdown twin, and a menu that opens the page in Claude or ChatGPT with the twin's URL already in the prompt.

The OpenAPI description

The API is described by one published OpenAPI document:

https://www.shopdeskbd.com/openapi/public-v1.json

It is the same artifact the reference pages are generated from, so the two cannot disagree — anything the spec declares, the reference shows, and nothing in the reference was written by hand.

One URL unlocks the usual tooling: generate a typed client, import the collection into Postman or Insomnia, or hand it to a ChatGPT GPT Action, which takes an OpenAPI URL directly.

Add the docs to your tools

Cursor — Settings → Indexing & Docs → Add Doc, then paste https://www.shopdeskbd.com/llms.txt. Cursor indexes the linked pages and cites them in chat.

Claude Code — connect the MCP server with the one-liner in the next section. Without MCP, telling it to fetch https://www.shopdeskbd.com/llms.txt and follow the links it needs works nearly as well.

ChatGPT — a GPT Action takes the OpenAPI URL above directly; for questions rather than calls, paste /llms-full.txt into the conversation.

Everything else — any agent that can fetch a URL can read the .md twins, and any tool that accepts a document can take /llms-full.txt.

The docs MCP server

The docs run a Model Context Protocol server at:

https://www.shopdeskbd.com/developers/mcp

Transport is Streamable HTTP, and there is no authentication — it serves the same public pages you are reading and nothing else.

Every tool is read-only and says so (readOnlyHint), and an argument it does not know is refused by name.

For Claude Code, one command:

claude mcp add --transport http shopdesk-docs https://www.shopdeskbd.com/developers/mcp

For other MCP clients, the generic configuration block:

{
  "mcpServers": {
    "shopdesk-docs": {
      "type": "http",
      "url": "https://www.shopdeskbd.com/developers/mcp"
    }
  }
}

The store MCP server

The API itself also speaks MCP. A second server exposes a store's live data as curated tools, at:

https://api.shopdeskbd.com/ext/mcp/v1

Transport is Streamable HTTP, and it authenticates exactly like the REST API: the same Authorization: Bearer header, the same keys, the same tenant boundary. The key the connection carries decides which company — and, for a store key, which store — every tool can see, and each tool requires the same scope as its REST counterpart (a tool that combines several reads requires all of their scopes). Each key lists only its own tools: tools/list shows the tools whose scopes the key holds, so an agent never sees a tool it cannot call.

Every tool is documented on MCP tools — scopes, arguments, metering and output — generated from the tool manifest the server publishes at https://www.shopdeskbd.com/openapi/mcp-tools-v1.json.

Eight tools answer the questions a merchant asks most, in one call each:

These answer concisely by default — the fields needed to act, names beside ids — and take response_format: "detailed" for the full objects. The COD confirmation guide walks through them.

Twelve more tools read, one per REST read:

And ten write — one per core write endpoint, running the same engine the merchant's own staff use, so a tool call cannot do anything the dashboard could not.

Five more build a catalog — attributes, categories and brands, photos by link, and one variant at a time. The catalog guide walks through them.

One more puts a video on a product. The video guide walks through it.

The tools that take links — create_product, create_category, create_brand, add_product_images_from_urls and attach_product_video — declare openWorldHint: true, because they download from outside the store (through the same checks as the REST API: see Photos by link); every other tool declares false. Photo reordering, edits and deletes, multipart uploads, catalog updates, and the video upload session, covers and deletes stay on REST.

The write tools are opt-in, and the opt-in is the key: each tool requires the same write scope as its REST twin, so a key minted with read scopes simply cannot write — it does not even list them. Writes carry the idempotency contract as an idempotency_key argument — required on create_order, record_order_payment, adjust_inventory, and attach_product_video when it imports a video_url; honoured everywhere else. The rules are the header's, verbatim: one unique value per logical operation, the same value on every retry of it, replays answer with the original result.

List tools page exactly like the REST API — pass meta.next_cursor back as starting_after until it comes back null. Every tool declares an outputSchema and answers with structuredContent, plus the same value as minified JSON text. The REST mirrors return what their REST twins return, because each calls the same service its twin calls — a write answers with the object re-read through the public serializer (or, for archive_product, the same small { id, archived } receipt).

One difference is deliberate: text a shopper wrote is returned as data. Order and follow-up notes, delivery addresses, customer names and emails, and checkout answers come back in labelled fields, at most 500 characters, with links, markup and hidden characters removed — so a note that reads like an instruction reaches the model as a quoted value, never as something to follow. The REST API returns those fields unchanged.

Tool calls count against the key's rate limits: reads against the read limit (the two summary tools as 5 reads each), writes against the write limit. A call to a tool the key does not list counts as a write.

A call that fails comes back as a tool result with isError: true, and its text is the REST error object — { "error": { code, message, fields? } }, with the same stable codes. When a name the call used matches nothing or several rows (an option name on create_product, a parent category), the error object also carries candidates: the rows it could have meant, names beside ids. A tool the key does not list is refused as an unknown tool. The request id is not in that text: it is in the result's _meta.request_id, the same value as the exchange's X-Request-Id header, so it reaches your logs without being handed to the model. Failed tool calls count as errors on the dashboard's API usage page.

For Claude Code, one command (the key travels as a header):

claude mcp add --transport http shopdesk-store https://api.shopdeskbd.com/ext/mcp/v1 --header "Authorization: Bearer shopdesk_sk_your_key_here"

For other MCP clients:

{
  "mcpServers": {
    "shopdesk-store": {
      "type": "http",
      "url": "https://api.shopdeskbd.com/ext/mcp/v1",
      "headers": {
        "Authorization": "Bearer shopdesk_sk_your_key_here"
      }
    }
  }
}

Drop this in your repo

If a coding agent works on your integration, put a short description of this API where your agent reads instructions — an AGENTS.md, a CLAUDE.md, a system prompt. The block below is deliberately compact: enough to make correct calls, with links to where everything else lives.

## Shopdesk Commerce API
 
- REST API over a Shop Desk store's live data: products, orders, customers,
  inventory, locations and sales channels. JSON in, JSON out.
- Base URL: `https://api.shopdeskbd.com/ext/v1`
- Auth: `Authorization: Bearer <key>`. Keys start with `shopdesk_sk_` and are
  created in the dashboard under Settings → Developer. Server-side only.
- Errors: every failure is `{ error: { code, message, request_id } }`.
  Branch on `code` — it is stable. `message` is human copy and may be
  reworded at any time. Validation failures add a `fields` map.
- Writes: send an `Idempotency-Key` header (any unique value up to 255
  characters; a UUID is ideal) and reuse the SAME key when retrying the
  same operation. Required on `POST /orders`, `POST /orders/{id}/payments`
  and `POST /inventory/adjustments`; honoured on every other write.
- Pagination: cursor-based. Pass `limit` (max 100) and `starting_after` =
  the previous page's `meta.next_cursor`; stop when `next_cursor` is null.
- Machine-readable docs:
  - OpenAPI: https://www.shopdeskbd.com/openapi/public-v1.json
  - Docs index: https://www.shopdeskbd.com/llms.txt
    (whole corpus in one file: https://www.shopdeskbd.com/llms-full.txt)
  - Docs MCP, Streamable HTTP, no auth: https://www.shopdeskbd.com/developers/mcp
  - Store MCP (live store data through curated read + write tools, gated by
    the key's scopes, same Bearer key): https://api.shopdeskbd.com/ext/mcp/v1
    (tool manifest: https://www.shopdeskbd.com/openapi/mcp-tools-v1.json)

The facts in that block are the same ones documented on Getting started, Errors, Writes & idempotency and Pagination — when in doubt, those pages are the authority, and an agent with the MCP server attached can check them itself.