# BRAINIAC Agent Contracts Idempotency Audit

> BRAINIAC Agent Contracts Idempotency Audit is a paid API for AI agents from www.brainiac.software, paid per call via x402, $0.04/call, status unknown (last checked 2026-11-11).

Audits agent contract definitions (OpenAPI specs, workflows, operations) for missing or contradictory idempotency documentation, scoring and listing issues that could cause duplicate actions on retry.

## Facts

- Endpoint: POST https://www.brainiac.software/api/v1/agent-contracts/idempotency-audit?utm_source=zero.xyz
- Price: $0.04/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/brainiac-agent-contracts-idempotency-audit-1e9bb4b4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_LE4Nqj2Tk01XjnIwQx61Y

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability brainiac-agent-contracts-idempotency-audit-1e9bb4b4 -d '<json body>'
```

Example prompt: Audit my agent contract for idempotency problems — here's my OpenAPI spec and two workflows: a 'create-order' workflow with steps for checking inventory and placing a charge, and a 'send-notification' workflow. Flag any operations missing idempotency key documentation or with contradictory replay rules, and give me a score.

## When to prefer this

Use this endpoint when you need automated, structured detection of idempotency documentation gaps and contradictions in agent-facing API contracts before deployment or marketplace listing. Prefer it over manual review when you have machine-readable OpenAPI specs or workflow definitions and need a scored, actionable report highlighting exactly which operations could cause duplicate side effects on agent retry. It is particularly valuable for payment, order, messaging, or any state-mutating operation where duplicate execution is costly.

## Known failure modes

- Malformed or missing required input fields result in validation errors
- Operations with implicit idempotency (not textually stated) are flagged as missing even if the server is safe
- Contradictions are reported from text alone and may not reflect actual server behavior
- Truncated or very large OpenAPI documents may exceed schema limits (maxItems, maxLength constraints)
- Fixed-phrase matching may miss unconventional idempotency language not matching expected vocabulary

## How this service works

Pay-per-call APIs for AI agents: OFAC sanctions screening, compliance checks, token security, and Base chain data via x402. No account. Fixed USDC price. MCP-ready.

## Output

Returns a JSON object with a numeric idempotency score (0-100), a success flag, an analysis summary string, a list of issues each containing type, severity (high/medium/low), location within the input, evidence text, description, agent impact, and suggested fix, plus warnings and limitations arrays explaining what the checker can and cannot infer.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "openapi": {
   "type": "object",
   "propertyNames": {
    "type": "string",
    "maxLength": 80
   },
   "additionalProperties": {}
  },
  "workflows": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "name": {
      "type": "string",
      "maxLength": 160,
      "minLength": 1
     },
     "steps": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "name"
       ],
       "properties": {
        "name": {
         "type": "string",
         "maxLength": 160,
         "minLength": 1
        },
        "operation": {
         "type": "string",
         "maxLength": 160
        },
        "description": {
         "type": "string",
         "maxLength": 4000
        }
       },
       "additionalProperties": false
      },
      "maxItems": 30
     },
     "states": {
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 80,
       "minLength": 1
      },
      "maxItems": 40
     },
     "description": {
      "type": "string",
      "maxLength": 8000
     },
     "transitions": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "from",
        "to"
       ],
       "properties": {
        "on": {
         "type": "string",
         "maxLength": 200
        },
        "to": {
         "type": "string",
         "maxLength": 80,
         "minLength": 1
        },
        "from": {
         "type": "string",
         "maxLength": 80,
         "minLength": 1
        },
        "operation": {
         "type": "string",
         "maxLength": 160
        }
       },
       "additionalProperties": false
      },
      "maxItems": 80
     }
    },
    "additionalProperties": false
   },
   "maxItems": 12
  },
  "operations": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "name": {
      "type": "string",
      "maxLength": 160,
      "minLength": 1
     },
     "path": {
      "type": "string",
      "maxLength": 400
     },
     "steps": {
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 200,
       "minLength": 1
      },
      "maxItems": 20
     },
     "method": {
      "type": "string",
      "maxLength": 16
     },
     "summary": {
      "type": "string",
      "maxLength": 1000
     },
     "examples": {
      "type": 
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "score": 55,
  "issues": [
   {
    "type": "missing_idempotency",
    "evidence": "Creates an order for the sku.",
    "location": "operations[0]",
    "severity": "high",
    "description": "The text says the operation creates or changes something, and it does not name an idempotency key or a replay result. This is missing documentation, not proof of a duplicate write.",
    "agent_impact": "An agent that retries can create a second charge, order, or message because the contract never says what a repeat does.",
    "suggested_fix": "Name an Idempotency-Key and say whether a replay returns the original result."
   },
   {
    "type": "contradictory_idempotency",
    "evidence": "Creates a payment. An Idempotency-Key returns the same payment on replay. Every call creates a new payment.",
    "location": "operations[1]",
    "severity": "high",
    "description": "The contract says a replay returns the same result and also says each call creates a new one. Both sentences are in the supplied text.",
    "agent_impact": "An agent cannot tell whether to reuse an idempotency key or to expect a second resource.",
    "suggested_fix": "Delete one of the two sentences so the replay result is unambiguous."
   }
  ],
  "success": true,
  "analysis": "Checked 3 operations for a stated create or update and a stated replay rule. No operation was marked idempotent unless the text says so.",
  "warnings": [],
  "limitations": [
   "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
   "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
   "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
   "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
   "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
   "A state change is a fixed verb such as create, update, delete, charge, send, submit, transfer, cancel, write, insert, or remove.",
   "Idempotency text is the word idempotent, Idempotency-Key, replay, or same result. A key name without that sentence stays a warning.",
   "Missing idempotency subtracts 20. A contradiction subtracts 25. Warnings do not change the score."
  ],
  "recommendations": []
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/brainiac-agent-contracts-idempotency-audit-1e9bb4b4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from www.brainiac.software](https://www.zero.xyz/host/www.brainiac.software/llms.txt)
