Magento describes its own REST API in machine-readable form. Every route is declared in a webapi.xml, every payload shape is a PHP interface with typed getters, and every route names the ACL resource that guards it. Measured on a stock 2.4.8-p5 install with sample data and Elasticsuite:
TL;DR — Magento declares its own REST surface in machine-readable form: on a stock 2.4.8-p5 install, 37 webapi.xml files, 432 routes, 177 service interfaces and 326 DTOs, each route naming the ACL resource that guards it. That is enough to build an agent skill that never invents an endpoint, and nowhere near enough to make an integration correct. The definitions carry shape and permission — not semantics, not sequencing, and not the calls that report success while storing nothing. Execution against a running install fills that gap.
| Count | |
|---|---|
webapi.xml files | 37 |
| Declared routes | 432 |
| Distinct service interfaces behind them | 177 |
Api/Data/*Interface DTO definitions | 326 |
| Distinct ACL resources | 60 |
Routes marked anonymous | 71 |
Routes marked self | 41 |
| By verb | GET 192, POST 139, PUT 62, DELETE 39 |
That is a complete, versioned, machine-readable description of the API surface, sitting in the vendor directory of every install. The obvious move is to generate an agent skill from it — one that knows every endpoint, never invents a route, and gets the payload shape right.
That move is worth making. It is also worth being honest about what it buys, because a skill built only from the definitions will be confidently wrong in exactly the ways a verification pass against a running store turns up.
What the definitions genuinely give you
Four things, and they are not small.
Route existence. Every hallucinated endpoint is prevented by a grep. webapi.xml is the authority: 432 routes, each with a verb, a URL template, a service class and method, and an ACL resource. A skill that resolves each claimed endpoint against this file cannot invent POST /V1/products/import or config:set graphql/validation/maximum_query_depth. That single check would have caught several errors in the drafts this work started from.
Payload shape. Api/Data/*Interface gives the field list, the types, and — via the const declarations — the exact wire names. BasePriceInterface says price, store_id, sku; TierPriceInterface says price_type with fixed and discount as its constants. Generating the field list from the interface is strictly better than remembering it.
A description in words, worth exactly what the docblock is worth. The generated schema is not only shapes. Every operation and every parameter arrives with a prose description, lifted from the PHPDoc on the service interface: ClassReflector::extractMethodData() takes the operation summary from the method’s docblock and each parameter’s text from its @param tag, and the Swagger generator drops both straight into description. It is not optional either — a method whose docblock is empty throws LogicException: The docBlock of the method … is empty rather than producing a blank field, which is why the coding standard is so insistent about Api interfaces.
For an agent that matters more than it sounds. Choosing the right endpoint out of 432 is a language problem before it is a schema problem, and a route list with no prose is a poor tool catalogue.
The limit is inside the sentence. A docblock says what the author meant the method to do — "Save product", "Delete category by ID" — which is intent, not behaviour. No summary line says that this save writes a store-scoped override, or that this delete cascades to children and unassigns every product beneath. So the prose inherits the same blind spot as everything else declared: accurate about the declaration, silent about what happens.
The authorization boundary — with one large caveat. The <resource ref="…"> on each route names the permission that guards it, and it surfaces things worth alarming about: 71 routes are declared anonymous, including POST /V1/customers and the entire /V1/guest-carts/* family.
The caveat is that the declaration is not the effective permission. Magento_WebapiSecurity registers a plugin on the web-API config converter that rewrites the ACL for 31 catalog and inventory reads when webapi/webapisecurity/allow_insecure is enabled. Adobe’s documentation presents this as Allow Anonymous Guest Access and frames the feature as restricting anonymous access; measured on 2.4.8-p5, switching it on took GET /V1/products from 401 to returning all 2,040 products with prices and stock, to an unauthenticated caller.
So a generated skill that reads <resource> and reports "this endpoint requires authorization" is telling you what the file says, not what the store does. The declaration is authoritative on existence and merely indicative on authorization. Anything that matters has to be answered by calling the endpoint with no credential and observing.
What they do not give you, which is the whole problem
The definitions describe shape. Every expensive mistake in the pass behind this article was behaviour, and behaviour is not declared anywhere.
A generated skill reading SourceItemsSaveInterface::execute(array $sourceItems): void learns the payload shape perfectly and learns nothing about the fact that a nonexistent SKU is accepted silently, a negative quantity is persisted, and one bad source_code rolls back the entire batch. Reading CategoryLinkInterface tells it category_id is a string; it does not tell it that a shorter category_links array removes nothing while an empty one removes everything. Nothing in webapi.xml distinguishes POST /V1/categories/{id}/products (idempotent, upserts) from POST /V1/configurable-products/{sku}/child (not idempotent, 400 on repeat), because they are the same shape.
Concretely, none of the following is derivable from any definition file:
| Behaviour | Where it actually lives |
|---|---|
| Error model — partial vs atomic vs silent | Only in the implementation, and it differs per family |
| Idempotency of each write | Only by trying it twice |
| Which store scope a scopeless route writes to | Emergent from route parsing + EAV scope |
Whether a 200 means the data was stored | category_ids, value_index, attribute-set drops all say 200 and store nothing |
| Sequencing constraints | Children before parents; options before links |
| Which fields are silently dropped | Attribute-set membership, price on grouped products |
That message carries unresolved %1 placeholders | Only by reading a real response |
There is a fourth category the definitions actively mislead on. ProductAttributeInterface has a closed field list, so a generator reading it produces a correct field list — and a skill that believes the field list is the attribute model will confidently tell you to set facet_max_size or search_weight or additional_data, all of which are real columns on catalog_eav_attribute and all of which the API rejects. The definition is accurate about itself and misleading about the domain.
The shape of a skill that would actually work
Three layers, only the first of which is generated.
Layer 1 — not written by hand, and probably not written at all. The temptation is to generate a route and DTO index into the skill. Do not: it is version- and install-specific, so it rots on the first upgrade, and it makes the skill enormous for content that is already sitting in the install.
Export it from the target system instead. The working example is three steps and no authoring: Magento publishes a machine-readable schema, so import that into a collection and expose the collection over MCP. The concrete calling layer is then generated from the same install you are integrating with, and regenerates when it changes — which also keeps the skill free of anything a version bump invalidates.
The export is permission-scoped, which turns out to be the best thing about it. The schema describes what the requesting credential may call: 45 paths anonymously, 325 with an administrator token, and 71 with an integration token restricted to catalog. Generate it with the credential the client will actually use and the collection describes precisely that client’s reachable surface — it cannot produce a call the token would be refused for.
One thing this does not remove: webapi.xml in the install stays the authority on whether a route exists at all. That check is what makes an invented endpoint impossible — and, as above, it is authoritative on existence only, not on who may call it.
Layer 2 — the behavioural contract, hand-written and test-backed. One entry per endpoint family, recording what the definitions cannot: error model, idempotency, scope behaviour, silent-drop conditions, sequencing prerequisites, and the exact text of the failures worth special-casing. This is the layer that makes the skill useful rather than merely accurate, and there is no way to generate it. Every row has to be executed against a real install.
That is what the pass behind this article was — one endpoint family at a time, against a running store, reading back what was stored rather than trusting what was returned. What each family turned out to hide, one line each:
- Products and variants — "partial update" is partial only for scalars, two concurrent creates for one key both succeed, and several writes report success and store nothing.
- Attributes — a closed field list that rejects everything modules add, and an option label set that deletes every translation you omit from it.
- Media — nothing is deduplicated by content, filename or label, and the gallery is global while the image roles are per store view.
- Prices and stock — two endpoints that look alike and have opposite error models: per-item failures on one, all-or-nothing plus silent acceptance of bad data on the other.
- Categories — no natural key anywhere in the schema, and two assignment paths whose asymmetry means assignments only ever accumulate.
- Customers — an unauthenticated create that sends mail, mail that can only be discarded rather than deferred, and an address update that deletes the row other tables point at.
- Orders — a cursor that silently drops rows written in the same second, state that moves only as a side effect of documents, and money and discount summed over different subsets of the same rows.
Each gets its own write-up later in the year; the findings are already published, which is the next section.
Layer 3 — sequencing. The order rules that span endpoints: children before configurable parents, options before links, structural import before prices and stock, catalog before customers before orders. These are project knowledge, not API knowledge.
Layer 2 is where the skills actually live, and the useful unit turned out to be one skill per endpoint group — flow and pitfalls in prose, no routes and no payloads. That set is public as magento-integration-skills, MIT-licensed, eleven skills: an orchestrating magento-integration-flow, two cross-cutting ones — -querying for the read path and -async-bulk for the queued write path — and -catalog-structure, -attributes, -media, -prices-stock, -categories, -customers, -orders and -fulfilment.
It is Layer 2 and Layer 3 only, deliberately. It will not tell you a route, a field name or a payload — for the reason above, those belong to the install and rot on the first upgrade. It will tell you what a route does that its declaration does not.
Two refinements the later passes forced:
The unit is not always the endpoint group. Read mechanics were written into three skills at once before being extracted, because filter combination and paging behave identically whatever entity is read — while family-specific read facts stayed with their family. And the order wave split by direction of work instead: the poll loop in one skill, the documents an integration writes in another. Almost every project needs the first and only some own the second.
The set drifts from its own sources, and the drift is silent. The order wave was verified and written while the skill set still carried nothing about orders — a search for invoice, shipment or reservation across it came back empty — and its own documentation went on claiming customer coverage was deliberately absent weeks after the customer skill shipped. Nothing failed; the set simply read as complete while it was not. Harvesting a finding into the skill is a step somebody has to actually run, and it belongs in a checklist rather than in anyone’s memory.
Keeping them free of concrete calls is not squeamishness, and the tradeoff is deliberate: the skill will never hand you a request body, and in exchange nothing in it expires when a field is renamed. It is what makes them survive a version bump, and it forces the content to be the part that transfers: that a success status is not proof of storage, that idempotency is per-endpoint, that two adjacent endpoints have opposite error models.
What would still be needed
Being concrete about the gap, because "write a skill" hides most of the work:
1. Behavioural coverage, and it has to go past the catalog. The catalog was the easy half; customers and orders were executed too, and orders produced the sharpest version of the whole argument. Order state transitions have no declarative representation anywhere — no endpoint sets an order’s state, three calls are the only direct transitions, and every other move is a side effect of creating a document. The endpoint that looks like the status setter validates against the store’s configured state-to-status mapping, which is configuration rather than API surface. No amount of reading the definitions produces any of that.
What is still open is narrower. Payment behaviour was measured against a stand-in gateway whose calls always succeed, so what the skill records is Magento’s bookkeeping and not any provider’s — a provider module can push an order into review, capture from a webhook, or invoice by itself, and none of that generalises. The skill therefore carries a per-method test pass rather than a table of answers. Beyond that: the Commerce-only surface, and behaviour at scale.
2. A harness, not a habit. The verification here was manual curl against a DDEV sandbox. To keep a skill honest across Magento versions it needs to be a runnable suite: fixtures, assertions on status and stored state, and a report of what changed between 2.4.8 and 2.4.9. Half the corrections in that pass exist because a claim was true in 2.3 and quietly stopped being true — that will happen again, to these claims. The drift described above is the second argument for the same thing: a suite that runs is also the only mechanism that notices a skill has fallen behind the articles it was written from.
3. Version-aware facts. Nearly every behavioural row needs a version qualifier. category_ids working, pageSize being honoured, duplicate option labels being rejected, RabbitMQ not being required — all are current behaviour, several of them contradicting documentation that was correct when written. A skill that states them flatly will be wrong on older installs.
4. Third-party reality. A stock install is not a real one. Elasticsuite alone adds sixteen columns to catalog_eav_attribute, none reachable over REST. The generated layer should be built from the project’s vendor tree, not from a reference install, and the skill needs to say what a module added and whether the API can see it.
5. A negative corpus. The most valuable thing here is not the list of endpoints, it is the list of plausible-but-wrong beliefs: that category_links replaces, that async/bulk needs RabbitMQ, that an out-of-set attribute is written but hidden, that duplicate options accumulate. A skill needs those as explicit anti-facts, because they are what a model trained on years of forum posts will otherwise say. The set now carries them as exactly that, and the later waves added more — that category_ids in custom_attributes is ignored on write (it assigns), and that an administrator credential cannot create an order for a known customer (the cart sequence does, behind an ordinary permission). Anti-facts age in the safest direction of anything in a skill: a belief that was wrong stays worth naming even after the behaviour changes, because the folklore does not update.
6. The access surface. Credential choice and lifetime, the deprecated bearer shortcut, permission scoping, the unauthenticated surface — and the fact that configuration can rewrite a route’s permission at runtime, so no static reading of the declarations settles it.
7. Documentation gaps worth encoding. Skimming the vendor documentation surfaced two things no amount of source reading would have prioritised: the anonymous-access setting above, and two condition types (moreq, nfinset) that most third-party write-ups omit entirely. A skill built only from source inherits source’s blind spots; a skill built only from documentation inherits its omissions. Both, then check.
8. The judgement layer, which stays human. Which subtree the ERP owns, whether a store view is allowed its own photography, whether a feed may create attributes at all. The API permits all of these; nothing in it says whether they are a good idea.
Layer 1 is an afternoon. Layers 2 and 3 are the work, and they are only trustworthy to the extent someone ran them.
Verification record
Counts measured 2026-08-25 against magento2-sandbox: Magento Open Source 2.4.8-p5, Luma + sample data, production mode, with Elasticsuite 2.12.1.1 and a handful of first-party modules installed — so it is not a clean-core baseline, though the breakdown below puts the non-core contribution at two routes. Routes, services, verbs and ACL references were parsed from vendor/magento//etc/webapi.xml, vendor/smile//src//etc/webapi.xml and app/code///etc/webapi.xml; DTO count from vendor/magento//Api/Data/*Interface.php. The docblock-to-description chain was read from that install’s own vendor tree: Generator.php takes an operation’s description from $methodData['documentation'], ClassReflector::extractMethodDescription() reads it from the method’s docblock and throws when that docblock is empty, and TypeProcessor::getParamDescription() reads each parameter’s @param text.
A correction made during the pass, and it is the useful part of this section. The first export came back with 45 paths whatever credential was sent, and the conclusion drawn from it — that the export is a fragment of the API — was wrong. Re-measured with a freshly issued token:
| Credential on the schema request | Paths | Definitions |
|---|---|---|
| None | 45 | 120 |
| Integration token, catalog only | 71 | 158 |
| Administrator token | 325 | 399 |
Against the install’s declarations — 432 routes across 344 distinct URL templates — the administrator export carries 410 operations across 325 paths, about 95% of the surface. Not a fragment.
That first measurement was served anonymously: the token had outlived its four-hour lifetime, and the endpoint answered the unauthenticated request with a valid, smaller schema rather than an error. A successful response to an unauthenticated request was indistinguishable from a successful response to an authenticated one — the same silent-failure class the skills document, committed here while documenting it, and it survived a round of review.
Two things that looked open and are not. The explicit service list has a documented form after all: Magento\Framework\Webapi\Request::_convertRequestParamToServiceArray() validates the parameter against /^([a-zA-Z\d]V[\d]+)(,[a-zA-Z\d]V[\d]+)$/ — comma-separated service names, alphanumeric, each ending in a version suffix, as in customerCustomerRepositoryV1. A name that matches the pattern but no known service yields an empty schema rather than an error, which is exactly what the 0-path result was. And the install’s module set is not a mystery: app/etc/config.php declares 420 modules with 416 enabled, of which 43 sit outside the Magento_ namespace — Elasticsuite, PayPal Braintree, and first-party modules under development. Of the 432 routes counted, 430 are declared by Magento_ core modules; Elasticsuite contributes one and a first-party module in app/code contributes one. The totals are the stock surface plus two routes.
And one correction to the count itself, found while checking that. The parse covered vendor/magento/, vendor/smile/ and app/code/, so it missed vendor/paypal/ — Braintree ships bundled with Open Source and declares two routes, /V1/applepay/auth and /V1/braintree/mine/payment/vault. Counting it, the install declares 434 routes across 38 files and 346 distinct URL templates; the 432 / 37 / 344 figures above are the three-bucket parse, which is what every percentage here is calculated against.
Still not verified: whether the administrator export’s 325 paths move on an install with a different module mix — they must, marginally — and no fresh export was taken for this revision.
Related reading
- Magento Integration Skills — the eleven skills this article argues for, installable today.
- Magento 2 REST API Gaps: What’s Missing and How to Fill It — the endpoints that are not declared anywhere, because they do not exist.
- Magento 2 searchCriteria: The Complete Reference — the read side, in the detail the skills deliberately leave out.
