Guide

Correct a failed API command

A failed call gives you a concrete place to start: the requested command, its inputs, the response, and the execution log. Inspect those facts, change the generated catalog or connection setting that caused the failure, then retry the same call.

This guide assumes an imported catalog and a connected agent. Complete one API call first. Use a test endpoint when reproducing a failure that could change remote data.

Inspect the failure

Find the failing command with search_commands, then inspect it with get_command. Compare its HTTP method, path, required inputs, and selected base URL with the provider documentation. In the TUI, inspect the response and execution logs for the same call.

A 401 response may point to missing or expired credentials. A 404 may point to the wrong path or base URL. Those are diagnostic clues, not automatic repair decisions. Verify the cause against the API documentation and response.

Change the specific setting

For a wrong base URL, use catalog_set_base_url. For request headers, use catalog_get_masked_headers to inspect names and masked values, then catalog_edit_headers to change the required entries. Do not put credentials into a public example or log.

For a wrong generated command definition, use catalog_apply_patch. Supply the catalog title, a strict match_command key with group, name, HTTP method, and path, and the full corrected replacement_command. Inspect the exact command first so the replacement preserves the fields the operation still needs.

{
  "catalog_id": "<catalog title>",
  "operations": [{
    "match_command": {
      "group": "<group>",
      "name": "<command name>",
      "http_method": "<current method>",
      "http_path": "<current path>"
    },
    "replacement_command": { "...": "<complete corrected command definition>" }
  }]
}

The example shows the request shape, not a runnable patch. The replacement must use the complete command definition returned for your actual catalog. A missing or ambiguous match returns a structured error; recheck the command identity before retrying the patch.

Retry and verify

Run get_command again to confirm the selected definition or connection setting. Retry the same operation with the same inputs. Compare the new response with the failed response and the API's documented result. Find the operation in the TUI and run it there if you need direct confirmation.

catalog_apply_patch replaces a generated command in Oatty's catalog. It does not edit the provider's original OpenAPI document. If the document itself is invalid, correct the source and import it again.