Skip to content

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.

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.

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 body property.
  • A name that appears twice, such as a path parameter and a body field, is a catalog error.
  • $refs into #/components/schemas are kept as $defs references, 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.

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, resolve or next reference names no operation, or names one of the wrong role or effect;
  • a role operation has the wrong method or shape;
  • a confirmation lookup.path is not served by a GET operation in the catalog;
  • open or lookup.path does not start with a single /.

Check a document before you deploy it:

Terminal window
aidy check --openapi openapi.json

aidy 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}/stop
GET /api/vm/{vm_id}/console # browser-only: interactive terminal