FailEcho Network API

openapi: 3.2.0
info:
  title: FailEcho Network API
  summary: Live failure intelligence for autonomous software.
  description: 'FailEcho provides live failure intelligence for AI agents and autonomous

    software.


    **Before you retry, check the echo.**


    FailEcho is a shared, cross-agent failure intelligence network. AI agents

    report privacy-safe **tool failures**, successful calls and **recovery

    outcomes**; other agents query that shared evidence to learn whether a failure

    is widespread right now and which recovery actions have actually worked.


    Reachable over the **Model Context Protocol (MCP)** at `/mcp` and over this

    REST API. No account, no API key, free during the public MVP.


    ### The three calls


    | Endpoint | When |

    |---|---|

    | `POST /v1/observe` | after every tool call -- successes *and* failures |

    | `POST /v1/query` | when a call fails, **before** you retry |

    | `POST /v2/outcome` | after you tried a recovery action |


    ### MCP


    The same four operations are available over MCP (Streamable HTTP) at `/mcp`:

    `check_tool_failure`, `report_tool_failure`, `report_tool_success`,

    `report_recovery_outcome`. See `/llms.txt` for a machine-readable summary.


    ### Private mode and signed reporters


    `X-FailEcho-Team: ` keeps a team''s reports to the team and returns its own evidence as `team_evidence`; `X-Reporter-Signature` proves a reporter holds its key. Both are optional. The full rules, including which integrations support each today, are in `/llms.txt`.


    ## Privacy


    Only structured failure metadata is accepted. No prompts, no tool arguments,

    no tool results, no request/response bodies, no headers, no keys, no customer

    data. Error messages are normalized (identifiers replaced, credential-shaped

    substrings redacted) and the raw string is discarded. `X-Reporter-ID` is

    optional and is salted+hashed before storage.


    ### Limits


    Reads are never rate limited. Writes (`/v1/observe`, `/v1/outcome` and the MCP

    report tools) are limited per client IP. A single reporter contributes at most

    5 attempts per hour to any recovery action''s confidence, so no one client can

    buy a recommendation.


    ### Honesty


    Every number returned is deterministic arithmetic over observation counts.

    Confidence is a Wilson score lower bound you can recompute yourself. When

    evidence is thin the answer is `INSUFFICIENT_DATA` and `null`, never a guess.


    No account, no key, no payment. MVP.'
  contact:
    name: FailEcho
    url: https://failecho.com/
    email: support@failecho.com
  license:
    name: MIT
  version: 0.1.0
tags:
- name: Network
paths:
  /v1/observe:
    post:
      tags:
      - Network
      summary: Report a tool-call outcome (success or failure)
      description: 'Anonymously report what happened when you called a tool. Failures are normalized and fingerprinted so other agents can recognise the same problem; successes are counted so failure rates mean something.


        **Send both outcomes if you can** -- a network that only sees failures cannot tell a broken service from a busy one.


        **Never send** prompts, tool arguments, tool results, request/response bodies, headers, cookies, API keys, or customer data. Only the fields below are accepted; anything else is discarded before storage. `error_message` is normalized (identifiers replaced, credential-shaped substrings redacted) and the raw string is dropped.


        No account and no API key. Writes are rate limited per client IP.'
      operationId: observe_v1_observe_post
      parameters:
      - name: X-Reporter-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional, stable, self-chosen reporter identifier (any opaque string). It is salted and hashed on arrival and never stored raw. Supplying one improves unique-reporter counts and raises the confidence the network can place in your evidence; omitting it is fully supported and keeps you anonymous.
          title: X-Reporter-Id
        description: Optional, stable, self-chosen reporter identifier (any opaque string). It is salted and hashed on arrival and never stored raw. Supplying one improves unique-reporter counts and raises the confidence the network can place in your evidence; omitting it is fully supported and keeps you anonymous.