The catalog
The catalog is the set of operations aidy may call. It is your OpenAPI 3.1 document: an
operation joins the catalog when it carries an x-aidy object, and operations without one are
invisible to aidy.
"/api/vm/{vm_id}/stop": { "post": { "operationId": "stopVm", "summary": "Stop server", "x-aidy": { "name": "stop_vm", "title": "Stop server", "description": "Stop a running cloud server (VM).", "effect": "update", "open": "/console/instance/{vm_id}", "confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" } } } }}aidy fetches the document from host.openapi with the user’s credential, so a host may show
different users different catalogs. GET /aidy/v0/catalog lists the operations visible to the
caller.
Naming an operation
Section titled “Naming an operation”name is the only required key. It matches ^[a-z][a-z0-9_]{0,63}$, is unique in the
catalog, and is used everywhere:
| Where | Spelling |
|---|---|
| Agent tool and MCP tool | stop_vm |
| CLI command | stop-vm, or the words in cli.command (vm stop) |
Assertion claim op |
stop_vm |
title labels approval cards, activity rows and CLI help. It defaults to the OpenAPI
summary, then name. description is what the model reads: name the resource and its
common synonyms (“cloud server (VM)”). It defaults to the summary.
The other keys are covered on their own pages:
| Keys | Page |
|---|---|
effect, approval, surfaces, redact, repeatable, timeoutSeconds, open, cli |
Operations and effects |
confirmation |
Approvals |
form |
Forms |
resolve |
Resolve |
next |
Chains |
role |
Identity, Search and knowledge, Forms |
The full list is in the x-aidy reference.
The derived operation
Section titled “The derived operation”aidy normalizes each annotated operation into one input schema. The model, MCP clients and the CLI all see the same schema.
- Path and query parameters become top-level properties.
- An object request body is flattened into top-level properties. Any other body becomes one
bodyproperty. - A name that appears twice, such as a path parameter and a body field, is a catalog error.
$refs into#/components/schemasare kept as$defsreferences, so recursive schemas stay valid.
For POST /api/vm/{vm_id}/stop with the body {"forced": boolean}, the derived input is:
{ "type": "object", "properties": { "vm_id": { "type": "string" }, "forced": { "type": "boolean", "default": false } }, "required": ["vm_id"]}When aidy calls the operation, it splits the arguments back into the path, the query and the
body. Before a call, arguments are coerced (a JSON string to an object or array, a numeric
string to a number) and validated against this schema. Invalid arguments go back to the model as
invalid_arguments and never reach your API.
Validation
Section titled “Validation”aidy validates the catalog when it loads it. Unknown x-aidy keys are rejected, and so are
catalogs where:
- a name is duplicated;
- a
form,resolveornextreference names no operation, or names one of the wrong role or effect; - a role operation has the wrong method or shape;
- a confirmation
lookup.pathis not served by aGEToperation in the catalog; openorlookup.pathdoes not start with a single/.
Check a document before you deploy it:
aidy check --openapi openapi.jsonaidy check prints every catalog issue and exits 1 when there is any. With --routes, it also
takes a list of the METHOD /path requests your UI makes, one per line, and fails for each one
no catalog operation serves, unless the line is marked # browser-only: <reason>. That keeps
the agent able to do what your UI does.
GET /api/vm/{vm_id}POST /api/vm/{vm_id}/stopGET /api/vm/{vm_id}/console # browser-only: interactive terminalRelated
Section titled “Related”x-aidyreference- Operations and effects
- CLI guide for
aidy check,skill,llmsanddocs